帮助手册kingscada3.51运行系统api使用

1、SCADA 运行系统 API 使用帮助亚控科技发展文件：项目：项目名称： KingScada3.51部门：开发部版 本 号：1.0受控状态：0密级：总 页 数：正文：附录：0编制：日期：审核：日期：批准：日期：版本Review日期版本号Review 人说明日期版本号作者说明2009-11-191.0 版创建2015-04-253.5 版修订 KS3.51 新增内容目录SCADA 运行系统 API 使用帮助11简介6概述6使用说明6相关类型和数据结构6宏定义6错误码7质量戳7通用数据类型822.4.12.4.22.4.32.4.4基本数据类型8时间戳类型9整型数组10字符串数组10BLOB 数据

2、类型10可变数据值类型10枚举数据类型11KXTVSionRole11KXTVRedundantMode11KXTVTagType11KXTVTagSubType112.5.5 KXTVTagDaype112.5.6 KXTVValueDaype12KXTVAlarmType12变量域相关枚举类型13运行系统相关数据类型13连接选项13运行系统配置信息13用户安全相关类型142.7.12.7.22.7.32.7.42.7.5用户属性14用户属性数组15角色属性15角色属性数组15安全区属性162.8 变量相关数据类型162.8.12.8.22.8.3变量基本信息16变量值信息数组16结构模板成

3、员属性信息16KXTVStructTemplateMember172.8.4 结构模板属性信息172.9 变量数据相关数据结构172.9.12.9.22.9.3变量实时数据信息17变量域值修改信息17变量值修改信息182.10 变量2.10.1确认相关数据结构18确认变量信息183 API 接口函数19辅助函数19KXTVAPIInitalize19KXTVAPIRelease19KXTVAPITrace19KXTVAPIGetErrorDescription19KXTVAPIFreeStringArray20KXTVAPIFreeArray20KXTVAPIFreeVaribleValue2

4、0KXTVAPIValueInit20KXTVAPIValueCopy20KXTVAPIUnicodeStringDuplicate21KXTVAPIUnicodeStringFree21服务器相关函数21KXTVServerConnect21KXTVServerIsConnected21KXTVServerDisconnect22KXTVServerGetConfiguration22KXTVServerFreeConfiguration22KXTVServerGetTime22KXTVServerGetRedunSus23变量相关函数23KXTVTagGetAllTagName23KXTV

5、TagGetAllAlarmTagName23KXTVTagGetAllHisTagName24KXTVAPIEnumChannelAllDeviceNames24KXTVTagGetAllTagBasicInfo24KXTVTagGetTagBasicInfo25KXTVTagGetTagNamebyID25KXTVTagGetTagIDbyName26KXTVTagFreeTagBasicInfo26KXTVTagFreeTagBasicInfoArray26实时数据相关函数27KXTVTagSetTagValues27KXTVTagSetTagValues227KXTVTagGetTag

6、Values27KXTVTagSetFieldValues28KXTVTagGetFieldValues28KXTVTagSetTagDatas29KXTVTagGetTagDatas29KXTVTagSubscribeTagData30用户安全数据相关函数303.5.1 KXTVSecurityCheckUsassword303.5.2 KXTVSecurityGetAllUserName30KXTVSecurityGetUsKXTVSecuritySetUsKXTVSecurityFreeUsroperty31roperty31roperty32KXTVSecurityAddUser32K

7、XTVSecurityDelUser32KXTVSecurityLogon32KXTVSecurityLogoff33KXTVSecurityGetUserNamebyID33KXTVSecurityGetUserIDbyName34KXTVSecurityGetAllRoleName34KXTVSecurityGetRoleProperty34KXTVSecurityFreeRoleProperty35KXTVSecurityAddRole35KXTVSecurityDelRole35KXTVSecuritySetRoleProperty35KXTVSecurityGetRoleNameby

8、ID36KXTVSecurityGetRoleIDbyName36KXTVSecurityGetUserRole37KXTVSecurityGetRoleUser37KXTVSecurityAddUserRole37KXTVSecurityDelUserRole38KXTVSecurityAddRoleUser38KXTVSecurityDelRoleUser38KXTVSecurityGetAllUserGroupName39KXTVSecurityGetGroupUserName39KXTVSecurityAddUserGroup40KXTVSecurityDelUserGroup40KX

9、TVSecurityAddUsertoGroup40KXTVSecurityDelUserfromGroup40KXTVSecurityModifyUserGroupName413.6确认函数41KXTVAEAckTags41KXTVAEAckAlarmGroups41KXTVAEAckTagsbyID42KXTVAEAckAlarmGroupsbyID42回调函数和其函数423.7.13.7.23.7.33.7.43.7.53.7.63.7.7变量实时数据变化订阅回调43用户属性订阅回调43角色属性订阅回调43用户角色关联信息订阅回调44用户组属性订阅回调44用户用户组关联信息订阅回调45安

