This ObjectType represents a FileType the can be used to access a PubSub configuration. The PubSubConfigurationType is formally defined in Table 211.
The PubSubConfigurationType file is a UA Binary encoded stream containing an instance of UABinaryFileDataType that contains a PubSubConfiguration2DataType or subtype as Body. The UABinaryFileDataType is defined in OPC 10000-5. The PubSubConfiguration2DataType is defined in 6.2.12.4. The indices of the namespaces in the PubSubConfiguration2DataType and the Namespaces in the DataTypeSchemaHeader of the UABinaryFileDataType shall match the NamespaceArray in the OPC UA Server for a Session with the Server.
The FileType functionality is used instead of passing the PubSubConfiguration2DataType to read and write Methods to overcome potential limitations of communication buffers for OPC UA Service calls. It is expected that the PubSubConfiguration2DataType is used internally in Client and Server and that the FileType is only used to be able to transfer large configurations.
The Open Method shall not support modes other than Read (0x01), Write + EraseExisting (0x06) and Read + Write (0x03).
When a Client opens the file for writing the Server will not actually update the PubSub configuration until the CloseAndUpdate Method is called. Simply calling Close will discard the updates.
When a Client opens the file for reading and writing, the Client shall follow the following steps.
- Read the existing configuration with the FileType Read Method.
- Set the position to the beginning of the file with the FileType SetPosition Method.
- Write the changes with the FileType Write Method.
- Apply the changes with the CloseAndUpdate Method.
Access to the PubSub configuration may be used by multiple Clients in parallel. Read access can be done in parallel but open with the Write flag set requires exclusive access. Therefore Clients that have the file open should minimize the time the file is open to the currently required actions. The Client shall close the file as soon as it completes the sequence of actions needed to read or write the file. Clients with a user interface shall not keep the file open for user configuration. Such Clients should read and close the file to initialize the user interface. If the user changes should be written to the PubSub configuration, the Client should open the file with Read + Write (0x03), read the file, compare the version information and then write the changes if the version matches the version from the intial read.
Table 211 – PubSubConfigurationType definition
|
Attribute |
Value |
||||
|
BrowseName |
PubSubConfigurationType |
||||
|
IsAbstract |
False |
||||
|
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
ModellingRule |
|
Subtype of FileType defined in OPC 10000-20. |
|||||
|
HasComponent |
Method |
ReserveIds |
Defined in 9.1.3.7.5. |
Mandatory |
|
|
HasComponent |
Method |
CloseAndUpdate |
Defined in 9.1.3.7.6. |
Mandatory |
|
|
Conformance Units |
|||||
|
PubSub Model Base |
|||||
This OptionSet defines flags indicating the PubSubConfigurationRefDataType options. The value of the mask is null, if none of the bits is set.
The PubSubConfigurationRefDataType is used to reference a configuration element in a PubSubConfiguration2DataType structure. The PubSubConfigurationRefDataType indicates the element type referenced and defines the operation to be executed for the referenced configuration element. The possible element operations are ElementAdd, ElementMatch, ElementModify and ElementRemove.
Only one of the reference bits shall be set. If more than one of these bits are set, the operation shall fail.
The PubSubConfigurationRefMask values are formally defined in Table 212.
Table 212 – PubSubConfigurationRefMask values
|
Value |
Bit No. |
Description |
|
ElementAdd |
0 |
If this bit is set, the referenced elements is added to the PubSub configuration. If the name of the element is null or empty a name is assigned. If the PublisherId is null, the default PublisherId for the transport profile is assigned. If WriterGroupId or DataSetWriterId are null, unique IDs are assigned. If this bit is set, the ElementModify and ElementRemove bits shall be false. If more than one of these bits are set, the operation shall fail. |
|
ElementMatch |
1 |
If this bit is set, the Id and name shall be null and a matching element is searched. This is used to add children to an existing parent configuration object. This flag can be combined with the ElementAdd flag to either use an existing element or to add the element if it does not exist. Match shall only be applied for ReferenceConnection, ReferenceWriterGroup and ReferenceReaderGroup. For all other references the match shall fail with Bad_InvalidArgument. Match applied to ReferenceWriterGroup shall return Bad_InvalidState if the GroupHeader is active for the WriterGroup. For the PubSubConnectionDataType, the following structure fields are used for the match, the others are ignored. For the WriterGroupDataType, the following structure fields are used for the match, the others are ignored.
For the ReaderGroupDataType, the following structure fields are used for the match, the others are ignored.
For the ConnectionProperties and GroupProperties only the entries are compared for the match that are provided in the element to match. Additional properties contained in the existing configuration are ignored. |
|
ElementModify |
2 |
If this bit is set, the referenced element will be modified. The related element in the current PubSub configuration is referenced with matching the name of the elements. If no matching name is found, the element operation shall fail. |
|
ElementRemove |
3 |
If this bit is set, the referenced element will be removed. The related element in the current PubSub configuration is referenced with matching the name of the elements. If no matching name is found, the element operation shall fail. A successful removal of the referenced element shall include the removal of all associated child elements. |
|
ReferenceWriter |
4 |
The element operation is applied to the referenced DataSetWriter. |
|
ReferenceReader |
5 |
The element operation is applied to the referenced DataSetReader. |
|
ReferenceWriterGroup |
6 |
The element operation is applied to the referenced WriterGroup. |
|
ReferenceReaderGroup |
7 |
The element operation is applied to the referenced ReaderGroup. |
|
ReferenceConnection |
8 |
The element operation is applied to the referenced PubSubConnection. |
|
ReferencePubDataset |
9 |
The element operation is applied to the referenced PublishedDataSet. |
|
ReferenceSubDataset |
10 |
The element operation is applied to the referenced SubscribedDataSet. |
|
ReferenceSecurityGroup |
11 |
The element operation is applied to the referenced SecurityGroup. The access to the security groups may require different user credentials than access to the communication configuration elements. |
|
ReferencePushTarget |
12 |
The element operation is applied to the referenced PubSubKeyServerPushTarget. The access to the push target configuration may require different user credentials than access to the communication configuration elements. |
The PubSubConfigurationRefMask representation in the AddressSpace is formally defined in Table 213.
Table 213 – PubSubConfigurationRefMask definition
|
Attribute |
Value |
|||||
|
BrowseName |
PubSubConfigurationRefMask |
|||||
|
IsAbstract |
False |
|||||
|
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
ModellingRule |
|
|
Subtype of the UInt32 type defined in OPC 10000-5. |
||||||
|
0:HasProperty |
Variable |
OptionSetValues |
LocalizedText[] |
PropertyType |
|
|
|
ConformanceUnits |
||||||
|
PubSub Model Base |
||||||
The PubSubConfigurationRefDataType allows to reference an element contained in the PubSubConfiguration2DataType Structure.
The PubSubConfigurationRefDataType is formally defined in Table 214.
Table 214 – PubSubConfigurationRefDataType structure
|
Name |
Type |
Description |
|
PubSubConfigurationRefDataType |
Structure |
|
|
ConfigurationMask |
PubSubConfigurationRefMask |
Specifies the add, match, modify or remove element operation and the type of configuration element that is referenced. |
|
ElementIndex |
UInt16 |
Specifies the index into the DataSetWriters, DataSetReaders, PublishedDataSets, SubscribedDataSets, SecurityGroups or PubSubKeyPushTargets array of the PubSubConfiguration depending on the bits ReferenceWriter, ReferenceReader, ReferencePubDataset, ReferenceSubDataset, ReferenceSecurityGroup or ReferencePushTarget. If this index is not used for referencing, it shall be set to 0. |
|
ConnectionIndex |
UInt16 |
Specifies the index within the Connections array of the PubSubConfiguration if the connection, group, reader or writer bits is set. If ReferenceConnection is true, the add, modify or remove element operation is applied. If ReferenceConnection is false, the name of the connection is used to identify the matching connection in the current PubSub configuration. If this index is not used for referencing, it shall be set to 0. |
|
GroupIndex |
UInt16 |
If the ReferenceReaderGroup and/or ReferenceReader bits are true, it speficies the index within the ReaderGroups array of the related connection. If ReferenceReaderGroup is true, the add, modify or remove element operation is applied. If ReferenceReaderGroup is false, the name of the ReaderGroup is used to identify the matching group in the current PubSub configuration. If the ReferenceWriterGroup and/or ReferenceWriter bits are true, it specifies the index within the WriterGroups array of the related connection. If ReferenceWriterGroup is true, the add, modify or delete bit is applied. If ReferenceReaderGroup is false, the name of the ReaderGroup is used to identify the matching group in the current PubSub configuration. If this index is not used for referencing, it shall be set to 0. |
The PubSubConfigurationRefDataType representation in the AddressSpace is formally defined in Table 215.
Table 215 – PubSubConfigurationRefDataType definition
|
Attribute |
Value |
|||||
|
BrowseName |
PubSubConfigurationRefDataType |
|||||
|
IsAbstract |
False |
|||||
|
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
ModellingRule |
|
|
Subtype of Structure defined in OPC 10000-5. |
||||||
|
ConformanceUnits |
||||||
|
PubSub Model Base |
||||||
The PubSubConfigurationValueDataType allows to indicate specific values contained in PubSubConfiguration elements.
The PubSubConfigurationValueDataType is formally defined in Table 216.
Table 216 – PubSubConfigurationValueDataType structure
|
Name |
Type |
Description |
|
PubSubConfigurationValueDataType |
Structure |
|
|
ConfigurationElement |
PubSubConfigurationRefDataType |
Refers to a configuration element in the related PubSubConfiguration2DataType Structure. |
|
Name |
String |
The name of the referenced PubSub configuration element. |
|
Identifier |
BaseDataType |
The identifier value used for the referenced element in the PubSub NetworkMessages. The value is only provided if the element is a PubSubConneciton, WriterGroup or DataSetWriter. The value is null otherwise. If ConfigurationElement references a PubSubConnection, Identifier will contain the value of the PublisherId. If ConfigurationElement references a WriterGroup, Identifier will contain the value of the WriterGroupId. If ConfigurationElement references a DataSetWriter, Identifier will contain the value of the DataSetWriterId. |
The PubSubConfigurationValueDataType representation in the AddressSpace is formally defined in Table 217.
Table 217 – PubSubConfigurationValueDataType definition
|
Attribute |
Value |
|||||
|
BrowseName |
PubSubConfigurationValueDataType |
|||||
|
IsAbstract |
False |
|||||
|
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
ModellingRule |
|
|
Subtype of Structure defined in OPC 10000-5. |
||||||
|
ConformanceUnits |
||||||
|
PubSub Model Base |
||||||
This Method reserves unique WriterGroupIds and DataSetWriterIds to allow PubSub configuration applications to apply unique Ids to new PubSub configuration elements when preparing a update to the PubSub configuration. It also returns the related default PublisherId. See 6.2.7.1 for more details on PublisherId and default values.
The ID shall be returned from the range 0x8000 - 0xFFFF for internal assignment. The Server shall ensure that the IDs returned are not used in the current PubSub configuration or are not reserved yet.
When a Client reserves IDs, these reservations are valid while the Session is open. The reserved IDs can only be used for configuration modifications through the same Session. The reservation is only valid until the ID is used in the configuration or until the Session is closed. The IDs can be re-used if a PubSub component that uses the ID is deleted.
The Client shall be authorized to modify the configuration for the PubSub functionality when invoking this Method on the Server.
Signature
ReserveIds (
[in]String TransportProfileUri,
[in]UInt16 NumReqWriterGroupIds,
[in]UInt16 NumReqDataSetWriterIds,
[out]BaseDataTypeDefaultPublisherId,
[out]UInt16[] WriterGroupIds,
[out]UInt16[] DataSetWriterIds
);
|
Argument |
Description |
|
TransportProfileUri |
Transport protocol and message mapping profile scope for the ID request. |
|
NumReqWriterGroupIds |
The number of requested Ids for WriterGroups. |
|
NumReqDataSetWriterIds |
The number of requested Ids for DataSetWriters. |
|
DefaultPublisherId |
The default PublisherId of the Server for the requested TransportProfileUri. |
|
WriterGroupIds |
The reserved Ids for WriterGroups for the requested TransportProfileUri. |
|
DataSetWriterIds |
The reserved Ids for DataSetWriters for the requested TransportProfileUri |
Method Result Codes
|
ResultCode |
Description |
|
Bad_UserAccessDenied |
The Session user is not allowed to modify the PubSub configuration. |
|
Bad_ResourceUnavailable |
The requested number of Ids cannot be reserved. The maximum number of WriterGroups and DataSetWriters are exposed in the PubSubCapabilities Object. |
Table 218 specifies the AddressSpace representation for the ReserveIds Method.
Table 218 – ReserveIds Method AddressSpace definition
|
Attribute |
Value |
||||
|
BrowseName |
ReserveIds |
||||
|
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
ModellingRule |
|
HasProperty |
Variable |
InputArguments |
Argument[] |
PropertyType |
Mandatory |
|
HasProperty |
Variable |
OutputArguments |
Argument[] |
PropertyType |
Mandatory |
|
ConformanceUnits |
|||||
|
PubSub Model Base |
|||||
This Method closes the file and applies the changes to the PubSub configuration as defined in the ConfigurationReferences argument. It can only be called if the file was opened for writing. If the Close Method is called any cached data is discarded and the PubSub configuration is not changed.
The file content shall be a UABinaryFileDataType with a PubSubConfiguration2DataType as Body. The ConfigurationReferences argument specifies the configuration elements to add, modify or remove. Configuration elements in PubSubConfiguration2DataType that are not referenced by ConfigurationReferences may be used indirectly as parent elements for referencing. In this case only the name of the element is relevant and all other fields of the element are ignored. Configuration elements in PubSubConfiguration2DataType not referenced and not used as parent elements are ignored.
Remove element operations shall be processed before any other operations are processed. The PubSubConfiguration2DataType may contain duplicate names for cases where elements are removed and added with the same name.
The top-level fields in the PubSubConfiguration2DataType are not referenced in ConfigurationReferences argument. Most of them are only relevant for the read case.
- The Enable field is ignored.
- The DataSetClasses field is ignored.
- The DefaultSecurityKeyServices field is ignored if the array is null or empty. If the array contains entries, the existing DefaultSecurityKeyServices are replaced with the new configuration.
- The ConfigurationVersion field is ignored. The ConfigurationVersion is updated to the current time after successful execution of CloseAndUpdate.
- The ConfigurationProperties field is merged with the existing ConfigurationProperties. If a key is provided with a value, the key is either inserted or it replaces the value of an existing key. If a key is provided with a null value, the key is deleted if it exists.
The Client shall be authorized to modify the configuration for the PubSub functionality when invoking this Method on the Server.
Signature
CloseAndUpdate (
[in]UInt32 FileHandle,
[in]Boolean RequireCompleteUpdate,
[in]PubSubConfigurationRefDataType[]ConfigurationReferences,
[out]Boolean ChangesApplied,
[out]StatusCode[] ReferencesResults,
[out]PubSubConfigurationValueDataType[] ConfigurationValues,
[out]NodeId[] ConfigurationObjects
);
|
Argument |
Description |
|
FileHandle |
The handle of the previously opened file. |
|
RequireCompleteUpdate |
If true, the modification is only applied if the all changes can be applied to all objects. |
|
ConfigurationReferences |
References to the PubSub configuration elements in the written file that should be added, modified or removed. |
|
ChangesApplied |
If true, one or more changes were applied. If RequireCompleteUpdate was set to false, the ReferencesResults argument indicates if referenced configuration elements failed. If false, no changes were applied. The detailed errors are provided in the ReferencesResults argument. |
|
ReferencesResults |
Results of the add, modify, match or remove operation for the referenced element. The length and order of the array shall match the ConfigurationReferences array. |
|
ConfigurationValues |
The assigned names and identifiers for the elements where empty names or null identifiers where provided in the elements. The values are only provided for elements with the bits ElementAdd or ElementMatch set and where a name and identifier was assigned. |
|
ConfigurationObjects |
NodeIds of the related Objects to referenced If NodeIds are returned, the length and order of the array shall match the ConfigurationReferences array. If the Server does not support the creation of NodeIds, the array is null or empty. |
Method Result Codes
|
ResultCode |
Description |
|
Bad_TypeMismatch |
The file content is not a UABinaryFileDataType with a PubSubConfiguration2DataType as Body. |
|
Bad_InvalidArgument |
The file handle is not valid. |
|
Bad_InvalidState |
The file was not opened for writer access. |
|
Bad_UserAccessDenied |
The Session user is not allowed to modify the PubSub configuration. |
|
Bad_NothingToDo |
The ConfigurationReferences array is null or empty. |
Element Result Codes
|
ResultCode |
Description |
|
Bad_BrowseNameDuplicated |
An element with the name already exists. The element cannot be added. |
|
Bad_NoMatch |
An element with the name does not exist or there is no element with matching parameters. The element cannot be matched, modified or removed. |
|
Bad_NotFound |
One of the parent elements does not exist or was not added or matched. The element cannot be processed. |
|
Bad_InvalidArgument |
The element reference is invalid or has invalid index entries. |
|
Bad_ResourceUnavailable |
The maximum number of supported elements is reached. |
|
Bad_InvalidState |
A WriterGroup with active GroupHeader was references with ElementMatch. |
|
Bad_UserAccessDenied |
The user has not the rights to access the element. |
Table 219 specifies the AddressSpace representation for the CloseAndUpdate Method.
Table 219 – CloseAndUpdate Method AddressSpace definition
|
Attribute |
Value |
||||
|
BrowseName |
CloseAndUpdate |
||||
|
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
ModellingRule |
|
HasProperty |
Variable |
InputArguments |
Argument[] |
PropertyType |
Mandatory |
|
HasProperty |
Variable |
OutputArguments |
Argument[] |
PropertyType |
Mandatory |
|
ConformanceUnits |
|||||
|
PubSub Model Base |
|||||