OPC client 在VC环境下编程.doc

OPC client 在VC环境下编程一 连接使用到变量的说明类型说明HRESULT函数返回值，用来检测函数返回值（如：初始化COM库，查找CLSID,创建OPC服务等），提供函数执行情况CLSID全球唯一标示符，用来确定OPC服务的标识，从注册表查找获得LPWSTRLPSTR和LPWSTR是Win32和VC+所使用的一种字符串数据类型。LPSTR被定义成是一个指向以NULL(0)结尾的8位ANSI字符数组指针，而LPWSTR是一个指向以NULL结尾的16位双字节字符数组指针OPC接口说明IOPCServer*m_IOPCServer;IOPCServer 接口及成员函数主要用于对组对象进行创建,删除,枚 举和获取当前状态等操作.是 OPC 服务器对象的主要接口.接口及成员IOPCItemMgt*m_IOPCItemMgt;IOPCItemMgt 接口及成员函数用于OPC 客户程序添加、删除和组对象中组员等控制操作。IOPCSyncIO*m_IOPCSyncIO;IOPCSyncIO 用于同步数据访问。OPCITEMDEFm_Items1;OPCITEMDEF 数组，包含着项的存取路径, 定义和被请求的数据类OPCITEMRESULT*m_ItemResult;OPCITEMRESULT 数组，服务器用来告诉客户关于项的附加的信息（项句柄和规范的数据类型）OPCHANDLEm_GrpSrvHandle;OPC服务的句柄，在多个函数中都会用到使用到的函数说明CoInitialize(NULL);初始化COM库CoInitialize是 Windows提供的API函数，用来告诉 Windows以单线程的方式创建com对象。应用程序调用com库函数（除CoGetMalloc和内存分配函数）之前必须初始化com库。返回值S_OK : 该线程中COM库初始化成功S_FALSE 该线程中COM库已经被初始化 CoInitialize () 标明以单线程方式创建。使用 CoInitialize 创建可以使对象直接与线程连接，得到最高的性能。 CoInitialize并不装载COM 库，它只用来初始化当前线程使用什么样的套间。使用这个函数后，线程就和一个套间建立了对应关系。线程的套间模式决定了该线程如何调用COM对象，是否需要列集等。CoInitialize ()并不会干扰客户和服务器之间的通信，它所做的事情是让线程注册一个套间，而线程运行过程中必然在此套间。CoInitialize和CoUninitialize必须成对使用查找OPC服务CLSIDFromProgID(LOPC服务的名称, &clsid);通过ProgID,查找注册表中的相关CLSID参数：1.服务的名称 2. CLSID型变量，用来接收注册表中查找到的CLSID创建OPC服务器对象CoCreateInstance (clsid, NULL, CLSCTX_LOCAL_SERVER ,IID_IOPCServer, (void*)&m_IOPCServer);创建OPC服务器对象，并查询对象的IID_IOPCServer接口参数：1. CLSID型变量，使用CLSIDFromProgID函数查找到的CLSID 2. 3.函数功能描述:用指定的类标识符创建一个Com对象,用指定的类标识符创建一个未初始化的对象。当在本机中只创建一个对象时，可以调用CoCreateInstance;在远程系统中创建一个对象时，可以调用CoCreateInstanceEx;创建多个同一CLSID的对象时, 可以参考 CoGetClassObject 函数。函数原形：STDAPI CoCreateInstance(REFCLSID rclsid, /创建的Com对象的类标识符(CLSID)LPUNKNOWN pUnkOuter, /指向接口IUnknown的指针DWORD dwClsContext, /运行可执行代码的上下文REFIID riid, /创建的Com对象的接口标识符LPVOID * ppv /用来接收指向Com对象接口地址的指针变量);参数：rclsid in 用来唯一标识一个对象的CLSID(128位),需要用它来创建指定对象。pUnkOuter in 如果为NULL, 表明此对象不是聚合式对象一部分。如果不是NULL, 则指针指向一个聚合式对象的IUnknown接口。dwClsContext in 组件类别. 可使用CLSCTX枚举器中预定义的值. riid in 引用接口标识符,用来与对象通信。ppv out 用来接收指向接口地址的指针变量。如果函数调用成功,*ppv包括请求的接口指针。返回值：S_OK 指定的Com对象实例被成功创建。REGDB_E_CLASSNOTREG 指定的类没有在注册表中注册. 也可能是指定的dwClsContext没有注册或注册表中的服务器类型损坏 CLASS_E_NOAGGREGATION 这个类不能创建为聚合型。E_NOINTERFACE 指定的类没有实现请求的接口, 或者是IUnknown接口没有暴露请求的接口.注释：CoCreateInstance帮助者函数通过使用对象的CLSID,提供了一种便洁的方式与类对象连接,创建未初始化的实例,以及释放类对象。它封装了以下的功能:CoGetClassObject(rclsid, dwClsContext, NULL, IID_IClassFactory, &pCF); hresult = pCF-CreateInstance(pUnkOuter, riid, ppvObj); pCF-Release(); 当在本机中只创建一个对象时，调用CoCreateInstance是最方便的;如果要在远程系统中创建一个对象时，可以调用CoCreateInstanceEx;创建多个同一CLSID的对象时, 可以参考 CoGetClassObject 函数;如果创建多个对象实例,可以获得类对象的IClassFactory 接口指针，并使用需要的方法,可以使用CoGetClassObject函数。在CLSCTX枚举器中, 你可以指定用来管理对象的服务器类型. 这些常量可以是CLSCTX_INPROC_SERVER, CLSCTX_INPROC_HANDLER, CLSCTX_LOCAL_SERVER或是它们的任何组合. 常量CLSCTX_ALL被定义为这三个值的组合. 想获得更多的有关这些常量的用法,请参考CLSCTX.添加组到OPC服务器m_IOPCServer-AddGroup(Lgrp1,/in 组名TRUE,/in 活动状态500,/in 向服务器发送请求的刷新率1,/in 客户端的操作句柄&TimeBias,/in 与标准时间的校正值&PercentDeadband,/in 要舍弃的数据LOCALE_ID,/in 服务器使用的语言&m_GrpSrvHandle,/out 添加组以后服务器返回的组句柄&RevisedUpdateRate,/out 服务器的数据刷新率 IID_IOPCItemMgt,/in 添加组的接口类型(LPUNKNOWN*)&m_IOPCItemMgt);/out 服务器返回的接口对象指针AddGroup函数的说明HRESULT AddGroup(in, string LPCWSTR szName, in BOOL bActive,in DWORD dwRequestedUpdateRate,in OPCHANDLE hClientGroup,unique, in LONG *pTimeBias,in FLOAT * pPercentDeadband,in DWORD dwLCID,out OPCHANDLE * phServerGroup,out DWORD *pRevisedUpdateRate,in REFIID riid,out, iid_is(riid) LPUNKNOWN * ppUnk);ParametersDescriptionszNameName of the group. The name must be unique among the other groups created by this client. If no name is provided (szName is pointer to a NUL string) the server will generate a unique name. The server generated name will also be unique relative to any existing public groups.bActiveFALSE if the Group is to be created as inactive.TRUE if the Group is to be created as active. dwRequestedUpdateRateClient Specifies the fastest rate at which data changes may be sent to OnDataChange for items in this group. This also indicates the desired accuracy of Cached Data. This is intended only to control the behavior of the interface. How the server deals with the update rate and how often it actually polls the hardware internally is an implementation detail. Passing 0 indicates the server should use the fastest practical rate. The rate is specified in milliseconds.hClientGroupClient provided handle for this group. refer to description of data types, parameters, and structures for more information about this parameterpTimeBiasPointer to Long containing the initial TimeBias (in minutes) for the Group. Pass a NULL Pointer if you wish the group to use the default system TimeBias. See discussion of TimeBias in General Properties Section See Comments below.pPercentDeadbandThe percent change in an item value that will cause a subscription callback for that value to a client. This parameter only applies to items in the group that have dwEUType of Analog. See discussion of Percent Deadband in General Properties Section. A NULL pointer is equivalent to 0.0.dwLCIDThe language to be used by the server when returning values (including EU enumerations) as text for operations on this group. This could also include such things as alarm or status conditions or digital contact states.phServerGroupPlace to store the unique server generated handle to the newly created group. The client will use the server provided handle for many of the subsequent functions that the client requests the server to perform on the group.pRevisedUpdateRateThe server returns the value it will actually use for the UpdateRate which may differ from the RequestedUpdateRate. Note that this may also be slower than the rate at which the server is internally obtaining the data and updating the cache.In general the server should round up the requested rate to the next available supported rate. The rate is specified in milliseconds. Server returns HRESULT of OPC_S_UNSUPPORTEDRATE when it returns a value in revisedUpdateRate that is different than RequestedUpdateRate.riidThe type of interface desired (e.g. IID_IOPCItemMgt)ppUnkWhere to store the returned interface pointer. NULL is returned for any FAILED HRESULT.添加项目m_IOPCItemMgt-AddItems(1, /in 添加1个itemm_Items,/in 添加的item的指针&m_ItemResult,/out 添加item的结果&m_pErrors);/out 发生的错误m_Items的说明定义：OPCITEMDEFm_Items1;这个参数为OPCITEMDEF结构，包含着项的存取路径, 定义和被请求的数据类等。AddItems函数说明HRESULT AddItems( in DWORD dwCount,in, size_is(dwCount) OPCITEMDEF * pItemArray,out, size_is(,dwCount) OPCITEMRESULT * ppAddResults,out, size_is(,dwCount) HRESULT * ppErrors);ParametersDescriptiondwCountThe number of items to be addedpItemArrayArray of OPCITEMDEFs. These tell the server everything it needs to know about the item including the access path, definition and requested datatypeppAddResultsArray of OPCITEMRESULTs. This tells the client additional information about the item including the server assigned item handle and the canonical datatype.ppErrorsArray of HRESULTs. This tells the client which of the items was successfully added. For any item which failed it provides a reason.OPCITEMDEF结构说明typedef struct stringLPWSTRszAccessPath;/OPC服务器存取路径stringLPWSTRszItemID;/item的名称BOOLbActive ;/活动状态OPCHANDLEhClient;/操作句柄DWORDdwBlobSize;/item的pBlob大小size_is(dwBlobSize) BYTE * pBlob;/二进制指针VARTYPEvtRequestedDataType;/数据类型由客户端请求WORDwReserved;/保留字 OPCITEMDEF;MemberUsed byDescriptionszAccessPathbothThe access path the server should associate with this item. By convention a pointer to a NUL string specifies that the server should select the access path. Support for accesspath is optionalNOTE: version 1 indicated that a NULL pointer would allow the server to pick the path however passing a NULL pointer will cause a fault in the proxy/stub code and thus is not allowed.szItemIDbothA null-terminated string that uniquely identifies the OPC data item. See the Item ID discussion and the AddItems function for specific information about the contents of this field.bActiveaddThis Boolean value affects the behavior various methods as described elsewhere in this specification. hClientaddThe handle the client wishes to associate with the item. See the OPCHANDLE for more specific information about the contents of this field.dwBlobSizebothThe size of the pBlob for this item. pBlobbothpBlob is a pointer to the Blob. vtRequestedDataTypebothThe data type requested by the client. An error is returned (See Additems or ValidateItems) if the server cannot provide the item in this format. Passing VT_EMPTY means the client will accept the servers canonical datatype.查询同步接口m_IOPCItemMgt-QueryInterface(IID_IOPCSyncIO, (void*)&m_IOPCSyncIO);参数：1. IID_IOPCSyncIO 同步接口 2.服务器返回的用于操作同步接口的指针。同步接口读取数据m_IOPCSyncIO-Read(OPC_DS_DEVICE, 1, phServer, &pItemValue, &pErrors);参数：1OPC_DS_DEVICE 从OPC设备读取 另一个选择是OPC_DS_CACHE从缓存读取2读取的数量3这个item的服务句柄4返回值的OPCITEMSTATE结构数值指针5返回的错误指针HRESULT Read(in OPCDATASOURCE dwSource,in DWORD dwCount, in, size_is(dwCount) OPCHANDLE * phServer, out, size_is(,dwCount) OPCITEMSTATE * ppItemValues,out, size_is(,dwCount) HRESULT * ppErrors);ParametersDescriptiondwSourceThe data source; OPC_DS_CACHE or OPC_DS_DEVICE dwCountThe number of items to be read.phServerThe list of server item handles for the items to be readppItemValuesArray of structures in which the item values are returned.ppErrorsArray of HRESULTs indicating the success of the individual item reads. The errors correspond to the handles passed in phServer. This indicates whether the read succeeded in obtaining a defined value, quality and timestamp. NOTE any FAILED error code indicates that the corresponding Value, Quality and Time stamp are UNDEFINED.OPCITEMSTATE结构说明typedef struct OPCHANDLEhClient;FILETIMEftTimeStamp;WORDwQuality;WORDwReserved;VARIANTvDataValue; OPCITEMSTATE;MemberDescriptionhClientthe client provided handle for this itemftTimeStampUTC TimeStamp for this items value. If the device cannot provide a timestamp then the server should provide one.wQualityThe quality of this item. vDataValueThe value itself as a variant./释放同步接口m_IOPCSyncIO-Release();m_IOPCSyncIO = NULL;/释放item管理接口m_IOPCItemMgt-Release();m_IOPCItemMgt = NULL;/释放 OPC服务器m_IOPCServer-Release();m_IOPCServer = NULL;/关闭COM库CoUninitialize();异步OPC数据读取查询group对象的异步接口m_IOPCItemMgt-QueryInterface(IID_IOPCAsyncIO2, (void*)&m_IOPCAsyncIO2);参数：1. IID_IOPCAsyncIO2 异步2.0接口 2.服务器返回的用于操作异步接口的指针。获得IOPCGroupStateMgt接口m_IOPCItemMgt-QueryInterface(IID_IOPCGroupStateMgt,(void*) &m_IOPCGroupStateMgt);参数：1. IID_IOPCGroupStateMgt 组状态接口 2.服务器返回的用于操作接口的指针。建立异步回调CComObject* pCOPCDataCallback;/ 回调对象的指针通过ATL模板创建回调对象的实例CComObject:CreateInstance(&pCOPCDataCallback); 查询IUnknown接口LPUNKNOWN pCbUnk;pCbUnk = pCOPCDataCallback-GetUnknown();建立一个服务器的连接点与客户程序接收器之间的连接AtlAdvise 函数告诉一个可连接对象客户想从此可连接对象接收事件.该函数封装实现接收事件HRESULT hRes = AtlAdvise(m_IOPCGroupStateMgt, / in 获得的IOPCGroupStateMgt接口指针pCbUnk, / in IUnknown接口指针IID_IOPCDataCallback,/ in回调接口 &m_dwAdvise / out 服务器返回的回调接口的标识);异步OPC数据释放退出连接点时使用AtlUnadviseHRESULT hRes = AtlUnadvise(m_IOPCGroupStateMgt, IID_IOPCDataCallback, m_dwAdvise);m_IOPCGroupStateMgt-Release();/异步的以下释放类似同步的OPC释放m_IOPCItemMgt-RemoveItems(1,/ in 删除项目phServer,/ in 被删除项目的服务句柄&pErrors/ out 有错误时的指针);m_IOPCAsyncIO2-Release();/释放异步接口m_IOPCAsyncIO2 = NULL;m_IOPCItemMgt-Release();/释放ITEM接口m_IOPCItemMgt = NULL;m_IOPCServer-Release();/释放OPC服务m_IOPCServer = NULL;CoUninitialize();/释放COM用于客户端的异步回调定义 功能:客户提供用来操作组的数据变化和刷新IOPCDataCallbackIOPCDataCallback:OnDataChangeHRESULT OnDataChange(in DWORD dwTransid,in OPCHANDLE hGroup,in HRESULT hrMasterquality,in HRESULT hrMastererror,in DWORD dwCount,in, sizeis(dwCount) OPCHANDLE * phClientItems,in, sizeis(dwCount) VARIANT * pvValues,in, sizeis(dwCount) WORD * pwQualities,in, sizeis(dwCount) FILETIME * pftTimeStamps,in, sizeis(dwCount) HRESULT *pErrors);参数描述dwTransid 事务标识符，如果是一般的回调，此值为0。hGroup 组的客户句柄。hrMasterquality S_OK ，如果OPC_QUALITY_MASK 是OPC_QUALITY_GOOD,否则为 S_FALSE 。hrMastererror 如果无错误，返回S_OK，否则返回S_FALSE.。dwCount 读取的在客户句柄表里的项数目。phClientItems 数据发生变化的项的客户句柄表。.pvValues 数据发生变化的项的VARIANTS 类型数据表。pwQualities 读取的项的品质值的表。pftTimeStamps读取的项的时间戳表。pErrors 项的HRESULTS 表。如果数据项的品质变为UNCERTAIN 或者 BAD，这里返回附加的服务器提供的更有用的错误信息。ParametersDescriptiondwTransid0 if the call is the result of an ordinary subscription. If the call is the result of a call to Refresh2 then this is the value passed to Refresh2.hGroupThe Client handle of the grouphrMasterqualityS_OK if OPC_QUALITY_MASK for all qualities are OPC_QUALITY_GOOD, S_FALSE otherwise.hrMastererrorS_OK if all errors are S_OK, S_FALSE otherwise.dwCountThe number of items in the client handle listphClientItemsThe list of client handles for the items which have changed.pvValuesA List of VARIANTS containing the values (in RequestedDataType) for the items which have changed.pwQualitiesA List of Quality values for the itemspftTimeStampsA list of TimeStamps for the itemspErrorsA list of HRESULTS for the items. If the quality of a data item has changed to UNCERTAIN or BAD., this field allows the server to return additional server specific errors which provide more useful information to the user. See below.HRESULT 返回码返回码描述S_OK 客户总是返回S_OK。ppErrors 返回码返回码描述S_OK 项的数据的品质是好的（OPC_QUALITY_GOOD）。E_FAIL 项的操作失败。OPC_E_BADRIGHTS操作的项是不可读的。OPC_E_UNKNOWNITEMID项在服务器的地址空间是不可用的。S_xxx, E_xxxS_xxx 卖方特殊信息。E_xxx 卖方指定的特殊错误。对于所有的S_xxx 错误码，客户需要假设相应的值，品质和时间戳都已经定义好了，不管品质是UNCERTAIN 或者BAD，建议服务器卖主提供关于UNCRTAIN 或BAD 项的附加的信息。回调发生在以下情况：一个或者多个的数据变化事件。事件在活动Group 中的活动项的值或者品质发生变化时发生。回调不会以超过刷新速率的速度发生。一般而言，除非值或者品质发生变化，否则回调不会发生。transaction ID 为0。通过AsyncIO2 接口的刷新请求。一旦请求发生，在活动Group 中的活动项都会刷新。Transaction ID 不为0。OPCDataCallback:OnReadCompleteHRESULT OnReadComplete(in DWORD dwTransid, /事务标识符，如果是一般的回调，此值为0。in OPCHANDLE hGroup, /组的客户句柄。in HRESULT hrMasterquality,/S_OK ，如果OPC_QUALITY_MASK 是OPC_QUALITY_GOOD,否则为 S_FALSE 。in HRESULT hrMastererror,/如果无错误，返回S_OK，否则返回S_FALSE.。in DWORD dwCount, /客户句柄里的项数目in, sizeis(dwCount) OPCHANDLE * phClientItems, /项的客户句柄表in, sizeis(dwCount) VARIANT * pvValues, /数据发生变化的项的VARIANTS 类型数据表。in, sizeis(dwCount) WORD * pwQualities,/ 读取的项的品质值的表。in, sizeis(dwCount) FILETIME * pftTimeStamps,/ 读取的项的时间戳表。in, sizeis(dwCount) HRESULT *pErrors/项的HRESULTS 表。如果数据项的品质变为UNCERTAIN 或者 BAD，这里返回附加的服务器提供的更有用的错误信息);DescriptionThis method is provided by the client to handle notifications from the OPC Group on completion of Async Reads.ParametersDescriptiondwTransidThe TransactionID returned to the client when the Read was initiated.hGroupThe Client handle of the grouphrMasterqualityS_OK if OPC_QUALITY_MASK for all qualities are OPC_QUALITY_GOOD, S_FALSE otherwise.hrMastererrorS_OK if all errors are S_OK, S_FALSE otherwise.dwCountThe number of items in the client handle, values, qualities, times and errors lists. This may be less than the number of items passed to Read. Items for whic errors were detected and returned from Read are not included in the callback.phClientItemsThe list of client handles for the items which were read. This is NOT guarenteed to be in any particular order although it will match the values, qualities, times and errors array.pvValuesA List of VARIANTS containing the values (in RequestedDataType) for the items.pwQualitiesA List of Quality values for the itemspftTimeStampsA list of TimeStamps for the itemspErrorsA list of HRESULTS for the items. If the system is unable to return data for an item, this field allows the server to return additional server specific error