C++ > 2.4接口升级说明

接口2.4升级到3.0，由于2.4是单机版、3.0是分布式版本，接口做了合并和修改,新的接口动态库名称为hdKingAPI。

1.统一的改动.

接口名称：为了尽量保持兼容性，新版本的接口名与旧版本的接口名基本保持一致，通过前缀插入’3’来表明是3.0版本的接口，例如连接从nt_connect改为nt3_connect，加点从pt_add_tag改为pt3_add_tag。

参数：参数前面都有一个宏来表明是输入参数还是输出参数，hd3_in表示输入，hd3_out表示输出。例如加点的接口

int32 pt3_add_tag(

hd3_in const HD3PtTagProp* pTagProp,

hd3_in const HD3Mask* pMask,

hd3_in const char* szDataNodeName，

hd3_out uint32* pnTagID

);

前3个参数表示输入，后1个参数表示输出，一目了然。这两个宏只起标示的作用，对于编译和运行没有任何影响。

2.连接和断开

老接口：int32 nt_connect(const char* szIP, uint16 nPort, HDHANDLE* pSrvHandle, int32 nTimeOutSec);

int32 nt_disconnect(HDHANDLE hServer);

新接口：int32 nt3_connect(hd3_in const HD3Connection* pInfo);

typedef struct {

char szAddress[HD3_LEN_ADDRESS * HD3_BASE];

uint16 nPort;

char szBakAddress[HD3_LEN_ADDRESS * HD3_BASE];

uint16 nBakPort;

int32 nTimeout;

}HD3Connection;

int32 nt3_disconnect();

说明：接口参数从分散的ip，端口，超时改为结构体，新增备机ip和备机端口，如果没有备机，备机信息不用填写。ip 和端口是3.0版本的配置中心所在的机器地址，默认端口号为5673。

老版本的接口返回连接句柄，其它的接口需要使用这个句柄，新版本中已经不需要了。

新版本的连接已经自动实现了重连的功能，调用者不用再编写保持重连的代码。

3. 点的配置

点的类型分为系统点，普通点，报警点，SPC报警点，统计点，计算点。其中系统点是ihd自动创建，其它类型的点提供接口增删查改。

4.1 新增点

老接口：int32 pt_add_tag(HDHANDLE hServer, const TagProp* pTagProp, int64 nPropMask);

新接口：int32 pt3_add_tag(

hd3_in const HD3PtTagProp* pTagProp,

hd3_in const HD3Mask* pMask,

hd3_in const char* szDataNodeName，

hd3_out uint32* pnTagID

);

点的结构体从TagProp 变为HD3PtTagProp，结构体的内容名称不变。

// Tag点掩码

typedef struct {

int64 nCommMask; // 公共属性的掩码

int64 nExtMask;

}HD3Mask;

掩码从int64的掩码修改为包含2个int64的掩码结构体。新的掩码包括点的基础掩码和点的扩展掩码，分别对应于点的基础属性和扩展属性，所有的掩码都定义在hd3MaskDefine.h中。

1）全属性掩码为 HD3M_ALL，表明调用者需要所有的属性

2）基本属性掩码 HD3M_COMM_PROP_XXX普通点，报警点，计算点，统计点的基本属性都用这些掩码

例如：名字掩码 HD3M_COMM_PROP_TAG_NAME

类型掩码HD3M_COMM_PROP_TAG_TYPE

3）普通点的扩展掩码 HD3M_PT_EXT_PROP_XXX, 普通点扩展属性只跟底层的数据采集相关，如采集器名称，设备名称，地址等。不使用iHD的OPC采集器，modbus采集器的用户不需要关系这些属性，扩展掩码赋值为0即可。

例如：采集器名 HD3M_PT_EXT_PROP_COLLECTOR_NAME

设备名 HD3M_PT_EXT_PROP_DEVICE_NAME

4)报警点的扩展掩码 HD3M_AM_EXT_PROP_XXX，报警点的扩展属性只与报警的产生确认恢复相关，如报警条件，报警源点，报警死区等。

例如：报警条件1 HD3M_AM_EXT_PROP_TEST1

报警源点：HD3M_AM_EXT_PROP_SOURCE_TAG

5)统计点的扩展掩码 HD3M_ST_EXT_PROP_XXX，统计点的扩展属性只与统计相关，如统计类型，统计取值方式，统计开始时间等。