10、全区属性订阅回调45CALLBACK *KXTVSECURITYZONEPROP_SUBSCRIBE_CALLBACKFUNC )(46KXTV_RET KXTVAPI KXTVSecurityRegisterSecurityZonePropCallbackFunc (461简介1.1 概述SCADA3.51 运行系统 API 接口（以下简称 API 接口）遵循 C 语言语法，大致提供了五种类型的接口：1.服务器连接、接口：主要用于和 SCADA3.51 运行系统建立和断开连接，对连接状态进行查询，以及服务器的状态和信息；2.变量管理，变量数据接口：接口用于获取运行系统的变量信息，包括属行系统

11、的历史变量，属于的操作；库的变量，该接口还可以用于实时变量数据，包括对各种不同变量域3.用户权限和安全管理接口：主要用于设置用户信息，用户角色（用户权限），设置用户组等；4.确认接口：对变量、变量组产生的信息作出确认的接口；5.辅助接口：主要完成复杂数据类型内存，帮助用户提高编程的效率，减少出错概率；1.2 使用说明使用本 API 需要下列文件：kxTVAPI.h kxTVAPIH.hkxTVAPI.libkxTVAllSORBA35x86.dll使用本 API 做程序开发时 kxTVAPI.h、kxTVAPIH.h 需要被程序文件包含，kxTVAll、kxTVAPI.lib 需要放置在程序编

12、译时可查找到的路径下。使用本 API 做程序运行时程序运行时需要将 kxTVAll、SORBA35x86.dll 放置在程序可查找到的运行环境路径下。kxTVAll、SORBA.dll 文件也可在SCADA 安装盘下找到。2相关类型和数据结构2.1 宏定义#define KXTVAPI_stdcall所有接口函数均使用 stdcall 调用规范#define KXWSTR(str)表示 UNICODE 字符串#define KXOK(err)L#str( (KXTV_32)(err) = 0 )该宏用来判断函数的返回码是否执行成功#define KXERR(err)( (KXTV_32)(er

13、r) != 0 )该宏用来判断函数的返回码是否执行失败#define IN #define OUT #define IN_OUT以上三个宏用于标示接口函数中参数的输入输出特性2.2 错误码API 中定义的错误码如表 1 所示。这里定义的错误码都是 API 接口函数本身产生的错误码，运行系统产生的错误码为大于 0 的数字，运行系统本身返回的错误码并不在下表描述，只有返回值为 0 时才表示成功。表 1. 运行系统 API 接口相关错误码2.3 质量戳运行系统的变量数据都带有质量戳， 变量数据的质量戳是一个 32 位的无符号整数。KXTVDataQuality 枚举类型定义了质量戳各标志位的含义。质

14、量戳的低八位由质量戳 Q、子状态S 和限制状态 L，分布为SSSSLL。即质量戳占高 2 位，子状态间 4 位，限制状态占低 2 位。KXTVDA _OPC_QUALITY_MASK 掩码用来获得质量戳Q; KXTVDA_OPC_S掩码用来获得子状态S; KXTVDA_OPC_LIMIT_MASK 掩码用来获得限制状态。下面列表解释了其他枚举值的含义：表 2. 运行系统 API 质量戳US_MASK枚举值描述KXTVDA_OPC_BAD坏数据KXTVDA_OPC_UNCERTAIN不确定数据KXTVDA_OPC_NA保留位KXTVDA_OPC_GOOD好数据KXTVDA_OPC_CONFIG_

15、ERROR坏数据，由于配置错误KXTVDA_OPC_NOT_CONNECTED坏数据，由于没有连接设备KXTVDA_OPC_DEVICE_FAILURE坏数据，由于设备错误KXTVDA_OPC_SENSOR_FAILURE坏数据，由于传感器失败，数据超过上下限KXTVDA_OPC_LAST_KNOWN坏数据，由于通讯失败，采用上一次的值M_FAILURE坏数据，由于通讯失败，并且没有上一值可用KXTVDA_OPC_OUT_OF_SERVICE坏数据，由于设备停机错误码描述KXTV_SUC0 成功KXTV_FAILED-1 失败KXTVERR_SYSTEM_ERROR-2 系统错误KXTVERR

