OPCServer Object

NOTE: Version 1.0 of this specification listed IEnumUnkown as an interface on the OPC Server. This was an error and has been removed. The semantics of QueryInterface do not allow such an implementation. The proper way to obtain a group enumerator is through IOPCServer::CreateGroupEnumerator.

A quick reference for this interface is provided below. A more detailed discussion can be found in the OPC Overview Document.

This interface must be provided, and all functions implemented as specified.
 
 

The server will create a group object, and return a pointer to the interface requested by the client. If the client requests an optional interface that the server does not support, the server is expected to return an error indicating the interface is not supported.

The requested update rate / revised update rate behavior should be deterministic between client / server sessions. The client expects that for the same server configuration or workspace; adding a group with a requested update rate will always result in the same RevisedRate independent of the number of clients or items that have been added.
 
 

The client should not call RemoveGroup without releasing all interfaces for the group. The client should also not release the server without removing all private groups.

Since the server is the ‘container’ for the groups it is permissible for the server to forcibly remove any remaining groups at the time all of the server interfaces are released. (This should not be necessary for a well behaved client).

See also the CreateGroupEnumerator function.

The level of localization supported (dwLCID) is entirely server specific. Servers which do not support dynamic localization can ignore this parameter.

See the MoveToPublic function for additional requirements related to public groups.

The default TimeBias for the group will be that of the system in which the group is created.
 
 
 
 
 
 

Note that if this method is called on a remote server, an RPC error may result. For this reason it is probably good practice for the client to attempt to call a local Win32 function if this function fails.

The expected behavior is that this will include handling of Win32 errors as well (such as RPC errors).

The Client must free the returned string.

It is recommended that the server put any OPC specific strings into an external resource to simplify translation.

To get the default value for the system, the dwLocale should be LOCALE_SYSTEM_DEFAULT.
 
 
 
 

The client must release the returned interface when it is done with it.

If needed, the client can obtain the hServerGroup Handle via IOPCGroupStateMgt::GetState.
 
 

Client must free the structure as well as the VendorInfo string within the structure.

Periodic calls to GetStatus would be a good way for the client to determine that the server is still connected and available.
 
 

In general, a well behaved client will call this function only after releasing all interfaces.

If interfaces still exist, Remove group will mark the group as ‘deleted’. Any further calls to this group via these interfaces will return E_FAIL. When all the interfaces are released, the group will actually be deleted. If bForce is TRUE then the group is deleted unconditionally even if references (interfaces) still exist. Subsequent use of such interfaces will result in an access violation.

Servers which do not support public groups will simply behave as if they had no public groups. That is they will NOT return E_INVALIDARG if the scope includes public groups.

IEnumUnknown creates an additional interface pointer to each group in the enumeration (even if the client already has a connection to the group). If the server has a large number of public groups available then this may involve considerable overhead as well as requiring additional cleanup by the client. In general, enumerating groups by name will be much faster.

In the case of IEnumUnknown (per the COM specification) the client must also release all of the returned IUnknown pointers when he is done with them.
 
 
 
 

The general principles of ConnectionPoints are not discussed here as they are covered very clearly in the Microsoft Documentation. The reader is assumed to be familiar with this technology. OPC 2.0 Compliant Servers are REQUIRED to support this interface.

Likewise the details of the IEnumConnectionPoints, IConnectionPoint and IEnumConnections interfaces are well defined by Microsoft and are not discussed here.

Note: OPC Compliant servers are not required to support more than one connection between each Server and the Client. Given that servers are client specific entities it is expected that a single connection will be sufficient for virtually all applications. For this reason (as per the COM Specification) the EnumConnections method for IConnectionPoint interface for the IOPCShutdown is allowed to return E_NOTIMPL.
 
 

