4.4.8.4 IOPCBrowseServerAddressSpace:: GetItemID
HRESULT GetItemID(
[in] LPCWSTR szItemDataID,
[out, string] LPWSTR * szItemID
);
Description
Provides a way to assemble a ‘fully qualified’ ITEM ID in a hierarchical space. This is required since the browsing functions return only the components or tokens which make up an ITEMID and do NOT return the delimiters used to separate those tokens. Also, at each point one is browsing just the names ‘below’ the current node (e.g. the ‘units’ in a ‘cell’).
Parameters Description
szItemDataID The name of a BRANCH or LEAF at the current level. or a pointer to a NUL string. Passing in a NUL string results in a return string which represents the current position in the hierarchy.
szItemID Where to return the resulting ItemID.
Return Codes
Return Code Description
E_FAIL The function failed
E_INVALIDARG An argument to the function was invalid. (e.g. the passed ItemDataID was invalid)
E_INVALIDARG An argument to the function was invalid.
E_OUTOFMEMORY Not enough memory
S_OK The function was successful
Comments
A client would browse down from AREA1 to REACTOR10 to TIC1001 to CURRENT_VALUE. As
noted earlier the client sees only the components, not the delimiters which are likely to be very server specific. The function rebuilds the fully qualified name including the vendor specific delimiters(分隔符、定界符) for use by ADDITEMs. An extreme example might be a server that returns:
\\AREA1:REACTOR10.TIC1001[CURRENT_VALUE]
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 the server must 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.