16、_INVALIDHANDLE-3 无效的句柄KXTVERR_INVALIDARGS-4 无效的参数KXTVERR_OUTOFMEMORY-5 内存不足KXTVERR_NETWORK-6 网络连接错误KXTVERR_NOT_SUPPORTED-7 功能不支持接口中还定义了一些与质量戳相关的宏。判断数据质量是否是坏的：#define KXTVIsDataBad( dataQuality )(dataQuality) & KXTVDA_OPC_QUALITY_MASK) = KXTVDA_OPC_BAD )判断数据质量是否是好的：#define KXTVIsDataGood( dataQuality

17、 )(dataQuality) & KXTVDA_OPC_QUALITY_MASK) = KXTVDA_OPC_GOOD )判断数据质量是否是不可靠的：#define KXTVIsDataUncertain( dataQuality )(dataQuality) & KXTVDA_OPC_QUALITY_MASK) = KXTVDA_OPC_UNCERTAIN )得到限制状态：#define KXTVGetQualityLimit( dataQuality ) (dataQuality) & KXTVDA_OPC_LIMIT_MASK )2.4 通用数据类型2.4.1基本数据类型API 中定义

18、的基本数据类型如表 3 所示。KXTVDA_OPC_WAITING_FOR_INITIAL_DATA坏数据，由于尚未取得设备数据KXTVDA_OPC_LAST_USABLE不确定数据，由于采用上一个值KXTVDA_OPC_SENSOR_CAL不确定数据，由于传感器值不精确KXTVDA_OPC_EGU_EXCEEDED不确定数据，由于超过量程KXTVDA_OPC_SUB_NORMAL不确定数据，由于数据从多个数据源得到，缺乏足够多的好数据KXTVDA_OPC_LOCAL_OVERRIDE好数据，但数值被覆盖KXTVDA_OPC_LIMIT_OK上下限都没有超过KXTVDA_OPC_LIMIT_L

19、OW超过下限KXTVDA_OPC_LIMIT_HIGH超过上限KXTVDA_OPC_LIMIT_CONST常量KXTVDA_OPCHDA_EXTRADATA同一时间戳可能存在多个数据，可能是好数据，坏数据或不确定数据KXTVDA_OPCHDA_OLATED插值数据，可能是好数据，坏数据或不确定数据KXTVDA_OPCHDA_RAW原始数据，可能是好数据，坏数据或不确定数据KXTVDA_OPCHDA_CALCULATED计算值，可能是好数据，坏数据或不确定数据KXTVDA_OPCHDA_NOBOUND没有上界或下界（时间超出范围），是坏数据KXTVDA_OPCHDA_NODATA没有数据，是坏数

20、据KXTVDA_OPCHDA_DATALOST数据丢失，可能由于停止导致，是坏数据KXTVDA_OPCHDA_CONVER标订或转换错误，可能是坏数据或不确定数据KXTVDA_OPCHDA_PARTIAL不完整时间区间的统计值，可能是好数据，坏数据或不确定数据表 3.运行系统 API 接口相关基本数据类型2.4.2时间戳类型时间戳类型KXTVTimeStamp 的定义如下：typedef struct KXTVTimeStampKXTV_U KXTV_U3216Seconds; Millisecs; KXTV_TIMESTAMP , *PKXTV_TIMESTAMP;时间戳精确到毫秒，其中Se

21、conds 表示自 1970/01/01 00:00:00()以来的秒数，时间戳中不足一秒的由毫秒数 Millisecs 表示，所以 Millisecs 只能取 0999 之间的整数。数据类型对应 C 数据类型描述KXTV _BOOLboolKXTV _CHARcharKXTV _WCHARwchar_tKXTV _BYTEunsigned charKXTV _unsigned charKXTV _FLOAT32floatKXTV _FLOAT64doubleKXTV _8signed charKXTV _U8unsigned charKXTV _16shortKXTV _U16unsigne

22、d shortKXTV _32longKXTV _U32unsigned longKXTV _64 64KXTV _U64unsigned 64KXTV _VOIDvoid空数据类型KXTV _PTRvoid*空指针类型KXTV _BINARYunsigned char*二进制数据类型KXTV _STRchar*ANSI 字符串指针KXTV _CSTRconst char*ANSI 常量字符串指针KXTV _WSTRwchar*UNICODE 字符串指针KXTV _CWSTRconst whar*UNICODE 常量字符串指针KXTV _STR_ARRAYchar*ANSI 字符串数组KXTV