例如：统计类型 HD3M_ST_EXT_PROP_STATS_TYPE

统计开始时间：HD3M_ST_EXT_PROP_SAMPLE_START_DATE

6)计算点的扩展掩码 HD3M_CA_EXT_PROP_XXX，计算点的扩展属性只与计算属性相关，如计算表达式，计算周期等。

例如：计算表达式 HD3M_CA_EXT_PROP_CALC_EXPR

计算周期：HD3M_CA_EXT_PROP_CALC_PERIOD

4.2 删除点

普通点，统计点，计算点，报警点的删除点的接口都合并为一个tag3_delete_tag

4.3 条件查询点

4.3.1 条件查询点的个数

普通点，统计点，计算点，报警点的条件查询点的个数的接口全部合并为一个

int32 tag3_query_tag_num_cond(

hd3_in enum HD3_TAG_CLASS nTagClass,

hd3_in const HD3FilterItemSet* pSet,

hd3_out int32* pnTagNum

);

条件查询参数

// 查询过滤项数组

typedef struct {

int32 nSize;

HD3FilterItem* pItem; // array

}HD3FilterItemSet;

typedef struct {

int32 nItemID;

enum HD3_RELATION nRelation;

char szValue[HD3_LEN_QUERY_ITEM_VALUE * HD3_BASE];

}HD3FilterItem;

属性项ID定义在hd3Enum.h中HD3_TAG_COL_XXX

例如Tag名称 HD3_TAG_COL_COMM_PROP_TAG_NAME

4.4 根据名称查询ID

普通点，统计点，计算点，报警点的条件查询点的个数的接口全部合并为一个

int32 tag3_query_id_by_name(

hd3_in const char* szName,

hd3_out uint32* pnTagID

);

5.新旧接口对照表

