SDK用户使用手册

海迅实时数据库 HS-SDK用户手册目录目录. 21.引言.41.1.编写目的 .41.2 适用范围 .42. 接口分类43. 接口详细说明 43.1 数据库服务连接、状态查询接口 43.1.1 数据库服务(HSServer 类) .43.1.2 名字服务集合 (HSNameServers 类) 63.1.3 名字服务对象(HSNameServer 类) 63.2 数据库测点提交、查询接口 .63.2.1 测点集合(HSPoints 类) .63.2.2 测点对象(HSPoint 类) 73.2.3 测点组集合(HSGroups 类) .83.2.4 测点组对象(HSGroup 类) .83.2.5 批量测点集合(HSPointList 类) 93.2.6 数据名称-值集合(HSNameValues 类) 93.2.7 数据名称-值对象 (HSNameValue 类) 93.3 数据提交、查询接口 103.3.1 数据值集合(HSData 类) .103.3.2 测点数据值集合(HSValues 类) 113.3.3 测点数据值对象(HSValue 类) .123.3.4 批量测点数据值集合(HSListData 类) .123.3.5 测点-值集合(HSPointValues 类) 123.3.6 测点-值对象(HSPointValue 类) .133.4 数据库用户、权限管理接口 .133.4.1 用户集合(HSUsers 类) 133.4.2 用户对象(HSUser 类) .133.4.3 角色集合(HSRoles 类) 143.4.4 角色对象(HSRole 类) .143.5 测点模糊查询对话框 .143.5.1 测点模糊查询窗体(HSDlgTestShow 类) .143.6 枚举集接口 .193.6.1 枚举集集合(HSEnumrations 类) 193.6.2 枚举集对象(HSEnumration 类) 191.引言1.1.编写目的将 HS-API 封装成基于 COM 组件的 HS-SDK，以方便对海迅数据库 API 接口二次开发使用。1.2 适用范围适用于海迅数据库百万点系列版本。2. 接口分类1. 数据库服务连接、状态接口。2. 数据库测点提交、查询接口。3. 数据提交、查询接口。4. 数据库用户、权限管理接口。5. 测点模糊查询窗体。6. 枚举集接口。3. 接口详细说明 3.1 数据库服务连接、状态查询接口3.1.1 数据库服务(HSServer 类)该类代表 HighSoon 数据库实例对象，返回数据库对应的实例集合。方法 方法说明 参数列表 返回值IN BSTR user 用户名IN BSTR password 密码IN VARIANT_BOOL fireWall 防火墙Open建立数据库连接IN VARIANT_BOOL cacheEnabled 缓存成功返回0，其它为失败返回错误码IN VARIANT startTime 起始时间IN VARIANT endTime 结束时间IN BSTR expression 计算表达式IN BSTR sampleInterval 取值的时间间隔Calculate根据表达式进行计算OUT IHSValues* pVal 计算结果成功返回0，其它为失败返回错误码ExpressionSum 获取时间段 IN VARIANT startTime 起始时间IN VARIANT endTime 结束时间IN BSTR duration 统计时长IN BSTR expression 计算表达式IN BSTR sampleInterval 取值的时间间隔IN enum SummariesType summariesType 取值类型maries 内的统计值OUT INameValues* pVal NameValues 集合成功返回0，其它为失败返回错误码IN VARIANT startTime 起始时间IN VARIANT endTime 结束时间IN BSTR duration 统计时长IN BSTR expression 计算表达式IN BSTR sampleInterval 取值的时间间隔PercentTrue符合表达式的时间占统计时长的百分比OUT IHSValues* pVal 计算结果成功返回0，其它为失败返回错误码IN VARIANT timestamps 时间点IN BSTR expression 计算表达式TimedCalculate运算表达式对时间戳对应的值进行计算OUT IHSValues* pVal 计算结果成功返回0，其它为失败返回错误码Close 断开数据库 连接 无成功返回0，其它为失败返回错误码属性 属性说明 参数列表 返回值Name 数据库实例对象 OUT BSTR* pVal 实例名 成功返回实例 名FullName 名字服务和实例名称 字符串 OUT BSTR* pVal 名字服务和 实例名 成功返回名字服务和实例名Users 用户集合对象 OUT IHSUsers* pVal 用户集合 成功返回用户 集合对象Roles 角色集合对象 OUT IHSRoles* pVal 角色结合 成功返回角色 集合对象Points 测点集合对象 OUT IHSPoints* pVal 测点集合 成功返回测点 集合对象Groups 测点组集合对象 OUT IHSPointGroups* pVal 点组集合 成功返回组集 合对象Enums 枚举集合对象 OUT IHSEnumrations* pVal 枚举集合 成功返回枚举 集合对象3.1.2 名字服务集合 (HSNameServers 类)该类代表 HighSoon 数据库命名服务集合，默认属性返回 HSNameServer 对象。属性 属性说明 参数列表 返回值IN VARIANT index 索引序号Item 数据库命名服 务集合对象OUT INameServer* pVal 命名服务对象成功返回命名服务对象Count 集合中命名对 象个数 OUT long* pVal 名字服务对象 个数 命名对象个数3.1.3 名字服务对象(HSNameServer 类)该类代表 HighSoon 数据库的 HSServer 对象，包含对应命名服务器中的所有数据库实例，并具有连接、断开命名服务器方法属性 属性说明 参数列表 返回值IN VARIANT index 索引序号Item 数据库命名服务 集合对象OUT IServer* pVal 数据库实例 对象成功返回数据库实例对象Count 集合中数据库实 例个数 OUT long* pVal 数据库实例 对象个数 实例对象个数Name 实例名称 OUT BSTR* pVal 数据库实例 数据库实例名 称3.2 数据库测点提交、查询接口3.2.1 测点集合(HSPoints 类)该类代表 HighSoon 数据库测点对象集合，默认属性返回 HSPoint 对象，并具有添加测点、删除测点、查询测点、重命名测点方法。属性 属性说明 参数列表 返回值IN VARIANT index 索引序号Item 数据库测点集合 对象OUT IHSPoint* pVal 数据库测点 对象成功返回数据库测点对象Count 集合中测点个数 OUT long* pVal 集合中测点 个数 测点对象个数方法 方法说明 参数列表 返回值IN BSTR pointName 测点名称IN enum PointType pointType 测点类型IN INameValues* attrs NameValues 集合Add 添加测点OUT IHSPoint* pPoint 测点对象成功返回0， 其它为失败返回错误码Rename 测点重命名 IN BSTR oldName 测点名称 成功返回0，其它为失IN BSTR newName 测点新名称 败返回错误 码Delete 删除测点 IN BSTR pointName 测点名称成功返回0，其它为失败返回错误码IN BSTR name 测点名称IN BSTR group 组名IN BSTR desc 测点描述IN,OUT UINT* pos 查询当前位置IN enum PointType pointType 测点类型FrurzySearch 测点模糊查 询OUT IPointList* pVal 测点集合成功返回 0，其它为失败返回错误码DeleteByIDList 批量删除数 据库测点 IN VARIANT idArray 起始时间成功返回0，其它为失败返回错误码IN BSTR pointName 测点名称IN INameValues* attrs NameValues 集合IN BSTR enumName 枚举集名称AddEnumPointByName根据枚举集名称添加枚举型测点OUT IHSPoint* pPoint 测点对象成功返回0，其它为失败返回错误码IN BSTR pointName 测点名称IN INameValues* attrs NameValues 集合IN ULONG Index 枚举集 IDAddEnumPointById根据枚举集ID 枚举型测点OUT IHSPoint* pPoint 测点对象成功返回0，其它为失败返回错误码get_PointCount查询实例内的测点总数 OUT ULONG* pVal 测点数目成功返回0，其它为失败返回错误码3.2.2 测点对象(HSPoint 类)该类代表 HighSoon 的测点对象，有一个属性返回 HSData 对象，另有属性返回HSPointAtrriubtes 集合对象。属性 属性说明 参数列表 返回值Data 测点对应数据 OUT IHSData* pVal 测点数据 测点数据ID 测点 ID OUT ULONG* pVal 测点 ID 测点 IDName 测点名称 OUT BSTR* pVal 测点名称 测点名称Descriptor 测点描述信息 OUT BSTR* pVal 测点描述 描述信息PointType 测点类型 OUT enum PointType* pVal 测点类型 测点类型PointGroup 组信息 OUT IHSPointGroup* pVal 测点组信息 组信息3.2.3 测点组集合(HSGroups 类)该类代表 HighSoon 数据库测点组集合，默认属性返回 HSGroup 对象。属性 属性说明 参数列表 返回值IN VARIANT index 索引序号Item 数据库测点组对象OUT IHSPointGroup* pVal 数据库测点 组对象成功返回数据库测点组对象Count 集合中组个数 OUT long* pVal 集合中组个 数 测点组个数方法 方法说明 参数列表 返回值IN BSTR name 组名称IN BSTR descriptor 组描述Add 添加组信息OUT IHSPointGroup* pVal 组对象成功返回0， 其它为失败返回错误码IN VARIANT group 索引序号Remove 删除组信息IN VARIANT_BOOL delPoints 测点信息成功返回 03.2.4 测点组对象(HSGroup 类)该类代表 HighSoon 数据库测点组对象。属性 属性说明 参数列表 返回值ID 测点组 ID OUT LONG* pVal 组 ID 成功返回测点 组 idName 测点组名称 OUT BSTR* pVal 组名称 测点组名称Descriptor 组描述 OUT BSTR* pVal 描述 测点组描述3.2.5 批量测点集合(HSPointList 类)该类代表 HighSoon 数据库批量测点集合。属性 属性说明 参数列表 返回值IN VARIANT index 索引序号Item 数据库测点对象OUT IHSPoint* pVal 数据库测点成功返回数据库测点组对象对象Count 集合中个数 OUT long* pVal 集合中测点 个数 测点个数Data 测点值集合 OUT IListData* pVal 测点数值 测点数值方法 方法说明 参数列表 返回值Add 添加测点对 象 IN IHSPoint* point 测点对象成功返回0， 其它为失败返回错误码3.2.6 数据名称-值集合(HSNameValues 类)该类是通用数据类型集合，代表 HighSoon 数据库名称与值的集合，属性 属性说明 参数列表 返回值IN VARIANT index 索引序号Item 数据库对象集合OUT INameValue* pVal 数据库对象成功返回数据库对象Count 集合中对象个数 OUT long* pVal 集合中组个 数 测点组个数方法 方法说明 参数列表 返回值IN BSTR Key 索引序号IN VARIANT Value 对象值Add 添加对象信 息OUT INameValue* pVal 对象名称成功返回 0Remove 删除对象 IN in BSTR Key 索引序号 成功返回 03.2.7 数据名称-值对象 (HSNameValue 类)该类代表 HighSoon 数据库名称与值的对象。属性 属性说明 参数列表 返回值Name 获取对象名称 OUT BSTR* pVal 对象名称 成功返回对象 名称Value 获取对象值 OUT long* pVal 对象值 测点组个数Value 对象值更新 IN VARIANT newVal 对象新值 成功返回 03.3 数据提交、查询接口用于测点实时、历史数据的交互，包含各种数据查询、数据提交、数据删除方法。3.3.1 数据值集合(HSData 类)属性 属性说明 参数列表 返回值Snapshot 数据库最新值 OUT IHSValue* pVal 测点数据对 象 成功返回数据库测点最新值方法 方法说明 参数列表 返回值IN VARIANT startTime 起始时间IN VARIANT endTime 结束时间RecordedValues根据测点名称查询测点时间段内的历史数据 OUT IHSValues* pVal 历时数据成功返回0， 其它为失败返回错误码IN VARIANT startTime 起始时间IN VARIANT endTime 结束时间IN VARIANT interval 插值步长InterpolatedValues根据测点 ID 查询时间内的插值历史数据OUT IHSValues* pVal 历时数据成功返回 0，其它为失败返回错误码IN VARIANT startTime 起始时间IN VARIANT endTime 结束时间IN LONG nInterval 时间间隔PlotValues根据测点 ID 查询指定间隔时段的最大最小统计值 OUT IHSValues* pVal 查询数据返回成功返回0，其它为失败返回错误码IN VARIANT startTime 起始时间IN VARIANT endTime 结束时间IN enum SummariesType 统计类型Summary测根据测点 ID查询测点一段时间内的统计信息 OUT IHSValues* pVal 查询数据返回成功返回 0，其它为失败返回错误码IN VARIANT startTime 起始时间IN VARIANT endTime 结束时间IN enum SummariesType 查询类型IN VARIANT duration 时间间隔Summaries根据测点 ID 查询间隔时间段内的统计值OUT IHSValues* pVal 查询数据返回成功返回0，其它为失败返回错误码IN VARIANT timestamp 测点时间IN VARIANT value 断面数据值UpdateValue单点单数据断面提交IN LONG state 测点状态码成功返回0，其它为失败返回错误码UpdateValues 多点单数据断 面提交 IN IHSValues* values 数据值集合成功返回0，其它为失败返回错误码3.3.2 测点数据值集合(HSValues 类)属性 属性说明 参数列表 返回值Item 数据库测点值对象 IN VARIANT index 索引序号 成功返回数据库测点值OUT IHSValue* pVal 测点数据值 对象Count 集合中数据个数 OUT long* pVal 测点数据个数 数据个数Attributes 名称数据对象 OUT INameValues* pVal 数据对象 数据对象方法 方法说明 参数列表 返回值IN VARIANT timestamp 数据时标IN VARIANT value 数据值Add向集合中添加数据IN LONG state 数据状态码成功返回0， 其它为失败返回错误码Insert向数据集合中插入数据对象IN IHSValue* value 数据对象 成功返回 0IN VARIANT index 索引序号OUT IHSValue* pVal 数据值对象IN INameValues* attrs NameValues 集合IN BSTR enumName 枚举集名称OUT IHSPoint* pPoint 测点对象Get 获取数据值 对象OUT IHSPoint* pPoint 测点对象成功返回 0 3.3.3 测点数据值对象(HSValue 类)属性 属性说明 参数列表 返回值Timestamp 数据时标 OUT IHSTime* pVal 数据时标 时标Value 数据值 OUT VARIANT* pVal 数据值 Value 值State 数据状态码 OUT LONG* pVal 数据状态码 状态码Attributes 名称数据对象 OUT INameValues* pVal 数据对象 数据对象3.3.4 批量测点数据值集合(HSListData 类)该类是批量测点数据集合类，与 HSPointList 类相对应。属性 属性说明 参数列表 返回值Snapshot 批量测点最新值 OUT IPointValues* 测点值 测点值集合pVal方法 方法说明 参数列表 返回值IN VARIANT timestam 时间点IN enum RetrievalType mode 断面类型ArcValue获取测点断面数据OUT IPointValues* pVal 测点值成功返回0， 其它为失败返回错误码UpdateValues 批量断面测 写值 IN INameValues* nameAndValues 数据对象成功返回 0其它为失败返回错误码3.3.5 测点-值集合(HSPointValues 类)该类代表 HighSoon 数据库测点- 值集合，其中测点与值一一对应。属性 属性说明 参数列表 返回值IN VARIANT index 索引序号Item 数据库测点值对象OUT IPointValue* pVal 数据库测点值对象成功返回数据库测点值对象Count 集合中值个数 OUT long* pVal 集合中值个数 测点值个数3.3.6 测点-值对象(HSPointValue 类)该类代表 HighSoon 数据库测点- 值对象。属性 属性说明 参数列表 返回值Point 测点对象 OUT IHSPoint* pVal 数据库测点 对象 测点对象信息Value 集合中值对象 OUT IHSValue* pVal 数据库测点 值对象 测点值信息3.4 数据库用户、权限管理接口用于数据库访问权限控制，包括用户添加、权限分配等。3.4.1 用户集合(HSUsers 类)属性 属性说明 参数列表 返回值IN VARIANT index 索引序号Item 数据库用户集合OUT IHSUser* pVal 用户对象成功返回用户对象Count 用户对象个数 OUT long* pVal 个数 用户个数方法 方法说明 参数列表 返回值IN BSTR name 用户名称IN BSTR pwd 密码IN BSTR role 角色Add 添加用户信息OUT IHSUser* pVal 用户对象成功返回0， 其它为失败返回错误码Delete 删除用户信息 IN BSTR name 用户名称成功返回 0其它为失败返回错误码3.4.2 用户对象(HSUser 类)属性 属性说明 参数列表 返回值IN BSTR newRole 角色新名称Action 更新用户信息IN BSTR newPassWord 用户新密码成功返回用户对象Name 获取用户名称 OUT BSTR* pVal 用户名称 成功返回用户 名称3.4.3 角色集合(HSRoles 类)属性 属性说明 参数列表 返回值IN VARIANT index 索引序号Item 数据库角色集合OUT IHSRole* pVal 角色对象成功返回角色对象Count 角色对象个数 OUT long* pVal 个数 角色个数方法 方法说明 参数列表 返回值IN BSTR name 角色名称IN LONG action 角色权限Add 添加角色信息OUT IHSRole* pVal 角色对象成功返回0， 其它为失败返回错误码Delete 删除角色信息 IN BSTR roleName 角色名称成功返回 0其它为失败返回错误码3.4.4 角色对象(HSRole 类)属性 属性说明 参数列表 返回值Action 更新角色信息 IN LONG newVal 角色新权限 成功返回 0Action 获取角色更新 OUT LONG* pVal 角色权限 成功返回角色 权限Name 获取角色名称 OUT BSTR* pVal 用户名称 成功返回角色 名称3.5 测点模糊查询对话框用于测点的模糊查询、搜索等功能。3.5.1 测点模糊查询窗体(HSDlgTestShow 类)属性 属性说明 参数列表 返回值IN INameValues* Attrs 数据-值对象结合Show 测点模糊查询窗体展示OUT IPointList* pVal 批量测点集合成功返回 0模糊查询初始界面如下图所示：其中，HS 命名服务器列表是通过读取“C:Windows”路径下的文件 “HSSDK.ini”获取，数据库实例项跟随命名服务的变化动态响应，其下拉列表内容为命名服务器中所包含的数据库实例。测点类型、测点名、测点组、测点描述是搜索条件，可根据需要进行相应设置，默认为空。窗体下半部分为测点属性查询结果，其中显示，服务器、测点名称、测点描述三列内容。左侧为搜索工具栏，包括模糊搜索、测点属性、测点最新值、重置、全选、确定和取消。下面分别说明各主要按钮的功能：一是模