23、 _WSTR_ARRAYwchar_t*UNICODE 字符串数组KXTV_RETlongAPI 接口函数返回码KXTV_HANDLEvoid*数据连接句柄2.4.3整型数组用于表示一个 KS_U32 型的整数数组，SizeofArray 表示数组中元素的个数， Array 为指向一个 KS_U32 型数组的指针。typedef struct KXTVArrayKXTV_U KXTV_U3232*SizeofArray; Array;_ARRAY;KXTV_ARRAY,*PKXTV_2.4.4字符串数组用于表示一个 unicode 字符串数组，SizeOfArray 表示数组中元素的个数，St

24、ringArray 为指向一个字符串数组的指针，数组的每个元素是一个字符串。typedef struct KXTVStringArrayKXTV_U32SizeOfArray; StringArray;KXTV_WSTR_ARRAYKXTV_STRING_ARRAY,*PKXTV_STRING_ARRAY;2.4.5BLOB 数据类型BLOB 类型是二进制长对象类型，Len 表示了该对象长度（字节数），Data 指向实际的数据起始地址。typedef struct KXTVBlobKXTV_U32Len; Data;KXTV_BINARY KXTV_BLOB, *PKXTV_BLOB;2.4.

25、6可变数据值类型该结构体可以各种数据类型的数据值，Daype 标示了结构体中的数据类型，参数见KXTVValueDaype（2.5.6 节），结构还包含了一个数据值联合体，根据 Daype 数据类型在相应成员中获取值、赋值，例如数据类型为 KXTVDT_BOOL，值就在 bitVal 中，数据类型为KXTVDT_R8，值就在 r8Val 中。typedef struct KXTVValueKXTV_UunionKXTV_ KXTV_ KXTV_ KXTV_ KXTV_16Daype;bitVal; i1Val; i2Val; i4Val; i8Val; ui1Val; ui2Val; ui4V

26、al; ui8Val; r4Val; r8Val; strVal; wstrVal;81632648163264KXTV_U KXTV_U KXTV_U KXTV_UKXTV_FLOAT32 KXTV_FLOAT64 KXTV_STR KXTV_WSTRKXTV_BLOB FILETIME KXTV_TIMESTAMP KXTV_VARIANTblobVal; ftVal; tsVal; varVal; KXTV_VALUE , *PKXTV_VALUE;2.5 枚举数据类型枚举数据类型定义了API 接口中需要使用到的常量值，来标示不同的状态、类型等。2.5.1KXTVS站点角色ionRole

27、2.5.2KXTVS KXTVS KXTVS KXTVS KXTVS KXTVSKXTVSION_ROLE_SINGLENODE，单机ION_ROLE_CNT，客户端ION_ROLE_REALDATA_SERVER，实时数据服务器ION_ROLE_ALARMDATA_SERVER，数据服务器ION_ROLE_HISDATA_SERVER，历史数据服务器 ION_ROLE_LOGON_SERVER，登陆服务器ION_ROLE_TIME_SERVER，校时服务器KXTVRedundantMode冗余模式2.5.3KXTV_REDUNDANT_NONE，没有冗余 KXTV_REDUNDANT_PRI

28、MARYSLAVE，主从冗余 KXTV_REDUNDANT_PEERTOPEER，对等冗余KXTVTagType运行系统中的变量类型2.5.4KXTVTAGTYPE_NONE，无类型 KXTVTAGTYPE_SYS，系统变量KXTVTAGTYPE_BASIC，基本变量KXTVTAGTYPE_REF，变量KXTVTAGTYPE_STRUCT，结构变量KXTVTAGTYPE_REFSTRUCT， KXTVTAGTYPE_ALMGROUP，KXTVTagSubType结构变量组变量枚举了变量子类型。2.5.5KXTVTAGSUBTYPE_NONE，无子类型KXTVTAGSUBTYPE_MEM，内存变

29、量 KXTVTAGSUBTYPE_IO，IO 变量KXTVTagDaype枚举了变量的基本数据类型。KXTVTAGDA数据类型YPE_BASIC，基本数据类型掩码，于此掩码取或结果非零，即为基本2.5.6KXTVTAGDA KXTVTAGDA KXTVTAGDA KXTVTAGDA KXTVTAGDA KXTVTAGDAKXTVValueDaYPE_DISC，离散YPE_YPE_32，整型64，长整型YPE_FLOAT，单精度浮点 YPE_DOUBLE，双精度浮点，目前暂不支持 YPE_STRING，字符串ype枚举了数据类型，接口中涉及数据值的地方，类型将为以下几种中的一种。2.5.7KXT

