WTOPCSvr DLL 使用手册（部分函数）
全文中如有“应用程序”字样，全部指的是“由开发者依据这个DLL开发的OPC服务器应用程序”。
用于OPC服务器的WinTECH软件快速开发DLL（WTOPCSvr）提供了一套易于使用的API，用于将用户的数据添加到OPC中。COM和OPC的所有细节都由DLL处理，这一套DLL可以很方便地开发应用程序，简明地向OPC提供数据点，不必关心底层COM接口的实现。DLL可以很容易地与用户开发的应用程序结合。所有使用此开发工具的OPC接口都支持OPC 1.0和OPC 2.0数据访问标准以及浏览接口。
WTOPCSvr作为数据库管理者。用户开发的应用程序通过向DLL传递名称和值来创建过程“标签”。DLL记录数据点，并将标签名称提供给任何OPC客户端应用程序。DLL可以控制用户开发的应用程序随时更改标签的值，并且将自动通知所有连接的客户端。对于由OPC客户端连接修改的任何标签，都提供写标签回调通知。（用户开发的应用程序可以控制哪些标记是OPC可写的。）
wtopcsvr现在支持动态创建OPC标签。DLL提供了一个回调函数，如果客户端请求一个以前未定义的标签（服务器并没有该名字的标签），该函数将向用户开发的应用程序返回控制权。由用户开发的服务器应用程序决定是使用请求的路径和名称组合新建一个标签，还是忽略请求。
WTOPCSvr.DLL 部分函数介绍
初始化和注册函数
BOOL UpdateRegistry(BYTE *pCLSID_Svr, LPCSTR Name, LPCSTR Descr, LPCSTR ExePath);
功能：调用此函数来完成服务器的注册。此函数对Windows注册表进行修改，以允许其他应用程序查找和执行服务器。
pCLSID_Svr 定义了OPC客户端用来连接到OPC服务器的CLSID（服务器类标识）(这是指向C样式GUID结构的字节指针)。
Name 服务器名字。
Descr 一个字符串，对服务器的描述。
ExePath 需要提供服务器应用程序的路径。
返回值：函数调用成功返回TRUE，失败返回FALSE。
BOOL InitWTOPCsvr(BYTE *pCLSID_Svr, UINT ServerRate);
功能：初始化DCOM和创建OPC服务器。
pCLSID_Svr 定义了OPC客户端用来连接到OPC服务器的CLSID（服务器类标识）。
ServerRate 以毫秒表示，并定义客户端连接的更新速率，即客户端连接后服务器以多快的速率向客户端提供刷新后的数据。
返回值：如果函数成功，返回值将为TRUE，否则为FALSE。
BOOL UnregisterServer(BYTE *pCLSID_Svr, LPCSTR Name);
功能：从注册表中移除服务器，从而注销服务器。
CLSID_Svr 定义了OPC客户端用来连接到OPC服务器的CLSID（服务器类标识）。
Name 想注销的服务器名字。
返回值：如果函数成功，返回值将为TRUE，否则为FALSE。
创建标签和更新标签的函数
HANDLE CreateTag(LPCSTR Name, VARIANT Value, WORD InitialQuality, BOOL IsWriteable);
功能：该函数通过 WTOPCSvr.DLL. 创建标签。
Name 定义OPC客户端要访问的标签名字。服务器程序中需要定义该名字，此名称可以是服务器所需的任何文本字符串。可以使用分段名称（包含分隔符“.”），将导致WTOPCSvr.DLL将OPC名称空间结构为层次结构，用于浏览操作。比如OPCTAG.TAG1，这样定义的标签名，在客户端读取时会认为这个标签作为一个叶子放在名为OPCTAG的树枝下。
Value 服务器程序需要在创建标签时提供标签的初始值。
InitialQuality OPC标签的品质会有不同情况，可以在创建时赋值一个初始状态。
IsWriteable 这个标志位用来定义新建的标签是否可以被客户端写值
返回值：如果标签创建成功，那么返回一个标签的句柄，否则返回INVALID_HANDLE_VALUE 表示创建标签失败。
BOOL UpdateTag(HANDLE TagHandle, VARIANT Value, WORD Quality);
BOOL UpdateTagWithTimeStamp(HANDLE TagHandle, VARIANT Value, WORD Quality, FILETIME timestamp);
功能：这两个函数都可以更新当前创建标签的内容，包括值，品质（下面的一个还有时间戳），如果服务器程序没有提供时间戳，DLL会自动添加当前服务器所在电脑的时间作为时间戳。
TagHandle 在建立标签的时候返回的标签句柄。
Value 服务器程序输入，要将标签更新为什么值。
Quality 服务器程序输入，要将标签更新为什么状态。
返回值：如果更新成功返回 TRUE，更新失败返回FALSE。
BOOL UpdateTagByName(LPCSTR Name, VARIANT Value, WORD Quality);
功能：这个函数也可以用来更新创建标签的内容，区别就是提供的是标签名字而不是标签句柄。
Name 要更新值的标签名字。
Value 服务器程序输入，要将标签更新为什么值。
Quality 服务器程序输入，要将标签更新为什么状态。
返回值：如果更新成功返回 TRUE，更新失败返回FALSE。
下述三个函数必须一起使用，它们一起提供了一次刷新多个标签的有效方式。首先调用StartUpdateTags，然后用UpdateTagToList代替UpdateTag()调用，当所有标签都被刷新后再调用EndUpdateTags()结束此次刷新操作。
BOOL StartUpdateTags();
功能：开始刷新服务器标签。
BOOL WINAPI UpdateTagToList(HANDLE TagHandle, VARIANT Value, WORD Quality);
功能：这个函数可以代替之前的更新标签值，可以一次更新多个标签值，传递的参数和之前的一样不再说明。需要注意，这个函数使用之前必须调用StartUpdateTags()，使用之后必须调用EndUpdateTags ()，否则调用会失败！
BOOL WINAPI EndUpdateTags();
BOOL SuspendTagUpdates(HANDLE TagHandle, BOOL OnOff);
功能：挂起对标签的更新。此函数可与未知项回调Unknown Item callback一起使用，以允许服务器应用程序知道客户端何时订阅这个被挂起的标记。一般情况下，服务器应用程序会随着标签值的变化跟新标签，然后DLL将处理所有客户端订阅、通知和更新请求，给客户端提供相应数据。在某些情况下（挂起），服务器应用程序只需要在客户端主动订阅项目时更新OPC标签。通过挂起更新，每当客户端尝试订阅被挂起的标签时，dll将发出UNKNOWNITEM回调。然后，服务器可以继续更新，并等待ITEMREMOVED回调再次挂起更新。
TagHandle 想要挂起的标签。
OnOff 挂起或者继续更新标签值的标志 (服务器应用程序应当使用l SuspendTagUpdates (…, TRUE) 在第一个UNKNOWNITEM回调通知产生后，这样可以防止别的客户端订阅这个挂起的标签时额外的UNKNOWNITEM回调通知。
返回值：成功将标签挂起会返回TRUE，失败返回TRUE。
BOOL ReadTag(HANDLE TagHandle, VARIANT *pValue);
BOOL ReadTagWithTimestamp(HANDLE TagHandle, VARIANT *pValue, WORD *pQuality, FILETIME *pTimestamp);
功能：这个函数可以让应用程序读取 WTOPCSvr.DLL中定义的标签的数据。
TagHandle 创建过的标签的句柄。
pValue 首先要定义一个指针，成功执行完该函数后，标签的值放在指针对应的数据中。
pQuality 首先要定义一个指针，成功执行完该函数后，标签的品质放在指针对应数据。
pTimeStamp 首先要定义一个指针，成功执行完该函数后，会接收到标签的时间戳。
返回值：读取成功返回TRUE，否则FALSE。
BOOL RemoveTag(HANDLE TagHandle);
功能：此函数用于从WTOPCSvr.DLL中删除标签。如果客户端连接正在访问删除的点，则连接将保持有效，但不会向客户端显示新数据。
TagHandle 标签句柄。
返回值：删除成功返回TRUE，否则FALSE。
回调通知函数（主要用于和客户端交互，发生相应的消息后，应用程序会进入到回调函数处理接收到的相应消息。有些类似于MFC中的消息映射机制）
BOOL EnableUnknownItemNotification(UNKNOWNITEMPROC lpCallback);
功能及返回值：这个函数的返回值表示一个客户请求了一个没有定义或是己经被暂停刷新的标签，但无论客户请求的标签是否是己定义的标签，这个函数都定义了一个从DLL返回的调用返回。服务器应用可以使用这个调用返回对动态创建的标签进行操作。WTOPCSvr.DLL 会接收到消息，进入这个消息回调函数。
lpCallback 指向一个如下的处理函数：
void CALLBACK EXPORT UnknownTagProc(LPSTR Path, LPSTR Name)
Path 发出请求的路径名。
Name 客户端想要请求访问的服务器标签名。
BOOL EnableItemRemovalNotification(ITEMREMOVEDPROC lpCallback);
功能：当删除对创建的一个标签的最后一个客户端引用时， WTOPCSvr.DLL会收到此消息进入这个回调函数。
lpCallback 指向一个如下的处理函数：
void CALLBACK EXPORT RemoveTagProc(HANDLE hTag, LPSTR Path, LPSTR Name)
hTag 指定已经被移除标签的句柄。
Path 发出请求的路径名。
Name 客户端想要请求访问的服务器标签。
BOOL EnableWriteNotification(WRITENOTIFYPROC lpCallback, BOOL ConvertToNativeType);
功能：此函数定义回调例程，每当OPC客户端应用程序写入对应标签时， WTOPCSvr.DLL会收到消息进入该回调函数。通常，dll本身可以将写入的值转换为VARIANT类型，但在某些情况下，由OPC服务器开发者开发的应用程序本身可能需要执行特殊的转换处理。
lpCallback 指向如下回调函数：
void CALLBACK EXPORT NotificationHandler(HANDLE handle, VARIANT *pNewValue, DWORD *pDeviceError)
handle 想要写入值的标签句柄。
pNewValue 定义要写入的值。服务器应用程序需要将新值写入实际设备，并调用UpdateTag将新值更新到DLL对应的标签缓存。
pDeviceError 如果写入值失败，服务器应用程序会将这个错误标记返回到客户端。
BOOL EnableDisconnectNotification(DISCONNECTPROC lpCallback);
功能：此函数定义回调例程，当OPC客户端应用程序断开对这个服务器应用程序的连接， WTOPCSvr.DLL会收到消息进入下面的回调函数。
lpCallback 指向如下函数:
void CALLBACK EXPORT DisconnectHandler(DWORD Numbr)
Numbr 定义了剩余连接到这个服务器的客户端的数目。
BOOL EnableEventMsgs(EVENTMSGPROC lpCallback);
功能：此函数允许服务器应用程序在OPC服务器接口正常运行期间从WtOPCsvr.dll接收事件消息。事件消息可用作调试工具，通过各种接口过程跟踪逻辑的执行。也就是说通过这个函数，可以手动模拟客户端发出的各种消息，比如模拟客户端发出写标签消息，从而在没有真正产生服务器和客户端连接时进行调试。
lpCallback 指向下面的回调函数：
void CALLBACK EXPORT EventHandler(LPCSTR Msg)
Msg 定义了要发出什么消息，比如前面的断开连接消息。
BOOL EnableRateNotification(RATECHANGEPROC lpCallback);
功能：此函数定义一个回调过程，每当项的最小请求更新率更改时，该回调过程接收控制。不同的客户端可能以不同的速率从服务器请求项目。此回调允许服务器应用程序优化其数据获取逻辑，以最有效的速率获取项的数据。
也就是说，如果有多个客户端连接服务器，每个客户端请求服务器对它刷新数据的速率不一样，当这些刷新速率中最小的刷新速率更改时，服务器端会收到这个消息，这样服务器可以进行一些处理，例如改变自己提供数据的速率，方便两者通讯更加有效率。
lpCallback 指向如下的回调函数：
void CALLBACK EXPORT RateChangeHandler(HANDLE hItem, DWORD Rate)
hItem 改变刷新率的项的句柄。
Rate 重新请求的刷新率。
其他函数
char SetWtOPCsvrQualifier(char qualifier);
功能：此函数用于设置dll用于分割分层命名空间的节点名的定界字符。默认分隔符是“.”字符，也就是说，服务器默认在创建标签时会通过识别标签中的. 来将标签分为不同的树枝和对应叶子，可以通过该函数替换这个分割符号。
int NumbrClientConnections();
功能：此函数返回当前连接到WTOPCSvr.DLL的OPC客户端数。
void RequestDisconnect();
功能：此函数要求所有OPC客户端与服务器断开连接。此函数不能保证请求得到满足，或者客户端将实际断开连接。OPC服务器请求客户机断开连接的能力仅适用于根据OPC 2.0规范连接的客户端。
BOOL RefreshAllClients();
功能：服务器应用程序可以使用此功能启动对所有连接的OPC客户端的刷新操作。一般都是OPC客户端应用程序基于WTOPCSvr.DLL中的异步时钟周期进行客户端自身的刷新。此函数可用于强制服务器更新所有客户端数据。.
返回值：函数调用成功返回TRUE，否则FALSE。
BOOL ResetServerRate(UINT ServerRate);
功能：服务器应用程序可以使用此函数更改服务器刷新数据的速率的当前设置。这个函数可以改变服务器注册时候的刷新速率。
返回值：函数调用成功返回TRUE，否则FALSE。
BOOL SetVendorInfo(LPCSTR VendorInfoString);
功能：应用程序可以设置服务器响应客户端对服务器信息的请求而返回的供应商信息描述。这个函数可以更新服务器创建时候定义的服务器描述。
返回值：函数调用成功返回TRUE，否则FALSE。
void SetServerState(OPCSERVERSTATE SvrState);
功能：此函数允许应用程序将服务器的状态设置为由客户端访问。在设计和调试期间可用于显示与服务器操作相关的内部诊断。
1787
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
