1、OPC Custom Interface1OPC Automation Interface2Edition: 3C79000G7076C22501OPC Server InterfaceManualThis manual is based on version 2.0 of the OPCspecification from the OPC Foundation.This manual is available only in English.ComputingiOPC Server Interface C7900G7076C22501Contents1 OPC Custom Interfac
2、e 1-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.1 Creating and Using an OLE Object in C/C+ 1-2. . . . . . . . . . . . . . . . . . . . . . . . 1.2 Additional Information about the Interface Description for the OPC CustomInterface 1-5. . . . .
3、 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.3 The “OPC Server” Object 1-6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.4 Objects of the “OPC Group” Class 1-11. . . . . . . . . . . . . . . . . . . . . . .
4、 . . . . . . . . . . 1.5 IDataObject Interface 1-16. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 OPC Automation Interface 2-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.1 Creating and Using an OLE Object in
5、 Visual Basic 2-2. . . . . . . . . . . . . . . . . . . 2.2 Object Model for the Automation Interface 2-5. . . . . . . . . . . . . . . . . . . . . . . . . . 2.3 The “OPCServer” Object 2-6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.4 The “OPCBrowser” Object 2-8.
6、 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.5 The “OPCGroups” Collection Object 2-10. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.6 The “OPCGroup” Object 2-12. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.7 T
7、he “OPCItems” Collection Object 2-15. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.8 The “OPCItem” Object 2-17. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Figures1-1 OPC Server Object 1-6. . . . . . . . . . . . . . . . . . . . . . . . . .
8、 . . . . . . . . . . . . . . . . . . . . 1-2 OPC Group Object 1-11. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3 IAdviseSink (Client) and IDataObject (Server) Interfaces 1-16. . . . . . . . . . . . . . 2-1 Activating the Reference for the Automation I
9、nterface 2-2. . . . . . . . . . . . . . . . 2-2 Object Model for the Automation Interface 2-5. . . . . . . . . . . . . . . . . . . . . . . . . . Tables1-1 Objects and Interfaces of the OPC Custom Interface 1-5. . . . . . . . . . . . . . . . 2-1 Properties of the “OPCServer” Object 2-6. . . . . . . .
10、 . . . . . . . . . . . . . . . . . . . . . 2-2 Properties of the “OPCBrowser” Object 2-8. . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3 Properties of the “OPCGroups” Object 2-10. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4 Properties of the “OPCGroup” Object 2-12. . . . .
11、 . . . . . . . . . . . . . . . . . . . . . . . . . 2-5 Properties of the “OPCItems” Collection Object 2-15. . . . . . . . . . . . . . . . . . . . . 2-6 Properties of the “OPCItem” Object 2-17. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1OPC Server Interface C7900G7076C22501OPC Cus
12、tom InterfaceChapter OverviewThis chapter shows how to use the OPC custom interface. It also lists theinterfaces and methods of the OPC customer interface. This is not a detailedinterface description but contains supplementary information and notes relatingspecifically to the Computing software.Ther
13、e is now an extended version of the OPC custom interface, specification 2.0.Version 2.0 supplements the existing OPC custom interface in several aspectsparticularly those simplifying the handling of asynchronous communication.The interfaces of Version 1.0 of the OPC interface are completely upwardsc
14、ompatible with Version 2.0.Section Description Page1.1 Creating and Using an OLE Object in C/C+ 1-21.2 Additional Information about the Interface Description for the OPCCustom Interface1-51.3 The “OPC Server” Object 1-61.4 Objects of the “OPC Group” Class 1-111.5 IDataObject Interface 1-161OPC Custo
15、m Interface1-2OPC Server Interface C7900G7076C225011.1 Creating and Using an OLE Object in C/C+The following sections illustrate step-by-step how you can call the methods of aninstance of an OLE class in C+. Note the difference between the term “Class” inOLE and in C+:C0083 OLE Classes: A Windows ob
16、ject is an instance of an OLE class. The term OLEclass differs from the class in C+.C0083 C+ Classes: A class in C+ is a type definition. An OLE class is, however, anobject description and does not contain types.Class Identification CodeEach OLE class can be identified uniquely by a 128-bit long ide
17、ntification code, theCLSID. This is used by the operating system for the unique assignment of a DLLor EXE file that implements this class. A client that wishes to use an object of aclass requires only the CLSID.ProgIDTo simplify the identification of OPC servers, there is normally a readable name,th
18、e ProgID assigned in the CLSIDs. While a CLSID is always unique due to thealgorithm for compilation, it is possible that a ProgID exists more than once. Justlike the CLSID, the ProgID is specified by the vendor of an OPC server.The ProgID for the OPC server of Computing is: OPCServer.WinACCreating a
19、 COM ObjectA COM object is created in five steps:1. Initialize COM.2. Query the CLSID.3. Create an Object.4. Call an OPC function.5. Release the interfaces used.Step 1: Initialize COMBefore you can use the functions of COM, the COM library must be initialized withthe following call:HRESULT r1; r1 =
20、CoInitialize(NULL);OPC Custom Interface1-3OPC Server Interface C7900G7076C22501Step 2: Query the CLSIDIf the name of an object is known, the CLSID can be queried using the OLEfunction “CLSIDFromProgID”.Example: The following program section illustrates how to query the CLSID for theOPC server for Co
21、mputing.CLSID clsid; / Get the CLSID from the Namer1 = CLSIDFromProgID(L”OPCServer.WinAC”),Step 3: Create an ObjectIf a client wants to use an object, it transfers the CLSID to the operating systemand requests an object instance. Regardless of where the server is located, theobject request is always
22、 directed to COM.The “CoCreateInstance” function creates an object belonging to the required class.This function includes certain intermediate steps via the “IClassFactory” interface.Creating an object using IClassFactory is more efficient when several objects of aclass must be created.Example: The
23、following lines show how an object of the class “OPC server” withreference to the “IUnknown” interface can be created.IUnknown * pOPCUnknown;r1 = CoCreateInstance (clsid, NULL, CLSCTX_LOCAL_SERVER,IID_IUnknown, (void*) Step 4: Call an OPC FunctionIn this step, a method of the “IOPCServer” interface
24、of the created object will beused to learn the status of the server. First, a pointer to the “IOPCServer” interfaceis made available via “IUnKnown”. Finally, the “GetStatus” method is called.Example: The program shown below outputs the status of the server and thevendor information. If the “GetStatu
25、s” method is called successfully, the OPCserver allocates the memory areas for the return information via the “IMalloc”interface. The user must release these memory areas again.IOPCServer *pOPCServer;OPCSERVERSTATUS *pss;r1 = pOPCUnknownQueryInterface(IID_IOPCServer,(void*)r1 = pOPCServer GetStatus(
26、printf(”Status.szVendorInfo = %lsn”, pss szVendorInfo);/ Remember to release the memory returned by the methodpIMallocFree(pssszVendorInfo);pIMallocFree(pss);OPC Custom Interface1-4OPC Server Interface C7900G7076C22501Step 5: Release the Interfaces UsedObjects include reference counters to detect wh
27、en the object is no longer requiredand can remove itself from memory. Each time the “QueryInterface” function iscalled, the reference counter is incremented. To release the object, the countermust be reset.Example: Using the following commands, the reference counter for the interfaces“IUnknown” and
28、“IOPCServer” is reset.pOPCServerRelease();pOPCUnknownRelease();OPC Custom Interface1-5OPC Server Interface C7900G7076C225011.2 Additional Information about the Interface Description for theOPC Custom InterfaceA comprehensive description of the OPC interfaces is beyond the scope of thismanual. This i
29、s supplied as a file along with this product as an original Englishdocument from the OPC Foundation. The documents are located in the ”DOC”directory in the product directory of the OPC server for Computing.The following supplementary information about the interfaces lists the objects ofOPC, their in
30、terfaces and the methods defined in these interfaces and points outparticular characteristics of the OPC server for Computing.Return ValuesAll the listed methods return a result of the type HRESULT.Overview of the Objects and InterfacesTable 1-1 Objects and Interfaces of the OPC Custom Interface Obj
31、ect InterfaceIOPCServerIOPCServerPublicGroups (optional)IOPCBrowseServerAddressSpace (optional)OPCServerIOPCItemProperties (new with V 2.0)IConnectionPointContainer (new with V 2.0)IOPCCommon (new with V 2.0)IPersistFile (optional)IOPCGroupStateMgtIOPCPublicGroupStateMgt (optional)IOPCASyncIO2 (new
32、with V 2.0)IOPCAsyncIO (no longer necessary with V2.0)OPCGroupIOPCItemMgtIConnectionPointContainer (new with V 2.0)IOPCSyncIOIDataObject (no longer necessary with V2.0)EnumOPCItemAttributes IEnumOPCItemAttributesOPC Custom Interface1-6OPC Server Interface C7900G7076C225011.3 The “OPC Server” ObjectT
33、he OPC server class has various attributes that contain information about thestatus, the version etc. of an OPC server object. The OPC server class also hasmethods with which a client can manage the objects of the OPC group class. Aclient application addresses only an object of this class directly u
34、sing COMmechanisms. The other objects are created by corresponding OPC methods.The methods of the IOPCServer interface are used to manage the objects in theOPC group class. Using the methods of the IOPCBrowseServerAddressSpaceinterface, it is possible to investigate the address area of the server.Fi
35、gure 1-1 illustrates the “OPC server” object with its interfaces.OPCServer ObjectIUnknownIOPCItemsProperties (V2.0)IConnectionPointContainer (V2.0)IOPCCommon (V2.0)IOPCBrowseServerAddressSpaceIOPCServerFigure 1-1 OPC Server ObjectIOPCServer InterfaceThis interface contains methods to manage groups w
36、ithin a server object. It is alsopossible to obtain information about the current status of the server.AddGroup ( szName, bActive, dwRequestedUpdateRate, hClientGroup,pTimeBias, pPercentDeadband, dwLCID, phServerGroup,pRevisedUpdateRate, riid, ppUnk )Creates a group in the server object.Notes:C0083
37、The ”pTimeBias” parameter is not evaluated by the OPC server for Computing.C0083 “LCID” is irrelevant for the OPC server for Computing.C0083 The “UpdateRate” is specified by the configuration parameter “Minimum UpdateRate” as a multiple of the configuration value.C0083 The “pPercentDeadband” paramet
38、er is only effective for variables of the real(VT_R4) type.C0083 If the “szName” parameter is empty, a name is generated beginning with theunderscore character (for example, “_123456”). User-defined names shouldtherefore not begin with the underscore character.OPC Custom Interface1-7OPC Server Inter
39、face C7900G7076C22501CreateGroupEnumerator ( dwScope, riid, ppUnk )Creates various enumerators for the group.Note: Since there are no public groups in the OPC server for Computing, the returnvalues for the parameter ”dwScope” ”.PRIVATE” and ”.PUBLIC” are identical.GetErrorString ( dwError, dwLocale,
40、 ppString )Supplies the error message for a specific error code.Note: The OPC server for Computing supports German and English error texts.Errors detected by the Windows operating system are explained in the language inwhich the operating system was installed.GetGroupByName ( szName, riid, ppUnk )Su
41、pplies an additional interface pointer for the name of a private group, in otherwords the reference counter is incremented.GetStatus ( ppServerStatus )Supplies the status information of the server.Note: The return value of the OPC server for Computing is the name and theversion of the OPC server.Rem
42、oveGroup ( hServerGroup, bForce )Deletes a group on the server.Note: The OPC server for Computing does not support the use of the ”bForce”parameter. It is not possible to delete groups to which references are still active.IOPCBrowseServerAddressSpace InterfaceThis interface contains methods with whi
43、ch the address area of the server can bequeried. The address area contains all the OPC items known to the server.BrowseAccessPaths ( szItemID, ppIEnumString )This provides the possibility of querying the access path of an ItemID.Note: Not required with the OPC server for Computing.OPC Custom Interfa
44、ce1-8OPC Server Interface C7900G7076C22501BrowseOPCItemIDs ( dwBrowseFilterType, szFilterCriteria,vtDataTypeFilter, dwAccessRightsFilter, ppIEnumString )Supplies a string of the type ”IEnumString” whose content is specified by the callparameters. The position from which the list is created can be se
45、t using the”ChangeBrowsePosition” method.Notes:C0083 “BRANCH” excludes the filters for Type and AccessRights.C0083 The rules for creating a filter are as follows: Asterisk (*) Any character string, including empty strings Plus (+) Any character string, however at least one character Question marks (
46、?) Any single character Square brackets ( ) One single character from the specified setC0083 To use one of the filter characters, this must be preceded by a back slash ().ChangeBrowsePosition ( dwBrowseDirection, szString )Allows you to browse through the address area. You can change to the higher l
47、evelor to a branch.GetItemID ( szItemDataID, szItemID )Creates a complete ItemID in the hierarchical address area. This function isnecessary since browsing itself only provides the designations below the currentnode.Note: The description of GetItemID in OPC specification is inconsistent with thedesc
48、ription of ChangeBrowsePosition. With ChangeBrowsePosition, it is notpossible to specify a complete ItemID. For this reason, the OPC server forComputing only currently supports the command GetItemID for single leaves(LEAF).QueryOrganization ( pNameSpaceType )Supplies the structure of the address are
49、a. The address area can be organizedwith a flat or hierarchical structure.Note: The structure of the address area of the OPC server for Computing isstructured hierarchically.OPC Custom Interface1-9OPC Server Interface C7900G7076C22501IOPCCommon Interface (Version 2.0)This interface of version 2.0 of the OPC Custom Interface contains methodsallowing the language settings and the name of the client to be made known to theserver.SetLocaleID (dwLcid)Sets the language code of the server. The language code specifies the language inwhich