This interface can be used by clients to browse the available properties (also refered to as attributes or parameters) associated with an ITEMID and to read the current values of these properties. In some respects the functionality is similar to that provided by BrowseServerAddressSpace, by EnumItemAttributes and by the SyncIO Read function. It differs from these interfaces in two important respects; (a) it is intended be much easier to use and (b) it is not optimized for efficient access to large amounts of data. Rather it is intended to allow an application to easily browse and read small amounts of additional information specific to a particular ITEMID.

The design of this interface is based upon the assumption is that most ITEMIDs are associated with more complex objects within the underlying system which have additional information (properties) beyond their value, quality and timestamp. This interface allows a flexible and convenient way to browse and read this information without imposing any particular design structure on the underlying system.

It also allows such information to be read without the need to create and manage OPCGroups.

Typical Use

Typical Client use of this interface would be to obtain an ITEMID either by obtaining a 'LEAF' via BrowseServerAddress or via direct input to an edit box by the user. That ITEMID would be passed to QueryAvailableProperties(). The resulting list would be presented to the user. He would select the properties he wanted to see from the list. The client would pass this set to GetItemProperties () to get a 'snapshot' of the data. Optionally the client could pass the set to LookupItemIDs and use the resulting set of ITEMIDs to create an OPCGroup to be used to repeatedly obtain the data.

Examples

This is just an example. It is not intended to impose any particular structure on any server implementation.

A typical OPC ITEMID might be FIC101.CV. This could represent the current value of a tag or function block called FIC101. This function block commonly has other properties associated with it such as Engineering Units, a loop description, etc. This function block could also have alarm limits and status, a setpoint, tuning parameters as well as documentation cross references, maintenance information, help screens, default operator displays and a limitless set of other properties. All of these properties are associated with each other by virtue of their common association with FIC101. This interface provides a convenient shortcut to accessing those related properties.

An MMI package for example might use this interface to allow the user to indicate that the Hi and Lo Engineering Units values should be used to scale a bargraph representation of the value.

Note that because these associations can be 'many to many' and can also be circular, a client application would not want to automatically investigate them all.

It is NOT intended that property browsing be hierarchical.

Another similar example could be a function block such as a TIMER or COUNTER in a high end PLC where various Properties are associated with each object.

How ‘Properties’ relate to ItemIDs.

In most cases it is expected (but not required) that such properties can also be accessed via ItemIDs such as FIC101.HI_EU, FIC101.DESC, FIC101.ALMSTAT, etc. These related ITEMIDs could be used in an OPCGroup. This interface provides a way to easily determine if such an alternate method of access can be used for the properties if large amounts of information need to be obtained more efficiently.

Property IDs

The server will need to assign DWORD ID codes to the properties. This allows the client to more easily manage the list of properties it wants to access. These properties are divided (somewhat arbitrarily) into 3 ‘sets’. The OPC ‘Fixed’ set contains properties that are identical to some of those returned by OPCITEMATTRIBUTES, the ‘recommended’ set is expected to be common to many servers, the ‘vendor specific’ set contains additional properties as appropriate. The assigned IDs for the first two sets are fixed. The vendor specific properties should use ID codes above 5000.

The OPC Property Sets

This is a set of property IDs that are common to many servers. Servers which provide the coresponding properties must do so using the ID codes from this list. Symbolic equates for these properties are provided in the OPCProps.H file. (See Appendix to this document).

ID Set 1 - OPC Specific Properties - This includes information directly related to the OPC Server for the system.

The position of the OPC Foundation is that if you have properties associated with an item which seem to fit the descriptions below then it is recommended that you use these specific descriptions and ID codes to expose those properties via this interface.

A server can provide any subset of these values (or none of them).

ID Set 3 - Vendor specific Properties

Note again that this interface is NOT intended to allow efficient access to large amounts of data.

The LocaleID of the server (as set by IOPCCommon::SetLocaleID) will be used by the server to localize any data items returned as strings. The item descriptions are not localized.
 
 
 
 