30、VDT_EMPTY，没有指定数据类型KXTVDT_BOOL，数据类型KXTVDT_I1，8 位整数(有符号) KXTVDT_UI1，8 位整数(无符号) KXTVDT_I2，16 位整数(有符号) KXTVDT_UI2，16 位整数(无符号) KXTVDT_I4，32 位整数(有符号) KXTVDT_UI4，32 位整数(无符号) KXTVDT_I8，64 位整数(有符号) KXTVDT_UI8，64 位整数(无符号) KXTVDT_R4，32 位浮点数 KXTVDT_R8，64 位浮点数 KXTVDT_STR，ANSI 字符串KXTVDT_WSTR，Unicode 字符串 KXTVDT_BL

31、OB，二进制数据对象 KXTVDT_VARIANT，不定数据类型 KXTVDT_FILETIME，文件时间结构类型KXTVAlarmType枚举了库产生的类型，对做出确认时，需要输入类型。KXTVALMTYPE_NONE，没有 KXTVALMTYPE_HIHI，高高 KXTVALMTYPE_HI，高 KXTVALMTYPE_LO，低 KXTVALMTYPE_LOLO，低低 KXTVALMTYPE_ROC，变化率 KXTVALMTYPE_MAJORDEV，大偏差 KXTVALMTYPE_MINORDEV，小偏差 KXTVALMTYPE_CONDITION，条件 KXTVALMTYPE_DISCO

32、PEN，离散开 KXTVALMTYPE_DISCCLOSE，离散关KXTVALMTYPE_DISCCHANGE，离散变化2.5.8变量域相关枚举类型每个变量都包含多个数据域，每个域有自己的数据类型和数据值，KXTVTagFieldID 定义了变量的各个域 ID，和 ID 一一对应，常量字符串数组 gx_tagFieldNameArray 定义了各个变量详细参见 kxTVAPI.h。，gx_tagFieldInfos_Disc、gx_tagFieldInfos_、gx_tagFieldInfos_Float、gx_tagFieldInfos_String、gx_tagFieldInfos_Alm

33、Group 五个常量结构体分别定义了离散型变量、整型变量、单精度浮点变量、字符串类型变量和组变量的域信息。结构分别说明了各种变量类型包含的域的 ID，域的数据类型，本文档不再一一枚举，详细参见kxTVAPI.h。运行系统相关数据类型连接选项在使用函数 KXTVConnectionOption 与运行系统服务器进行连接时，需要传入连接参数，它是一个结构，包括以下的成员，根据需要，在连接前要进行适当的设置。称和ServerName，被连接的服务器计算机名或地址Servort，被连接的服务器端口或其他协议的附加地址信息UserName;，用户名 Password，CnteName，Cnt 端机器名称

34、ApplicationName，Cnt 端应用程序名称NetUserFlag，网络用户标志，标示为网络用户还是本地用户 NetworkTimeout，连接超时，毫秒1-4，保留字段MaxAllowErrorsBeforeDisconnect，关闭接之前允许出现的最大连接错误数目typedef struct KXTVConnectionOptionKXTV_WSTR KXTV_WSTR KXTV_WSTR KXTV_WSTR KXTV_WSTR KXTV_WSTR KXTV_ServerName;Servort;UserName; Password;ApplicationName; C ntNa

35、me; NetUserFlag; NetworkTimeout; ConnectionFlags;1;2;3;4;KXTV_U KXTV_U KXTV_U KXTV_U32323232KXTV_WSTR KXTV_WSTRKXTV_CONNECTION_OPTION , *PKXTV_CONNECTION_OPTION;2.6.2运行系统配置信息SionName，站点名称SionRole，参见KXTVSionRole ProjectPath，工程路径SionIP，站点 IP 地址SionPort，站点端SionBackupNetIP，站点备份网络 IPSionBackupNetPort，站点备

36、份网络端RedunS RedunS RedunS RedunSRedunSionName，冗余站点名称 ionIP，冗余站点 IP ionPort，冗余站点端口ionBackupNetIP，冗余站点备份网络 IPionBackupNetPort，冗余站点备份网络端口RedunMode，冗余模式，参见 KTVRedundantMode 定义IsPrimary，是否是主机,true 主机，false 从机bBackupHisData，是否备份历史数据，true 备份，false 不备份typedef struct KXTVConfigurationKXTV_WSTRSionName; SionRo

37、le; ProjectPath; SionIP;SionPort;SionBackupNetIP; SionBackupNetPort; RedunSionName; RedunSionIP; RedunSionPort;RedunSionBackupNetIP; RedunSionBackupNetPort; RedunMode;IsPrimary; bBackupHisData;KXTV_U32KXTV_WSTR KXTV_WSTRKXTV_U32KXTV_WSTRKXTV_U32KXTV_WSTR KXTV_WSTRKXTV_U32KXTV_WSTRKXTV_U32KXTV_ KXTV_