2.4版本接口	3.0版本接口	说明
ut_set_mode	已去除	buffer接口使用独立API
ut_set_timeout	ut3_set_request_timeout
ut_get_item_step	ut3_get_item_step
ut_free_iterator	ut3_free_handle
nt_connect	nt3_connect
nt_disconnect	nt3_disconnect
nt_test_connection	已去除	KingAPI自动重连，调用者不需要自己测试判断和重连了
nt_get_server_current_time	ut3_get_server_ms_time
ut_get_license_info	ut3_get_license_info
ut_get_license_info_all	ut3_get_license_info_all
pt_register_tag_change_info	已去除
pt_query_tagid	tag3_query_id_by_name
pt_query_tagids	tag3_query_ids_by_names
pt_query_tag_type	pt3_query_tag_type
pt_query_tag_prop	pt3_query_tag_prop
pt_add_tag	pt3_add_tag
pt_add_tags	pt3_add_tags
pt_delete_tag	tag3_delete_tag, tag3_delete_tags
pt_get_collector_timestamp	pt3_get_collector_version
pt_get_collector_change_his	pt3_get_collector_alter_report
pt_delete_change_his	已去除
pt_query_tag_num_cond	tag3_query_tag_num_cond
pt_query_tags_cond	pt3_query_tags_cond
pt_query_specify_page_tags_cond	pt3_query_specify_page_tags_cond
pt_modify_tag_prop	pt3_modify_tag_prop, pt3_modify_tags_prop
pt_reg_monitored_tag	pt3_reg_monitored_tag
pt_add_digitalset	pt3_add_digitalset
pt_delete_digitalset	pt3_delete_digitalset
pt_modify_digitalset	pt3_modify_digitalset
pt_query_digitalset_state_infos	pt3_query_digitalset_all_state_infos
pt_query_digitalset_state_name	pt3_query_digitalset_state_name
pt_query_digitalset_names	pt3_query_digitalset_names
pt_is_sys_tag_name	已去除
sn_save_snapshot	sn3save_snapshot
sn_save_snapshots	sn3_save_snapshots
sn_save_disorder_snapshots	sn3_save_disorder_snapshots
sn_save_tags_disorder_snapshots	sn3_save_tags_disorder_snapshots
sn_query_snapshot	sn3_query_snapshot
sn_query_snapshots	sn3_query_snapshots
ar_query_interp_record	已去除	功能包含在ar3_query_interp_record_by_mode
ar_query_raw_records	ar3_query_raw_records
ar_query_interp_records	已去除	功能包含在ar3_query_interp_records_by_mode
ar_query_interp_record_by_mode	ar3_query_interp_record_by_mode
ar_query_interp_records_by_mode	ar3_query_interp_records_by_mode
ar_query_tags_interp_records_by_mode	ar3_query_tags_interp_records_by_mode
ar_delete_record	ar3_delete_record
ar_modify_record	ar3_modify_record
ar_query_specify_num_raw_recs	ar3_query_specify_num_raw_recs
ar_query_raw_records_number	ar3_query_raw_records_number
am_register_alarm_record_info	am3_register_alarm_record_info
am_unregister_alarm_record_info	am3_unregister_alarm_record_info
am_add_tag	am3_add_tag
am_query_tagid	tag3_query_id_by_name
am_delete_tag	tag3_delete_tag, tag3_delete_tags
am_modify_tag_prop	am3_modify_tag_prop
am_query_tag_prop	am3_query_tag_prop
am_query_tag_names	tag3_query_tags_common_prop
am_query_tag_num_cond	tag3_query_tag_num_cond
am_query_tags_cond	am3_query_tags_cond
am_query_specify_page_tags_cond	am3_query_specify_page_tags_cond
am_add_group	am3_add_group
am_query_groupid	am3_query_groupid
am_delete_group	am3_delete_group
am_modify_group_name	am3_modify_group
am_modify_group_desc	am3_modify_group
am_modify_group_parentid	am3_modify_group
am_query_group_props	am3_query_group_props
am_query_group_child_tags	am3_query_group_child_tags
am_query_group_child_groups	am3_query_group_child_groups
am_query_snapshots	am3_query_snapshots
am_query_tag_records	am3_query_tag_records
am_query_tags_all_records	am3_query_tags_all_records
am_query_group_records	am3_query_group_records
am_acknowledge_alarms	am3_acknowledge_alarms
am_comment_alarms	am3_comment_alarms
sc_login	sc3_login
sc_modify_password	sc3_modify_password
sc_reset_password	sc3_reset_password
sc_add_user	sc3_add_user
sc_delete_user	sc3_delete_user
sc_add_group	sc3_add_group
sc_delete_group	sc3_delete_group
sc_add_user_to_group	sc3_add_user_to_group
sc_delete_user_from_group	sc3_delete_user_from_group
sc_modify_user_desc	sc3_modify_user_desc
sc_modify_group_desc	sc3_modify_group_desc
sc_query_all_users	sc3_query_all_users
sc_query_members_of_group	sc3_query_members_of_group
sc_query_all_groups	sc3_query_all_groups
sc_query_groups_of_user	sc3_query_groups_of_user
sc_query_manage_security	sc3_query_manage_security
sc_modify_manage_security	sc3_modify_manage_security
sc_query_all_trusts	sc3_query_all_trusts
sc_add_trust	sc3_add_trust
sc_delete_trust	sc3_delete_trust
sc_query_current_user_name	sc3_query_current_user_name
sc_add_auth_item	sc3_add_auth_item
sc_delete_auth_item	sc3_delete_auth_item
sc_modify_auth_item	sc3_modify_auth_item
sc_add_auth_item_to_group	sc3_add_auth_item_to_group
sc_delete_auth_item_from_group	sc3_delete_auth_item_from_group
sc_query_all_auth_items	sc3_query_all_auth_items
sc_query_auth_items_of_group	sc3_query_auth_items_of_group
sc_query_groups_of_auth_item	sc3_query_groups_of_auth_item
sc_query_auth_of_user	sc3_query_auth_of_user
ct_add_collector	ct3_add_collector
ct_delete_collector	ct3_delete_collector
ct_query_all_collectors	ct3_query_all_collectors
ct_query_collector	ct3_query_collector
ct_query_collector_id_by_name	ct3_query_collector_id_by_name
ct_modify_collector	ct3_modify_collector
ct_add_device	ct3_add_device
ct_delete_device	ct3_delete_device
ct_query_device	ct3_query_device
ct_query_device_id_by_name	ct3_query_device_id_by_name
ct_query_devices_of_collector	ct3_query_devices_of_collector
ct_modify_device	ct3_modify_device
ct_add_scan_group	ct3_add_scan_group
ct_delete_scan_group	ct3_delete_scan_group
ct_query_scan_group	ct3_query_scan_group
ct_query_scan_group_id_by_name	ct3_query_scan_group_id_by_name
ct_query_scan_groups_of_device	ct3_query_scan_groups_of_device
ct_modify_scan_group	ct3_modify_scan_group
ct_register_collector_change_info	已去除
ct_update_collector_status	ct3_update_collector_status
ct_update_device_status	ct3_update_device_status
ct_query_collector_status	ct3_query_collectors_status
ct_query_device_status	ct3_query_devices_status
ct_query_collector_status_rec	已去除
ct_query_device_status_rec	已去除
ct_query_update_status_inter	ct3_get_status_update_interval
st_add_tag_v2	st3_add_tag
st_query_tagid	tag3_query_id_by_name
st_delete_tag	tag3_delete_tag, tag3_delete_tags
st_modify_tag_prop_v2	st3_modify_tag_prop
st_query_tag_prop_v2	st3_query_tag_prop
st_query_tag_num_cond_v2	tag3_query_tag_num_cond
st_query_tags_cond_v2	st_query_tags_cond
st_query_specify_page_tags_cond_v2	st_query_specify_page_tags_cond
st_tag_max	st3_tag_stats_calc
st_tag_min	st3_tag_stats_calc
st_tag_sum	st3_tag_stats_calc
st_tag_mean	st3_tag_stats_calc
st_tag_integral	st3_tag_stats_calc
st_tag_good_percent	st3_tag_stats_calc
st_tag_stats_calc	st3_tag_stats_calc
ca_add_tag	ca3_add_tag
ca_query_tagid	tag3_query_id_by_name
ca_query_tag_name	tag3_query_tags_common_prop
ca_delete_tag	tag3_delete_tag, tag3_delete_tags
ca_modify_tag_prop	ca3_modify_tag_prop
ca_query_tag_prop	ca3_query_tag_prop
ca_query_tag_num_cond	tag3_query_tag_num_cond
ca_query_tags_cond	ca3_query_tags_cond
ca_query_specify_page_tags_cond	ca3_query_specify_page_tags_cond
cs_register_cfg_chg_callback	已去除
spc_add_tag	spc3_add_tag
spc_delete_tag	tag3_delete_tag, tag3_delete_tags
spc_modify_tag_prop	spc3_modify_tag_prop
spc_query_tag_names	tag3_query_tags_common_prop
spc_query_tag_prop	spc3_query_tag_prop
spc_query_tagid	tag3_query_id_by_name
spc_query_tag_num_cond	spc3_query_tag_num_cond
spc_query_tags_cond	spc3_query_tags_cond
spc_query_specify_page_tags_cond	spc3_query_specify_page_tags_cond
spc_query_group_child_tags	spc3_query_group_child_tags
spc_acknowledge_alarms	spc3_acknowledge_alarms
spc_query_snapshots	spc3_query_snapshots
spc_register_alarm_record_info	spc3_register_alarm_record_info
spc_unregister_alarm_record_info	spc3_unregister_alarm_record_info
spc_query_tag_records	spc3_query_tag_records
spc_query_tags_records	spc3_query_tags_all_records
spc_query_group_records	spc3_query_group_records
spc_comment_alarms	spc3_comment_alarms
tag_query_tags_baisc_info_by_name	tag3_query_tags_baisc_info_by_name
tag_query_tags_cond	tag3_query_tags_cond
tag_query_tags_basic_prop	tag3_query_tags_common_prop
tag_opc_release_tag	已去除
tag_opc_release_tags	已去除
tag_opc_unrelease_tag	已去除
tag_opc_unrelease_tags	已去除
tag_opc_query_tag_state	已去除
tag_opc_query_tags_state	已去除
tag_opc_set_tags_state	已去除
tag_opc_query_all_release_tags	已去除
tag_query_tag_number	tag3_query_tag_num_cond
ut_query_netmgr_connect_client_num	已去除
ut_set_charset	ut3_set_charset
ut_get_charset	ut3_get_charset
nt_get_all_client_num	ut3_get_all_client_num
nt_get_all_client_info	ut3_get_all_client_info
nt_get_socket_net_info	ut3_get_socket_net_info
nt_get_client_sockets	ut3_get_client_sockets