Clients should not use this interface to obtain large amounts of data. Clearly each server vendor will provide the best performace possible however as a practical matter it is expected that the design of this interface will make it difficult for the server to optimize performace. See LookupItemIDs.
 
 

The caller must Free the returned NewItemIDs and Errors array.
 
 

Public groups may be created by the server or they may be created by a client. When created by the client, they are first created as private groups and then converted to public groups by MoveToPublic.

A client can enumerate the available public groups by name using IOPCServer::CreateGroupEnumerator. He can ‘connect’ to a public group by calling GetPublicGroupByName. He can examine the contents of the group via IEnumOPCItemAttributes. He can assign client handles and datatypes that are meaningful for the particular client using various IOPCItemMgt functions.

Once a client connects to a Public group, it behaves very much like a private group. He can activate and deactivate the group or items in the group. He can set client handles for the group and items within the group. He can set requested data type for the items in the group. All of these operations affect only that particular client. They do not affect the behavior of other clients connected to that group. The exception to this behavior is that he cannot add or remove items.
 
 
 
 

Note that when the client’s last interface for the public group is released, the client is effectively disconnected from the group. At this point the server should release any resources or instance data associated with this particular client’s connection to the public group. It is not necessary for the client to call RemoveGroup or RemovePublicGroup to free these client specific resources.
 
 

It is permissible for a server to publish ‘hard coded’ groups which cannot be deleted. The server should return E_FAIL in this case.

In general, a well behaved client will call this function only after releasing all interfaces.

If interfaces still exist, RemovePublicGroup will mark the group as ‘deleted’. Any further calls to this group via these interfaces will return E_FAIL. When all the interfaces are released, the group will actually be deleted. If bForce is TRUE then the group is deleted unconditionally even if references (interfaces) still exist. Subsequent use of such interfaces will result in an access violation.

Note that any client can delete a public group. You can get the server handle of the group by calling IOPCGroupStateMgt::GetState.
 
 

NOTE: Version 1.0A of the specification stated that each instance of this interface was a separate object (like an enumerator), which would have allowed multiple independent browse sessions by the same client on the server address space. This turns out to be in violation of the rules of COM and as a result it does not work in combination with DCOM. In practice, this interface MUST be implemented (like any other interface) as a separate interface on the single underlying Data Access Object. The text of this section has been modified to reflect this. Note that the 'footprint' of the interface is unchanged for 2.0.

Note that the Data Access Server object maintains state information related to browsing (i.e. the current position in the address hierarchy) on behalf of the client using this interface. Since there is just one underlying Server object, there is just a single copy of this state information. Therefore the client CANNOT create a separate and independent browser object by doing a second QueryInterface for IOPCBrowseServerAddressSpace. (Doing this would simply give him a second copy of the original interface). If a second, independent browser object is required by a client, the client would need to create a second OPC Data Access Object and perform a QueryInterface for IOPCBrowseServerAddressSpace on that object.

It is assumed that the underlying server address space is either flat or hierarchical. A flat space will always be presented to the client as Flat. A hierarchical space can be presented to the client as either flat or hierarchical.

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. The client can optionally choose a starting point within a hierarchical space by calling ChangeBrowsePosition using OPC_BROWSE_TO. For a FLAT space this is ignored. For a HIERARCHICAL space you may pass any partial path (or a pointer to a NUL string to indicate the root). This sets an initial position from which you can browse up or down.

The Client can browse the items below (contained in) the current position via BrowseOPCItemIDs. For a hierarchical space you can specify BRANCH (which returns things on that level with children) or LEAF (things on that level without children)- or FLAT (everything including children of children). This gives you back a String enumerator.

This browse can also be filtered by a vendor specific filter string, by datatype, or by Access Rights.

In a hierarchy, the enumerator will return ‘short’ strings; the name of the ‘child’. These short strings will generally not be sufficient for AddItem. The client should always convert this short string to a ’fully qualified’ string via GetItemID. For example the short string might be TIC101; the fully qualified string might be AREA1.REACTOR5.TIC101. Note that the Server fills in any needed delimiters.