38、 KXTV_16KXTV_CONFIGURATION,*PKXTV_CONFIGURATION;用户安全相关类型用户属性用户属性KXTVUsroperty 用于增加用户，修改用户信息，以及相关的数据改变后的回调信息中，其中成员的含义如下：UserNam，用户名ment，用户说明 UserID，用户 ID，只读属性UserTimeOut，用户超时，默认为，无超时LogonTimeOut，登录超时: 分钟，默认为，无超时UserAddTime，用户创建时间, 只读属性UserModifyTime，用户最后修改时间,只读属性typedef struct KXTVUsKXTV_WSTR KXTV_WS

39、TRropertyUserName;ment; UserID; UserTimeOut; LogonTimeOut; UserAddTime;KXTV_U FILETIM KXTV_U FILETIME3232FILETIMEUserModifyTime;KXTVUSER_PROPERTY,*PKXTVUSER_PROPERTY;2.7.2用户属性数组同时获得多个用户属性信息时，需要使用到用户属性数组。其中成员的含义如下：UserNum，用户属性数目UsropArray，指向 KXTVUSER_PROPERTY 数组的指针，该数组中包含UserNum 个用户的信息typedef struct

40、KXTVUsropertyArrayKXTV_U32UserNum;PKXTVUSER_PROPERTYUsropArray;KXTVUSER_PROPERTY_ARRAY, *PKXTVUSER_PROPERTY_ARRAY;2.7.3角色属性用户可以指定自己的角色，从而限定用户在运行系统中的操作权限。操作权限体现在操作的优先级上，以及对安全区的可操作性。角色的定义用户属性 KXTVUsroperty 用于增加角色，修改角色信息，以及相关的数据改变后的回调信息中，其中成员的含义如下：RoleName，角色名称ment，角色描述 RoleID，角色 ID，只读属性RoleTimeOut，角色超

41、时，默认为，无超时PriorityLevel，优先级Operaevel，操作权限SecurityZoneCount，可操作的安全区数量SecurityZoneIDs，可操作的安全区 ID 集合typedef struct KXTVRolePropertyKXTV_WSTR KXTV_WSTRRoleName;ment; RoleID; RoleTimeOut; PriorityLevel;KXTV_U FILETIME KXTV_U KXTV_U KXTV_U KXTV_3216163216*Operaevel;SecurityZoneCount;SecurityZoneIDs;KXTVROL

42、E_PROPERTY,*PKXTVROLE_PROPERTY;2.7.4角色属性数组同时获得多个角色属性信息时，需要使用到角色属性数组。其中成员的含义如下：RoleNum，角色属性数目RolePropArray，指向KXTVROLE_PROPERTY 数组的指针，该数组中包含UserNum 个角色的信息typedef struct KXTVRolePropertyArrayKXTV_U32RoleNum; RolePropArray;PKXTVROLE_PROPERTYKXTVROLE_PROPERTY_ARRAY, *PKXTVROLE_PROPERTY_ARRAY;2.7.5安全区属性安全

43、区属性包括了 ID 和名称SecurityZoneID，安全区 IDSecurityZoneName，安全区的名称typedef struct KXTVSecurityZonePropertyKXTV_16SecurityZoneID; SecurityZoneName;KXTV_WSTRKXTVSECURITYZONE_PROPERTY,*PKXTVSECURITYZONE_PROPERTY;变量相关数据类型变量基本信息该结构了基本的变量信息。TagName，变量名称ment，变量描述 TagID，变量 IDStructTagID，结构变量 IDAlarmGrou，组 IDTagDaype，

44、变量数据类型TagType，变量类型typedef struct KXTVTagBasicInfoKXTV_WSTR KXTV_WSTRTagName;ment; TagID; StructTagID; AlarmGrouKXTV_U KXTV_U KXTV_U KXTV_U KXTV_32323232;TagDa TagType;ype;16KXTVTAG_BASICINFO,*PKXTVTAG_BASICINFO;2.8.2变量值信息数组在同时对多个变量值信息操作时，需要使用到变量值信息数组。其中成员的含义如下：TagNum，变量数目TagBasicInfoArray，指向 KXTVTAG

45、_BASICINFO 数组的指针，该数组中包含 TagNum个变量值的信息typedef struct KXTVTagBasicInfoArrayKXTV_U32TagNum; TagBasicInfoArray;PKXTVTAG_BASICINFOKXTVTAG_BASICINFO_ARRAY,*PKXTVTAG_BASICINFO_ARRAY;2.8.3结构模板成员属性信息结构模板成员是结构模板中定义必须的，结构模板中有一个或者多个结构模板成员，其属性通过 KXTVStructTemplateMember 定义，包括：MemberName，成员名称 MemberID，成员 ID Membe

