In the OPCDA.NET Professional Edition this method is available also for OPCDA V2 servers. With OPCDA V2 servers the method is emulated by calling the available OPCDA V2 browse methods.
It is assumed that the underlying server address space is hierarchical. A flat space will always be presented to the client as not having children. A hierarchical space can be presented to the client as either not having children or having children. A hierarchical presentation of the server address space would behave much like a file system, where the directories are the branches or paths, and the files represent the leaves or items. For example, a server could present a control system by showing all the control networks, then all of the devices on a selected network, and then all of the classes of data within a device, then all of the data items of that class. A further breakdown into vendor specific ‘Units’ and ‘Lines’ might be appropriate for a BATCH system.
The browse position is initially set to the ‘root’ of the address space. On subsequent calls, the client may choose to browse from the continuation point. This browse can also be filtered by a vendor specific filter string. The itemID must be the value of ItemID returned with a BrowseElement from a previous call to browse or an empty string (used to indicate a top level browse). The ItemID is a fully qualified descriptor for the element that can be used for further browsing and as an item id if BrowseElement.IsItem is set. Note, that it is possible for a single element to be both an item and have children (e.g. complex data items). If the level specified ItemID is valid, but does not have any children, then the Browse will succeed, but the result will be a zero length BrowseElements array.
If the filter criteria result in an empty result, then the Browse will still succeed.
Syntax
| Visual Basic (Declaration) | |
|---|---|
Public Function Browse( _ ByVal itemID As String, _ ByRef continuationPoint As String, _ ByVal maxElements As Integer, _ ByVal mode As browseFilter, _ ByVal elementFilter As String, _ ByVal vendorFilter As String, _ ByVal returnProperties As Boolean, _ ByVal returnValues As Boolean, _ ByVal propertyIDs() As Integer, _ ByRef moreElements As Boolean _ ) As BrowseElement() | |
| C# | |
|---|---|
public BrowseElement[] Browse( string itemID, ref string continuationPoint, int maxElements, browseFilter mode, string elementFilter, string vendorFilter, bool returnProperties, bool returnValues, int[] propertyIDs, out bool moreElements ) | |
Parameters
- itemID
- The name of the branch in the hierarchy to browse. If the root branch is to be browsed then a NUL string is passed.
- continuationPoint
- If this is a secondary call to Browse, the previous call might have returned a Continuation Point where the Browse can restart from. Clients must pass a NUL string in the initial call to Browse. This is an opaque value, which the server creates. A Continuation Point will be returned if a Server does support Continuation Point, and the reply is larger than dwMaxElementsReturned. The Continuation Point will allow the Client to resume the Browse from the previous completion point.
- maxElements
- Server must not return any more elements than this value. If the server supports Continuation Points, then the Server may return a Continuation Point at a value less than dwMaxElementsReturned. If the server does not support Continuation Points, and more than dwMaxElementsReturned are available, then the Server shall return the first dwMaxElementsReturned elements and set the pbMoreElements parameter to TRUE.
If dwMaxElementsReturned is 0 then there is no client side restriction on the number of returned elements. - mode
- An enumeration {All, Branch, Item} specifying which subset of browse elements to return. See the table in the comments section below to determine which combination of bits in BrowseElement.dwFlagValue are returned for each value in browseFilter.
- elementFilter
- A wildcard string that conforms to the Visual Basic LIKE operator, which will be used to filter Element names. A NUL String implies no filter.
- vendorFilter
- A server specific filter string. This is entirely free format and may be entered by the user via an EDIT field. A pointer to a NUL string indicates no filtering.
- returnProperties
- Server must return all properties which are available for each of the returned elements. If true, pdwPropertyIDs is ignored.
- returnValues
- Server must return the property values in addition to the property names.
- propertyIDs
- An array of Property IDs to be returned with each element. If bReturnAllProperties is true, pdwPropertyIDs is ignored and all properties are returned.
- moreElements
- If the Server does not support a Continuation Point then the server will set pbMoreElements to True if there are more elements than dwMaxElementsReturned.