'Declaration<ComVisibleAttribute(False)> Public Interface IUAReadOnlyPubSubConfiguration
'UsageDim instance As IUAReadOnlyPubSubConfiguration
[ComVisible(false)] public interface IUAReadOnlyPubSubConfiguration
[ComVisible(false)] public interface class IUAReadOnlyPubSubConfiguration
This interface defines a set of methods for read-only access to the configuration of OPC UA PubSub entities, such as connections, writer groups, dataset writers, and published datasets. It is designed to allow applications to query and inspect the PubSub configuration without modifying it.
PubSub configuration describes the parameters of an OPC UA publisher and/or subscriber. It can be stored in a file, or it can be accessed through an information model in a "normal" OPC UA server.
Note that the use of PubSub configuration model is entirely optional. The model is standardized in OPC UA specifications, and when used, it must be used "as is". But, OPC UA publishers and subscribers may not use the configuration model at all, or they may choose to expose their configuration is some different way.
You can obtain the IUAReadOnlyPubSubConfiguration Interface by calling appropriate methods on the OPC UA Publish-Subscribe Client.
Most PubSub objects in the PubSub configuration are identified by their names. The name is usually a string, but some PubSub object are identified by an instance of UAQualifiedName Class.
Depending on the type of PubSub object and the structure of other arguments, sometimes a simple name of the PubSub object is enough to unambiguously locate it in the PubSub configuration. In other cases, the name is not sufficient, and a locator has to be used.
In this context, locator is a structure that consists of two or more names of PubSub objects. The names together unambiguously determine the location of the PubSub object in the PubSub configuration. For example, a dataset writer locator (represented by the UADataSetWriterLocator Class) contains
Published datasets are organized in a tree of dataset folders. Each published dataset has a name that must be unique not only in its dataset folder, but across the whole PubSub configuration. If a location of a published dataset in the PubSub configuration needs to be specified, a dataset folder path is used. The dataset folder path is a sequence of dataset folder names, starting from the root of the dataset folder tree.
Because published dataset names are unambiguous across the whole PubSub configuration, some methods allow you to omit the dataset folder path. In such case, you can pass a null reference in place of the dataset folder path, and the method will work on the whole tree. Note that a null reference in place of a dataset folder path is different from an empty path (a non-null, empty sequence): An empty dataset folder path denotes a "root" folder.
Some more information related to OPC UA PubSub configuration can be found in OPC UA PubSub logical identifiers.
The methods available on the PubSub configuration allow you to look up PubSub objects using various criteria, and retrieve their data. They are grouped into several categories.
PubSub objects can be looked up using their names. Methods that allow you to look up certain type of object in the PubSub configuration (sometimes given the location of their logical parent) are consistently called FindXXXX, where XXXX determines the type of PubSub object being looked up.
Attempt to look up an object that does not exist is not considered an error. When any of the FindXXXX does not find the PubSub object being looked up, it does not throw an exception. Instead, it simply returns a null reference. If the method call, however, contains argument that give location where the lookup is to be performed (e.g. the name of the PubSub connection when looking for a writer group), this location must be valid, otherwise an error occurs (UALogicalException Class).
List of the FindXXXX methods is below.
If you need to look for a published dataset (by its name) in a given dataset folder and its subfolders, use the SearchPublishedDataSet Method.
In most cases, you can use one of the FindXXXX methods to determine whether a certain PubSub object is present in the PubSub configuration. The PubSub object with the given name is present if the result of the FindXXXX method is not null. Alternatively, you can use one of the ListXXXX methods, and check whether the PubSub object name is among those returned.
You can use the above described approaches, except:
The methods to determine the PubSub object presence are consistently named HasXXXX, where XXXX determines the type of PubSub object being tested for existence.
If you do not know the names of certain PubSub objects, you can obtain the names from the PubSub configuration, usually given the location of some kind of logical parent. The methods that return the list of such names (or locators) are consistently called ListXXXX, where XXXX determines the type of PubSub object.
The methods below return names or locators of PubSub objects residing under a given parent.
There are also utility methods, built on top of others, that provide data about PubSub objects combined from multiple locations. They are briefly described below.
Methods that retrieve PubSub objects from the configuration are consistently named using the GetXXXX pattern. In most cases, a PubSub object can be retrieved by looking it up using one of the FindXXXX methods described above. For the remaining information in the PubSub configuration that cannot be accessed in this way, use one of the methods below.
The published dataset can optionally be associated with a published dataset source. The information about the published dataset source can be retrieved using the GetPublishedDataSetSourceElement Method. Because the published dataset source is optional, this method (and the methods that are derived from it - see further) returns null when the published dataset source is not configured - this is a difference from all other GetXXXX methods which never return null. The result of the GetPublishedDataSetSourceElement Method is polymorphic - its type depends on the type of the published dataset source, and it can be an instance of either UAPublishedDataItemsElement Class or UAPublishedEventsElement Class. If you know upfront which type of published dataset source you expect, you can use one of the extension methods, the GetPublishedDataItemsElement Method or GetPublishedEventsElement Method, to directly retrieve the desired type; they give an error if the actual type is not what you have coded for.
The methods below provide basically a functionality of the corresponding FindXXXX methods, with the difference that the PubSub object being looked up must exist; if not, the method gives an error. Consequently, in case of successful completion of any of these methods, the return value is never null.
Sometimes you need to retrieve information for all child objects under certain parent. This is, in fact, a combination of a ListXXXXNames method and one of the GetXXXXElement methods above. For convenience, QuickOPC provides (extension) methods for this functionality already. The return type is always a keyed collection of elements, where the key is the name. The methods in this group are given below.
The example below starts at the "root" of the PubSub configuration, and first obtains names of all PubSub connections available (they are at the 1st level). For each PubSub connection, given its name, it obtains names of writer groups configured on that PubSub connection (they are at the 2nd level). And, for each such writer group, given its name, it obtains names of all dataset writers configured on that writer group (they are at the 3rd level). Besides the PubSub object names, the commented parts also show how to obtain more detailed information about each PubSub object.
The example below uses the ListAllPublishedDataSetNames Method to retrieve all published dataset from the PubSub configuration. The published datasets are actually organized in the PubSub configuration using a hierarchical structure of dataset folders. The word "all" in the method name denotes that the method will truly return all published datasets in the configuration, not just those at the "root" of the dataset folder structure, or in any specified dataset folder. The method will act recursively in the dataset folder structure, if needed. There are also methods that allow you to work with contents of individual dataset folders. Note that the published dataset names are unique across the PubSub configuration as a whole (regardless of their location in the dataset folder structure), and therefore a published dataset name is sufficient to identify the published dataset, and the dataset folder path is not strictly necessary.