46、rType，参见 KXTagTypeMemberDaype，参见 KXTagDaypeKXTVStructTemplateMemberKXTV_WSTRMemberName;KXTV_U KXTV_U KXTV_U323232MemberID;MemberType; MemberDaype;KXTVSTRUCTTEMPLATE_MEMBER,*PKXTVSTRUCTTEMPLATE_MEMBER;2.8.4结构模板属性信息结构模板成员是结构模板中定义必须的，结构模板中有一个或者多个结构模板成员，其属性通过 KXTVStructTemplateMember 定义，包括：TemplateNam，结

47、构模板名称ment，结构模板描述 MemberCount，结构模板成员个数MemberArray，结构模板成员数组，typedef struct KXTVStructTemplatePropertyKXTV_WSTR KXTV_WSTRTemplateName;ment; MemberCount; MemberArray;KXTV_U32PKXTVSTRUCTTEMPLATE_MEMBERKXTVSTRUCTTEMPLATE_PROPERTY,*PKXTVSTRUCTTEMPLATE_PROPERTY;变量数据相关数据结构变量实时数据信息KXTVTagData 结构表示了变量的实时数据值。Fi

48、eldValue，域值TimeStamp，时间戳 QualityStamp，质量戳typedef struct KXTVTagDataKXTV_VALUE FILETIMEFieldValue; TimeStamp; QualityStamp;KXTV_U32KXTVTAG_DATA,*PKXTVTAG_DATA;2.9.2变量域值修改信息该结构用于修改变量的域值的数据值。变量的实时值也是变量域的一种，所以该结构可以用于修改变量的值或者域值。TagID，变量 IDFieldID，域 ID FieldValue，域值 TimeStamp，时间戳QualityStamp，质量戳typedef st

49、ruct KXTVTagSetDataPacketKXTV_U32TagID; FieldID; FieldValue; TimeStamp; QualityStamp;KXTV_16KXTV_VALUE FILETIMEKXTV_U32KXTVTAG_SET_DATAPACKET,*PKXTVTAG_SET_DATAPACKET2.9.3变量值修改信息该结构用于修改变量的数据值。TagID，变量 ID FieldValue，变量值 TimeStamp，时间戳QualityStamp，质量戳typedef struct KXTVTagSetValuePacketKXTV_U32TagID; F

50、ieldValue; TimeStamp; QualityStamp;KXTV_VALUE FILETIMEKXTV_U32KXTVTAG_SET_VALUEPACKET,*PKXTVTAG_SET_VALUEPACKET;2.10 变量2.10.1确认相关数据结构确认变量信息用于对变量或者组的做出确认，分别可以根据名称和 ID 来确认ItemName，变量或 ItemID，变量或AckRemark，确认组名称组 ID的备足信息AlarmType，类型，参见KXTVAlarmType（2.5.7）typedef struct KXTVAlarmAckInfoKXTV_WSTRItemName;

51、 AlarmType; AckRemark;KXTV_U32KXTV_WSTRKXTV_ALARMACKINFO , *PKXTV_ALARMACKINFO;typedef struct KXTVAlarmAckInfobyIDKXTV_U KXTV_U3232ItemID; AlarmType; AckRemark;KXTV_WSTRKXTV_ALARMACKINFOBYID , *PKXTV_ALARMACKINFOBYID;3API 接口函数辅助函数KXTVAPIInitalize初始化接口，用来初始化网络环境和其他资源，在连接运行系统之前必须先调用这个接口。语法：KXTV_RET KX

52、TVAPI KXTVAPIInitalize();返回值：如果成功返回 KXTV_SUC,如果失败返回相应错误码KXTVAPIRelease运行系统资源接口，用来网络环境和其他资源。在使用完毕运行系统之后。调用 KXTVAPIInitalize 成功后，在使用完毕运行系统时，必须调用该接口语法：KXTV_RET KXTVAPI KXTVAPIRelease();返回值：如果成功返回 KXTV_SUC,如果失败返回相应错误码3.1.3KXTVAPITrace环境和资源。启用或者关闭语法：调试功能。启用后，将会有调试信息输出到指定的日志文件中KXTV_VOID KXTVAPI KXTVAPITra

