OPC：客户端开发——应用WTclient.dll使用手册部分中文版
WinTECH软件快速客户端开发DLL（WTclient），提供了一种应用API方便地将定制应用和任何OPC Server相结合的方式。所有COM和OPC的细节均由DLL来处理，这使得一个应用可以轻松的从服务器获取数据点，而不用关心接口后的实际完成过程。 这些DLL可以方便和已有的或者新的应用相结合。其中提供了面向OPC1.0和OPC2.0数据访问标准所需的全部OPC接口，同时也提供了浏览接口和连 接到简单警报/事件服务器的支持。
这个用户指导应该被当作一本OPC数据访问和OPC警报/事件规范手册文档使用，其中的所有资料都可在OPC主网站http://www.opcfoundation.org上找到。
WTclient.lib内有DLL文件中API的出口定义，将这个文件包含到你的定制应用的工程文件中，同时将WTclientAPI.h包 含到会调用DLL的模块中。如果应用Visual Basic进行编程，需要将VBA范例中（随demo提供）的module1.bas包含到你的工程中。
在使用WTclient.dll的之前，需要在代码起始的时候调用一下函数Disable30MinTimer
| 函数 | BOOL Disable30MinTimer (LPCSTR Authorization); |
| 说明 | DLL里面有个计时的函数，如果想正常使用dll的功能需要在开始传递一个字符串来调用一个禁用计时的函数，否则30分钟之后停止服务。该dll文件有的导出函数传递也是LPCSTR的，程序调用功能正常，也是采用传递byref 的 byte来进行的。 至于说这个字符串是什么，就要和Dll的厂家公司联系了 |
- DCOM初始化——WTclientCoInit、CoUninitialize
| 函数 |
WTclientCoInit()、CoUninitialize() |
| 说明 |
从WTClient.DLL2.0版本开始，初始化DCOM是客户端应用的责任了。2.0版本之前，WTClient.dll在DLLMain 函数中执行DCOM和安全初始化的过程，并在dll下载时调用CoUninitialize函数。由于不同windows dll文件的加载顺序，这会带来一些问题。 这些初始化调用被移动到了一个新的输出函数WTclientCoInit()中，用户的应用可以在主要可执行线程启动的时候调用这个函数。WTclientCoInit()将DCOM初始化为多线程并使用默认安全设定。你的应用可以选择自行初始化DCOM替代 这个输出函数。任何情况下，你的应用都必须在终止时调用CoUninitialize()函数。 |
2、获取OPC服务器列表
| 函数 |
int NumberOfOPCServers (BOOL UseOPCENUM, LPCSTR MachineName); |
| 说明 |
OPCENUM是由OPC Foundation提供的一个组件，它允许预期的客户端应用获取本地以及远程可用服务器列表。可惜的是，在写这个组件的时候，OCENUM的操作并没有很好的跨平台一致性。 WTclient.dll允许应用尝试使用OPCENUM组件来获取服务器列表，或者越过OPCENUM组件通过扫描Windows 登记的本地拷贝来获取列表。如果使用了OPCENUM，你可以通过传递远程机器的名称来获取远程服务器列表。 |
一旦WTclietn.dll返回了服务器的数目，应用就可以通过调用如下所示的函数来对服务器名称列表进行枚举：
| 函数 |
BOOL GetServerName (int index, LPSTR Buffer, int BufSize); |
| 说明 |
一个由用户提供的字符缓冲区Buffer负责存放传递过来的index标识的服务器列表中某个服务器名字。BufSize标识用户提供的字符缓 冲区的长度，并可以防止dll载入过长的名字。如果Buffer中返回了一个有效的服务器名称，GetServerName函数返回TRUE。 |
还有一个补充函数集允许应用获取可用的警报/事件服务器列表。
| 函数 |
int NumberOfOPC_AEServers (LPCSTR MachineName); BOOL GetOPC_AEServerName (int index, char *pBuf, int BufSize); |
3、建立、断开OPC连接
| 函数 |
HANDLE ConnectOPC(LPCSTR MachineName, LPCSTR ServerName, BOOL EnableDLLBuffering); HANDLE ConnectOPC1(LPCSTR MachineName, LPCSTR ServerName, BOOL EnableDLLBuffering); HANDLE ConnectOPC_AE(LPCSTR MachineName, LPCSTR ServerName); |
| 说明 |
如果一个由计算机名称和服务器名称定义的和OPC服务器之间的连接可以被建立，则此函数返回一个有效的HANDLE。可以建立和不同的服务器的多个同步连接，此时返回的HANDLE标识了可用于以后创建组和项目的连接。如果传递一个空字符串作为计算机名称参数，标识的是本地计算机。 WTclient会先尝试使用OPC2.0连接点接口进行连接，如果不可用，则会转而采用OPC1.0数据对象接口。 WTclient.dll的基本操作有两种模式。第一种模式用于支持'C-样式'回调函数的应用，在这种情况下，dll中没有缓冲区操作。由于可以从连接的OPC服务器接收到数据更改提示，回调可用于将新的信息传送给控制应用（此处涉及到下面会提及的EnableOPCNotification 函数）。 对于使用不支持回调函数的工具设计的那些应用（例如Visual Basic 5.0），WTclient会被配置为维护一个由应用创建的全部OPC项目（标签）列表的模式。当服务器数据改变时，dll中列表里相关的标签值会被更 新，控制应用可以随时读取标签的值（此处涉及到下面会提及的ReadOPCItem函数）。 ConnectOPC1会总是尝试使用OPC1.0连接。 ConnentOPC_AE会建立一个和OPC警报/事件服务器的连接，此连接由计算机名称和服务器名称指定。 |
断开连接的函数：
| 函数 |
void DisconnectOPC(HANDLE hConnect); void DisconnectOPC_AE(HANDLE hConnect); |
| 说明 |
当一个应用终止的时候，它会负责从依附的服务器断开连接。 DisconnectOPC（或Disconnect_OPCAE）函数会对hConnect定义的连接执行一个彻底的连接关闭操作。 |
4、获取服务器标签名列表
| 函数 |
int NumberOfOPCItems(HANDLE hConnect); BOOL GetOPCItemName (HANDLE hConnect, int index, char *pBuf, int BufSize); |
| 说明 |
这两个函数和获取服务器名称列表函数的调用方式类似。 NumberOfOPCItems()返回所连接OPC服务器支持的独有标签总数。 依次地调用GetOPCItemName()会逐步遍历所有可用的标签名，最终允许控制应用选择一个项目或者提交一个浏览列表给用户。 NumberOfOPCItems()会浏览服务器的全部项目名称列表并提供一个“FLAT”格式的列表。NumberOfOPCItems()函数相当于在根节点处用OPC_FLAT方式调用BrowseItems函数。（BrowseItems函数见下表） |
| 函数 |
BOOL GetNameSpace (HANDLE hConnect, WORD *pNameSpace); BOOL BrowseTo (HANDLE hConnect, LPCSTR NodeName); char SetWTclientQualifier (char qualifier); int BrowseItems (HANDLE hConnect, WORD Filter); |
| 说明 |
为了提供较好的应用等级体系命名空间访问服务器的方式，WTClient dll提供函数以便于应用直接从服务器端浏览项目名。 GetNameSpace()函数允许应用决定服务器的命名空间，BrowseTo()函数负责将当前浏览位置移动到指定的名称处，BrowseItems()函数用服务器的节点名称来填充内部名称列表。BrowseTo()函数既可以和 OPC_LEAF一起使用来读取当前浏览位置的叶片名称，也可以和OPC_BRANCH一起使用来当前浏览位置的读取枝条名称。这些名称可以被 GetOPCItemName函数获取。 WtClient动态链接库为NumberOfOPCItems()函数和BrowseItems()函数维护一个单一的名称列表，因此应用程序在浏览服务器命名空间的时候必须很小心，避免覆盖前一次调用的值。在各个等级的树的相互作用过程中，调用BrowseItems之后，所有的项目名称必须立刻拷贝到本地存储中。 SetWTclientQualifier()函数允许应用程序改变用来解析各个等级命名空间节点的划界字符。客户端应用一般认为缺省的划界符为‘.’，然而也有些服务器将‘.’字符用在了节点名字中。 |
| 函数 |
BOOL SetBrowseFilters (HANDLE hConnect, LPCSTR UserString, VARTYPE DataType, DWORD AccessType); |
| 说明 |
应用程序可以设置浏览过滤器来影响服务器返回的OPC项目个数。应用程序可以选择仅获取那些符合指定数据类型或者访问权限的项目。 |
5、创建OPC组和标签
| 函数 |
HANDLE AddOPCGroup (HANDLE hConnect, LPCSTR Name, DWORD *pRate, float *pDeadBand); void RemoveOPCGroup (HANDLE hConnect, HANDLE hGroup); |
| 说明 |
WTclient.dll提供两个函数，允许你创建、移除一个OPC组。 AddOPCGroup()函数返回一个唯一指定某个组的指针，这个指针对于其他的Wtclient函数是必需的。传送给做AddOPCGroup()参数的值由控制应用端决定，对于每个组都是明确的。Name不会被服务器采用，可以任意选取。pRate是一个指针，指向对象为所需刷新率（单位为毫秒），服务器端用这个刷新率提供客户端刷新后的返回值。 |
| 函数 |
BOOL ChangeOPCGroupState (HANDLE hConnect, HANDLE hGroup, BOOL Active)); |
| 说明 |
应用这个函数可以将指定的OPC组设定为激活状态（Active = TRUE）或者无效状态（Active = FALSE）。 |
| 函数 |
HANDLE AddOPCItem (HANDLE hConnect, HANDLE hGroup, LPCSTR ItemName); void RemoveOPCItem (HANDLE hConnect, HANDLE hGroup, HANDLE hItem); |
| 说明 |
如果想要给指定的OPC组添加一个项目，只需使用组的指针以及待添加项目的标签名调用AddOPCItem函数即可，该函数会返回一个唯一标识指定项目的指针。如果请求的项目不存在，则函数将会返回INVALID_HANDLE_VALUE。当关闭一个组的时候，需要调用 RemoveOPCItem()函数来清理已分配的内存 |
| 函数 |
BOOL SetItemUpdateHandle (HANDLE hConnect, HANDLE hGroup, HANDLE hItem, HANDLE hUpdate); |
| 说明 |
SetItemUpdateHandle()函数允许客户端应用定义一个独有的指针，供服务器在数据更新回调时使用。这个函数的提供是为了给客户端应用提供便利，以便于进行更有效率的程序设计，并可以对服务器提供的新数据进行操作。 |
| 函数 |
BOOL GetOPCItemNameFromHandle (HANDLE hConnect, HANDLE hGroup, HANDLE hItem, char *pBuf, int BufSize); |
| 说明 |
这个函数允许客户端应用通过传递AddOPCItem函数返回的指针来获取OPC项目名。 |
| 函数 |
BOOL GetOPCItemType (HANDLE hConnect, HANDLE hGroup, LPCSTR ItemName, VARTYPE *pType, DWORD *pAccessRights); |
| 说明 |
这个函数返回了指定项目的本地变量类型以及访问权限。 |
| 函数 |
int NumberOfItemProperties (HANDLE hConnect, LPCSTR ItemName); |
| 说明 |
这个函数返回了和指定标签相关的OPC项目属性数量 |
| 函数 |
BOOL GetItemPropertyDescription (HANDLE hConnect, int PropertyIndex, DWORD *pPropertyID, VARTYPE *pVT, BYTE *pDescr, int BufSize); |
| 说明 |
遍历NumberOfItemProperties()函数创建的列表，就可以获取每个项目属性的描述 |
| 函数 |
BOOL ReadPropertyValue (HANDLE hConnect, LPCSTR Itemname, DWORD PropertyID, VARIANT *pValue); |
| 说明 |
ReadPropertyValue()函数可以返回一个项目属性的当前值。 |
6、从服务器获取标签值更新（Getting updated Tag Values from the Server）
| 函数 |
BOOL EnableOPCNotification (HANDLE hConnect, NOTIFYPROC lpCallback); |
| 说明 |
如果你的应用支持回调，当连接的服务器发出了标签数据值改变的通知时，WTclient会提供回调操作。回调函数的原型定义如下 |
| 函数 |
void CALLBACK EXPORT OPCUpdateCallback (HANDLE hGroup, HANDLE hItem, VARIANT *pVar, FILETIME timestamp, DWORD quality) |
| 说明 |
由组指针和项目指针确定的标签的值、时间戳以及OPC品质标签都会在回调过程中提供给应用。。 |
| 函数 |
BOOL ReadOPCItem (HANDLE hConnect, HANDLE hGroup, HANDLE hItem, VARIANT *pVar, FILETIME *pTimeStamp, DWORD *pQuality); |
| 说明 |
如果WTclient已经配置为维护一个内部标签缓冲，控制应用可以使用ReadOPCItem函数读出当前标签的值。如果请求的项目不可用（或者没有选定DLL缓冲），函数会返回FALSE。 |
| 函数 |
HRESULT ReadOPCItemFromDevice (HANDLE hConnect, HANDLE hGroup, HANDLE hItem, VARIANT *pVar, FILETIME *pTimeStamp, DWORD *pQuality); |
| 说明 |
这个函数执行了一个直接同步读取服务器端指定项目的操作。 |
7、将标签值写入到服务器（Writing Tag Values to the Server）
| 函数 |
DWORD WriteOPCItem (HANDLE hConnect, HANDLE hGroup, HANDLE hItem, VARIANT *pVar, BOOL DoAsync); |
| 说明 |
Writing new data to the connected Server is accomplished via the WriteOPCItem function. The identifying handles for the group and item must be supplied as well as the data to be written. The DoAsync parameter instructs the dll to perform an Asynchronous write to the Server. For Synchronous writes, the return value indicates the hResult returned from the server and a non-zero value indicates an error. For Asynchronous writes, the return value is a Transaction ID that defines the asynchronous callback handle and a zero value indicates an error. |
8、其他函数和回调函数（Miscellaneous Functions and callbacks）
| 函数 |
BOOL GetSvrStatus (HANDLE hConnect, OPCSERVERSTATUS *pSvrStatus, int VendorInforBufSize); |
| 说明 |
The current status of the identified server is returned in the supplied buffer. |
| 函数 |
BOOL SetClientName (HANDLE hConnect, LPCSTR Name); |
| 说明 |
This function allows the client to define a name to designate the connection with the server. |
| 函数 |
BOOL EnableErrorNotification (ERRORPROCAPI lpCallback); |
| 说明 |
The WTClient dll can notify the client application of errors that occur during processing of data interface calls to an OPC Server. Error messages may be generated by the dll if unexpected situations occur during processing of a user request. The default operation of the dll is to display a user message in a dialog box describing the condition. In most cases, it is more appropriate for the application itself to handle the error message rather than having the dialog generated by the dll. If Error Notification is enabled, control will be passed to the application via the following callback: |
| 函数 |
void CALLBACK EXPORT ErrorMsgCallback (DWORD hResult, char *pMsg); |
| 说明 |
A textual description of the error is contained in pMsg along with the resultant hResult. |
| 函数 |
BOOL EnableClientEventMsgs (EVENTMSGPROC lpCallback); |
| 说明 |
The WTClient dll can also notify the client application of various events as they occur during operation of the connection with the server. These events are basically used for debugging and represent normal activity associated with processing individual interfaces, (such as entering and exiting a particular function). Generally, the client application does not need to be made aware of theses events, however, if it wishes to provide a low level description of how the connection is functioning, it can receive these debugging statements as they occur by enabling Event Msgs. |
| 函数 |
void CALLBACK EXPORT EventMsgCallback (char *pMsg); |
| 说明 |
A textual description of the event is contained in pMsg. |
| 函数 |
BOOL EnableShutdownNotification (HANDLE hConnect, SHUTDOWNPROCAPI lpCallback); |
| 说明 |
If a connected OPC Server wishes to shutdown, it may request that any or all clients disconnect. The Client application should enable the shutdown notification within the WTClient dll to handle this request and terminate the connection. |
| 函数 |
void CALLBACK EXPORT ShutdownCallback (HANDLE hConnect); |
| 说明 |
The hConnect parameter identifies the server connection that is requesting the disconnect. |
9、创建警报/事件订阅机制（Creating an Alarms & Events Subscription）
| 函数 |
BOOL Create_AE_Subscription (HANDLE hConnect, HANDLE SubscriptionHandle,DWORD *pBufferTime, DWORD *pMaxSize); BOOL WINAPI EnableAECallback (AE_PROC lpCallback); BOOL WINAPI EnableExtendedAECallback (AE_PROC_EX lpCallback); |
| 说明 |
To begin receiving alarm and event messages from the connected server, a subscription must be in initiated and a callback procedure defined. The application passes a SubscriptionHandle that the server uses to identify the connection to the callback. pBufferTime and pMaxSize refer to the requested update frequency and the maximum number of events to be exchanged at one time. (Note: These values are for efficiency purposes only. If the standard callback is used, the WTClient DLL will set up the connection and callback to the server. The DLL will always issue a single callback to the application per event message, regardless of how many event messages are in the server callback to the dll. If the extended version of the callback is used, these parameters have the effect as described in the OPC A&E Specification with respect to the ONEVENTSTRUCT.)
|
One of two callback procedures may be defined, depending upon the complexity of the client application. Teh standard callback procedure is prototyped as follows:
| void CALLBACK EXPORT AECallback (HANDLE SubscriptionHandle, char *pSource, |
| 函数 |
void CALLBACK EXPORT AECallback (HANDLE SubscriptionHandle, char *pSource, FILETIME timestamp, char *pMsg, DWORD severity); |
| 说明 |
The SubscriptionHandle is the same as created by the subscription, pSource identifies the source of the event and pMsg is the description. |
If additional information regarding the alarm & event notification, the client must enable the extended version of the callback:
| 函数 |
void CALLBACK EXPORT ExtendedAECallback (HANDLE SubscriptionHandle, BOOL bRefresh, BOOL bLastRefresh, DWORD dwCount, ONEVENTSTRUCT *pEvents) |
| 说明 |
Notice that the extended version of the A&E Callback contains the unfiltered parameter list as returned by the server OnEvent Interface, and may contain more than one event message. |
10、A&E服务器直接调用接口（A&E Server Direct Interface Calls）
The following functions are provided to allow the client application to call directly into the attached A&E Server. The parameter list is passed directly to the associated Server Interface without change and the resulting returned values originate from the server itself. The WTClient.dll does not modify these parameters in any way and their definition is described in the OPC Alarms & Events Specification available from the OPC Foundation. Please refer to this specification for a detailed description of each of the following functions.
| BOOL GetAESvrStatus (HANDLE hConnect, OPCEVENTSERVERSTATUS *pSvrStatus, |
The current status of the identified server is returned in the supplied buffer.
| BOOL Refresh_AE_Subscription (HANDLE hConnect, HANDLE hSubscription); |
This function allows the client to request a refresh of the defined A&E subscription from the server.
| HRESULT AckCondition (HANDLE hConnect, DWORD dwCount, LPWSTR szAcknowledgerID, |
The client uses the AckCondition method to acknowledge one or more conditions in the Event Server. The client receives event notifications from conditions via the IOPCEventSink::OnEvent callback. This AckCondition method specifically acknowledges the condition becoming active or transitioning into a different sub-condition (and no other state transition of the condition). One or more conditions belong to a specific event source – the source of the event notification. For each condition-related event notification, the corresponding Source, Condition Name, Active Time and Cookie is received by the client as part of the OnEvent callback parameters. (Refer to the OPC Alarms & Events Specification for a detailed description of the parametr list and return value.)
| HRESULT EnableConditionByArea (HANDLE hConnect, DWORD dwNumAreas, LPWSTR *pszAreas); |
Places all conditions for all sources within the specified process areas into the enabled state. Therefore, the server will now generate condition-related events for these conditions.
The effect of this method is global within the scope of the event server. Therefore, if the server is supporting multiple clients, the conditions are enabled for all clients, and they will begin receiving the associated condition-related events. (Refer to the OPC Alarms & Events Specification for a detailed description of the parametr list and return value.)
| HRESULT EnableConditionBySource (HANDLE hConnect, DWORD dwNumSources, LPWSTR *pszSources); |
Places all conditions for the specified event sources into the enabled state. Therefore, the server will now generate condition-related events for these conditions.
The effect of this method is global within the scope of the event server. Therefore, if the server is supporting multiple clients, the conditions are enabled for all clients, and they will begin receiving the associated condition-related events. (Refer to the OPC Alarms & Events Specification for a detailed description of the parametr list and return value.)
| HRESULT DisableConditionByArea (HANDLE hConnect, DWORD dwNumAreas, LPWSTR *pszAreas); |
Places all conditions for all sources within the specified process areas into the disabled state. Therefore, the server will now cease generating condition-related events for these conditions.
The effect of this method is global within the scope of the event server. Therefore, if the server is supporting multiple clients, the conditions are disabled for all clients, and they will stop receiving the associated condition-related events. (Refer to the OPC Alarms & Events Specification for a detailed description of the parametr list and return value.)
| HRESULT DisableConditionBySource (HANDLE hConnect, DWORD dwNumSources, LPWSTR *pszSources); |
Places all conditions for the specified event sources into the disabled state. Therefore, the server will no longer generate condition-related events for these conditions.
The effect of this method is global within the scope of the event server. Therefore, if the server is supporting multiple clients, the conditions are disabled for all clients, and they will stop receiving the associated condition-related events. (Refer to the OPC Alarms & Events Specification for a detailed description of the parametr list and return value.)
| HRESULT GetFilter (HANDLE hConnect, HANDLE hSubscription, DWORD *pdwEventType, |
Returns the filter currently in use for event subscriptions. (Refer to the OPC Alarms & Events Specification for a detailed description of the parametr list and return value.)
| HRESULT SetFilter (HANDLE hConnect, HANDLE hSubscription, DWORD dwEventType, |
Sets the filtering criteria to be used for the event subscription.
Events may be selected using the following criteria:
• Type of event, i.e. simple, condition, or tracking.
• Event categories
• Lowest severity, i.e. all events with a severity greater than or equal to the specified severity.
• Highest severity, i.e. all events with a severity less than or equal to the specified severity.
• Process areas
• Event Sources
A list of values for a single criterion are logically ORed together (e.g. if two event categories are specified, event notifications for both categories will be received). If multiple criteria are specified, they will be logically ANDed together, i.e. only those events satisfying all criteria will be selected. An example is specifying both lowest severity and highest severity will result in the selection of events with severities lying between the two values.
An OPCEventSubscription object has only one filter.
(Refer to the OPC Alarms & Events Specification for a detailed description of the parametr list and return value.)