This ItemID can optionally be passed to BrowseAccessPaths to get a list of valid access paths to this item. (this returns another string enumerator).

If the client browsed for BRANCHs (things with children) then he can pass the result (short string) to ChangeBrowsePosition to move ‘down’. This method can also move ‘up’ in which case the short string is not used.

Examples of a Hierarchical Space:

Example 1

<ROOT>

AREA1 (branch)

REACTOR10 (branch)

TIC1001 (branch)

CURRENT_VALUE (leaf)

SETPOINT

ALARM_STATUS

LOOP_DESCIPTION

TIC1002

CURRENT_VALUE

etc…

REACTOR11

etc…

AREA2

etc…

Example 2

<ROOT>

PLC_STATION_1 (branch)

ANALOG_VALUES (branch)

40001 (leaf)

40002

etc…

An error is returned if the passed string does not represent a ‘branch’.

Moving UP from the ‘root’ will return E_FAIL.

Note OPC_BROWSE_TO is new for version 2.0. Clients should be prepared to handle E_INVALIDARG if they pass this to a 1.0 server.
 
 
 
 

Whenever possible the server should return strings which can be passed directly to AddItems. However, it is allowed for the Server to return a ‘hint’ string rather than an actual legal Item ID. For example a PLC with 32000 registers could return a single string of "0 to 31999" rather than return 32,000 individual strings from the enumerator. For this reason (as well as the fact that browser support is optional) clients should always be prepared to allow manual entry of ITEM ID strings. In the case of ‘hint’ strings, there is no indication given as to whether the returned string will be acceptable by AddItem or ValidateItem

Clients are allowed to get and hold Enumerators for more than one ‘browse position’ at a time.

Changing the browse position will not affect any String Enumerator the client already has.

The client must Release each Enumerator when he is done with it.
 
 

It is also possible that a server could support hierarchical browsing of an address space that contains globally unique tags. For example in the case above, the tag TIC1001.CURRENT_VALUE might still be globally unique and might therefore be acceptable to AddItem. However the expected behavior is that (a) GetItemID will always return the fully qualified name (AREA1.REACTOR10.TIC1001.CURRENT_VALUE) and that (b) that the server will always accept the fully qualified name in AddItems (even if it does not require it).

This function does not need to be called for a FLAT space. If it is called, then it will simply return the same string that was passed in.

It is valid to form an ItemID that represents a BRANCH (e.g. AREA1.REACTOR10). This could happen if you pass a BRANCH (AREA1) rather than a LEAF (CURRENT_VALUE). The resulting string might fail if passed to AddItem but could be passed to ChangeBrowsePosition using OPC_BROWSE_TO.

The client must free the returned string.

ItemID is the unique ‘key’ to the data, it is considered the ‘what’ or ‘where’ that allows the server to connect to the data source.
 
 

Changing the browse position will not affect any enumerator the client already has.

The client must Release each Enumerator when he is done with it.

AccessPath is the "how" for the server to get the data specified by the itemID (the what). The client uses this function to identify the possible access paths for the specified itemID.

This optional interface allows Clients to load or save a server ‘configuration’. The reason for providing this interface is to allow a client application to have access to any ‘hooks’ it might need to get the system started or to change the system configuration without requiring the user to start a separate program.

The filename discussed below tells the server where it’s configuration information is located. Filename syntax and semantics is server specific, and may include the fully qualified path and file name, or may refer to a proprietary database where the server’s configuration is stored. The format and content of the file or database is server specific.

Note that this interface does NOT save any client specific information such as group and item definitions. Rather, it is a ‘hook’ intended to load or save the server configuration such as a SCADA or DCS database, communications baud rates, PLC station addresses, etc.

A load will cause other clients connected to this server to be effectively disconnected, or the results of the other clients subsequent interactions with the server to be unknown.

The client must free the returned string.