53、ce(KXTV_参数：EnableTrace , KXTV_CWSTR LogFileName );EnableTrace：启用或者关闭调试功能标志。LogFileName：启用调试功能时，调试信息输出的目标文件名（完整路径文件名）。如为空，则在当前目录下创建默认的日志文件。返回值：如果成功返回 KXTV_SUC,如果失败返回相应错误码3.1.4KXTVAPIGetErrorDescription根据错误码，获取错误描述。语法：KXTV_RET KXTVAPI KXTVAPIGetErrorDescription(INKXTV_RETOUT KXTV_WSTRErrorID , ErrorDe

54、scription ,DespLen);OUT KXTV_U参数：ErrorID：错误码。32&ErrorDescription：错误描述信息。 DespLen：错误描述信息的长度。返回值：如果成功返回 KXTV_SUC,如果失败返回相应错误码。说明：ErrorDescription 的内存由函数内部分配，调用者需要调用函数3.1.5KXTVAPIFreeStringArray。字符串数组资源，用来通过API 接口函数分配的字符串数组资源。语法：KXTV_RET KXTVAPI KXTVAPIFreeString(IN_OUT PKXTV_STRINGARRAY StringArray);参数

55、：StringArray：指向待返回值：如果成功返回 KXTV_SUC,如果失败返回相应错误码的字符串数组的指针3.1.6KXTVAPIFreeArray整数数组资源，用来通过 API 接口函数分配的整数数组资源。语法：KXTV_RET KXTVAPI KXTVAPIFreeArray(IN PKXTV_参数：_ARRAYArray);LongArray：指向待返回值：如果成功返回 KXTV_SUC,如果失败返回相应错误码3.1.7KXTVAPIFreeVaribleValue的整数数组的指针可变类型资源，用来语法：通过 API 接口函数分配的可变类型资源。KXTV_RET KXTVAPI K

56、XTVAPIValueFree(IN PKXTV_VALUE Value);参数：Value：指向可变类型资源返回值：如果成功返回 KXTV_SUC,如果失败返回相应错误码KXTVAPIValueInit初始化可变类型数据值。语法：KXTV_RET KXTVAPI KXTVAPIValueInit(IN PKXTV_VALUE Value );参数：DataValue：指向待初始化的可变类型值的指针返回值：如果成功返回 KXTV_SUC，如果失败返回相应错误码KXTVAPIValueCopy将源数据的值语法：给目标数据。KXTV_RET KXTVAPI KXTVAPIValueCopy(PKX

57、TV_VALUE PKXTV_VALUE参数：Value ,SourceValue );Value：目标数据 SourceValue：源数据返回值：如果成功返回 KXTV_SUC，如果失败返回相应错误码3.1.10 KXTVAPIUnicodeStringDuplicate从源字符串中语法：宽字节字符串。KXTV_WSTR KXTVAPI KXTVAPIUnicodeStringDuplicate( KXTV_CWSTR Source );参数：Source：源字符串返回值：后的字符串。得到的字符串在使用完毕以后需要调用 KDBUti果字符串。3.1.11 KXTVAPIUnicodeStri

58、ngFree字符串资源，用来通过 API 接口函数分配的字符串资源。语法：icodeStringFree结KXTV_VOID KXTVAPI KXTVAPIUnicodeStringFree( KXTV_WSTR Source );参数：Source：待返回值：如果成功返回 KXTV_SUC,如果失败返回相应错误码服务器相关函数KXTVServerConnect连接运行系统服务器。必须先连接运行系统才可以对其中的变量，用户信息等做出操作。语法：KXTV_RET KXTVAPI KXTVServerConnect(的字符串的指针IN PKXTV_CONNECTION_OPTIONOUT KXTV

59、_HANDLE*ConnectOption ,ServerHandle);参数：ConnectOption：连接选项，详细内容请参看KXTVAPIServerConnect 结构。ServerHandle：KXTV_HANDLE 结构类型，连接成功后函数返回一个有效服务器句柄，以后行系统的调用都必须使用该句柄返回值：如果成功返回 KXTV_SUC,如果失败返回相应错误码。说明：返回的连接句柄 ServerHandle 需要调用者保存，不能随意修改，在和运行系统服务器的数据对连接中，很多接口函数需要它作为传入参数。3.2.2KXTVServerIsConnected获取和运行系统服务器的连接状态

60、。语法：KXTV_参数：KXTVAPI KXTVServerIsConnected(IN KXTV_HANDLEServerHandle);ServerHandle：运行系统连接句柄。返回值：返回连接状态，若连接已经建立，则返回为真3.2.3KXTVServerDisconnect断开运行系统服务器的连接。和运行系统服务器建立连接成功后，在使用完毕运行系统后，必须调用该接口断开和服务器的连接，同时也要通过这个接口来柄。语法：已经获得的运行系统连接句KXTV_RET KXTVAPI KXTVServerDisconnect(IN KXTV_HANDLE参数：ServerHandle);Serve