客户端API » VB.Net 语言接口定义

方法摘要
void Login(ByVal url As String, ByVal sn As String, ByVal mode As LoginMode)
授权登录。初始化运行环境,获取操作句柄。必须在除升级函数之外的其它操作前执行。根据登录模式的不同可能需要连接授权服务器。
void LoginEx(ByVal url As String, ByVal sn As String, ByVal featureId As UInteger, ByVal xmlScope As String, ByVal mode As LoginMode)
授权登录的增强版本。允许应用程序在登录时指定授权中所需包含的特征项,以缩小登录范围。
void Logout()
此函数用于释放上下文句柄,退出登录状态。
UInteger ReadFeature(ByVal featureId As UInteger)
此函数用于读取特征项的数据内容,可用于“只读”和“读写”特征类型。
void WriteFeature(ByVal featureId As UInteger, ByVal featureValue As UInteger)
此函数用于更新“读写”类型的特征项的数据内容。
UInteger ConvertFeature(ByVal featureId As UInteger, ByVal para1 As UInteger, ByVal para2 As UInteger, ByVal para3 As UInteger, ByVal para4 As UInteger)
此函数用于使用“算法”类型的特征项对输入参数进行变换操作,得到唯一对应的4字节结果。
Byte() EncryptFeature(ByVal featureId As UInteger, ByVal plainBuffer() As Byte)
此函数用于使用“密钥”类型的特征项对输入的明文进行加密,返回密文结果。
Byte() DecryptFeature(ByVal featureId As UInteger, ByVal cipherBuffer() As Byte)
此函数用于使用“密钥”类型的特征项对输入的密文进行解密,返回明文结果。
UInteger QueryFeature(ByVal featureId As UInteger)
请求特征项,检查特征项是否存在并可用。可用于任意特征项类型。对于集团授权,函数执行成功后会占用一个模块用户数。
UInteger ReleaseFeature(ByVal featureId As UInteger)
释放特征项。集团授权会释放模块用户数。
void SetDataItem(ByVal dataItemName As String, ByVal dataItemValue() As Byte)
创建或更新配置项。如果相同名称的配置项存在,则会更新其中的数据;否则将添加新的授权码配置项。
void RemoveDataItem(ByVal dataItemName As String)
删除指定的配置项。该操作无法删除通过控制台设置的产品配置项或模版配置项。
Byte() GetDataItem(ByVal dataItemName As String)
读取指定的配置项数据。
UInteger GetDataItemNum()
此函数用于获取可访问配置项的数量,一般用于配置项的枚举操作。
String GetDataItemName(ByVal index As UInteger)
根据配置项索引获取其名称,一般用于配置项的枚举操作。
String GetSessionInfo(ByVal type As SessionType)
获取当前会话信息,以字符串形式返回。根据获取的内容不同,返回结果可能是XML格式或非XML格式。 返回数据中的日期项已根据客户端的本地时区进行调整。如果Login时未指定SN,返回串为当前系统所有可用SN的综合结果。
String GetRequestInfo(ByVal sn As String, ByVal type As BindingType)
获取当前运行环境的升级请求码,用于发起本地授权激活及升级请求。
String GetUpdateInfo(ByVal url As String, ByVal sn As String, ByVal requestInfo As String)
使用请求码与授权服务器进行连接,获取升级码。本函数需要进行网络连接。
String ApplyUpdateInfo(ByVal updateInfo As String)
应用升级码完成本地授权激活或升级。本函数必须在获取请求码的同一环境下执行。
void UpdateOnline(ByVal url As String, ByVal sn As String)
此函数用于与授权服务器在线连接,自动完成本地授权的升级操作。本函数需要进行网络连接。
String Revoke(ByVal sn As String)
获取用于迁出浮动授权码的请求码,以实现离线迁出操作。执行本函数后该授权码将不可用。
void RevokeOnline(ByVal url As String, ByVal sn As String)
从客户端迁出已激活的浮动授权码。授权码迁出后,可以用于其它的客户端。本函数需要进行网络连接。
void CheckOutSn(ByVal url As String, ByVal featureId As UInteger)
从集团授权服务器借出一个完整的授权码,以允许客户端脱离集团服务器单独使用。被借出的集团授权码必须具有可借出属性,并在客户端成功借出后减少一个可用用户数。被借出的用户数在到期后将自动返还给集团服务器。
void CheckOutFeatures(ByVal url As String)
从集团授权服务器借出一组特征项,这些特征项必须包含在同一个授权码中。被借出的集团授权码必须具有可借出属性,并在客户端成功借出后减少一个可用用户数。被借出的用户数在到期后将自动返还给集团服务器。
void CheckIn(ByVal url As String, ByVal featureId As UInteger)
提前返还从集团授权服务器借出的授权。要提前返还授权,该授权码必须具有允许提前返还属性。
String GetInfo(ByVal sn As String, ByVal type As InfoType)
获取授权信息及使用环境信息,数据以XML格式返回。调用此函数前客户端不需要执行登录操作。
void RemoveSn(ByVal sn As String)
删除指定授权码在本机的授权数据,可用于测试或当授权数据出现问题而不能通过升级解决时的故障处理。
UInteger GetVersion()
获取客户端安全库版本号。
方法详细信息

Login

    public Sub Login (
                 ByVal url As String,
                 ByVal sn As String,
                 ByVal mode As LoginMode)
授权登录。初始化运行环境,获取操作句柄。必须在除升级函数之外的其它操作前执行。根据登录模式的不同可能需要连接授权服务器。

参数:
url - [IN] 自定义授权服务器地址,包括端口。如未使用自定义授权服务器则为NULL。
sn - [IN] 授权码(SN)字符串。如果为空(空串或NULL)则尝试寻找所有当前本机可用的SN
mode - [IN] 登录模式。 包含以下类型:
Local // 登录本地授权,不会尝试寻找集团或云授权服务器。如果本地授权失效也不会尝试自动升级
Remote // 登录远程授权服务器,尝试建立云授权或集团授权连接,服务器地址由URL参数或配置文件提供
Auto // 同时尝试本地授权及远程授权,寻找任何可用的授权方式。可能自动升级失效的本地授权

返回:

LoginEx

    public Sub LoginEx (
                 ByVal url As String,
                 ByVal sn As String,
                 ByVal featureId As UInteger,
                 ByVal xmlScope As String,
                 ByVal mode As LoginMode)
授权登录的增强版本。允许应用程序在登录时指定授权中所需包含的特征项,以缩小登录范围。

参数:
url - [IN] 自定义授权服务器地址,包括端口。如未使用自定义授权服务器则为NULL。
sn - [IN] 授权码(SN)字符串。如果为空(空串或NULL)则尝试寻找所有当前本机可用的SN
featureId - [IN] 登录授权所需要包含的特征项ID
xmlScope - [IN] 登录范围。用于提供更多的登录条件,格式为标准XML字符串。目前保留,必须为NULL
mode - [IN] 登录模式。 包含以下类型:
Local // 登录本地授权,不会尝试寻找集团或云授权服务器。如果本地授权失效也不会尝试自动升级
Remote // 登录远程授权服务器,尝试建立云授权或集团授权连接,服务器地址由URL参数或配置文件提供
Auto // 同时尝试本地授权及远程授权,寻找任何可用的授权方式。可能自动升级失效的本地授权

返回:

Logout

    public Sub Logout ()
此函数用于释放上下文句柄,退出登录状态。

参数:

返回:

ReadFeature

    public Function ReadFeature (
                 ByVal featureId As UInteger) As UInteger
此函数用于读取特征项的数据内容,可用于“只读”和“读写”特征类型。

参数:
featureId - [IN] 产品的特征项ID。

返回:
特征项数据缓存区地址,用于存储读出的数据。

WriteFeature

    public Sub WriteFeature (
                 ByVal featureId As UInteger,
                 ByVal featureValue As UInteger)
此函数用于更新“读写”类型的特征项的数据内容。

参数:
featureId - [IN] 产品的特征项ID。
featureValue - [IN] 特征项数据值。

返回:

ConvertFeature

    public Function ConvertFeature (
                 ByVal featureId As UInteger,
                 ByVal para1 As UInteger,
                 ByVal para2 As UInteger,
                 ByVal para3 As UInteger,
                 ByVal para4 As UInteger) As UInteger
此函数用于使用“算法”类型的特征项对输入参数进行变换操作,得到唯一对应的4字节结果。

参数:
featureId - [IN] 产品的特征项ID。
para1 - [IN] 变换输入因子1
para2 - [IN] 变换输入因子2
para3 - [IN] 变换输入因子3
para4 - [IN] 变换输入因子4

返回:
变换结果。

EncryptFeature

    public Function EncryptFeature (
                 ByVal featureId As UInteger,
                 ByVal plainBuffer() As Byte) As Byte()
此函数用于使用“密钥”类型的特征项对输入的明文进行加密,返回密文结果。

参数:
featureId - [IN] 产品的特征项ID。
plainBuffer - [IN] 数据缓存区地址,用于存储明文数据。

返回:
数据缓存区地址,用于存储密文数据。

DecryptFeature

    public Function DecryptFeature (
                 ByVal featureId As UInteger,
                 ByVal cipherBuffer() As Byte) As Byte()
此函数用于使用“密钥”类型的特征项对输入的密文进行解密,返回明文结果。

参数:
featureId - [IN] 产品的特征项ID。
cipherBuffer - [IN] 数据缓存区地址,用于存储密文数据。

返回:
数据缓存区地址,用于存储明文数据。

QueryFeature

    public Function QueryFeature (
                 ByVal featureId As UInteger) As UInteger
请求特征项,检查特征项是否存在并可用。可用于任意特征项类型。对于集团授权,函数执行成功后会占用一个模块用户数。

参数:
featureId - [IN] 产品的特征项ID。

返回:
当不为NULL时,获取特征项当前可用用户数。

ReleaseFeature

    public Function ReleaseFeature (
                 ByVal featureId As UInteger) As UInteger
释放特征项。集团授权会释放模块用户数。

参数:
featureId - [IN] 产品的特征项ID。

返回:
当不为NULL时,获取特征项当前可用用户数。

SetDataItem

    public Sub SetDataItem (
                 ByVal dataItemName As String,
                 ByVal dataItemValue() As Byte)
创建或更新配置项。如果相同名称的配置项存在,则会更新其中的数据;否则将添加新的授权码配置项。

参数:
dataItemName - [IN] 数据项名称,名称最大长度为128字节。
dataItemValue - [IN] 数据项数据缓存区地址,数据最大长度为1024字节。

返回:

RemoveDataItem

    public Sub RemoveDataItem (
                 ByVal dataItemName As String)
删除指定的配置项。该操作无法删除通过控制台设置的产品配置项或模版配置项。

参数:
dataItemName - [IN] 数据项名称,名称最大长度为128字节。

返回:

GetDataItem

    public Function GetDataItem (
                 ByVal dataItemName As String) As Byte()
读取指定的配置项数据。

参数:
dataItemName - [IN] 数据项名称,名称最大长度为128字节。

返回:
数据项数据缓存区地址,数据最大长度为1024字节。

GetDataItemNum

    public Function GetDataItemNum () As UInteger
此函数用于获取可访问配置项的数量,一般用于配置项的枚举操作。

参数:

返回:
可访问的数据项总数,包括了所有可以访问到的产品、模版及授权码的数据项。

GetDataItemName

    public Function GetDataItemName (
                 ByVal index As UInteger) As String
根据配置项索引获取其名称,一般用于配置项的枚举操作。

参数:
index - [IN] 数据项索引。

返回:
用于存储数据项名称的存储区地址。

GetSessionInfo

    public Function GetSessionInfo (
                 ByVal type As SessionType) As String
获取当前会话信息,以字符串形式返回。根据获取的内容不同,返回结果可能是XML格式或非XML格式。 返回数据中的日期项已根据客户端的本地时区进行调整。如果Login时未指定SN,返回串为当前系统所有可用SN的综合结果。

参数:
type - [IN] 获取会话信息类型。 包含以下类型:
XML_TYPE_SN_INFO // 获取当前会话中授权码的授权信息,以XML结构表示。未作限制的授权项将不会返回
XML_TYPE_FEATURE_INFO // 获取当前会话中授权码的特征项信息,以XML结构表示
BIT_SERVER_ADDRESS // 授权服务器IP地址。只对云授权有意义,其它授权方式将返回:127.0.0.1
BIT_SERVER_TIME // 授权服务器系统时间。如果是本地授权,将返回本机系统时间
BIT_CONTROL_TYPE // 授权类型。是以逗号分隔的以下几种类型的组合:Group(集团授权),Smart(智能连接), Float(可浮动), Demo(演示授权), USB(U盘授权), Force(强制认证)
BIT_VOLUME_NUMBER // 允许使用的机器数量
BIT_START_DATE // 授权开始日期
BIT_END_DATE // 授权结束日期
BIT_EXPIRATION_DAYS // 授权有效期,单位为天。有效期从激活时间算起
BIT_USAGE_NUMBER // 最大使用次数
BIT_CONSUMED_USAGE_NUMBER // 对于设定最大使用次数的授权码,返回当前使用次数
BIT_ACTIVATE_DATE // 授权码激活时间
BIT_USER_LIMIT // 集团授权用户数。对其它方式的授权返回0
BIT_LAST_UPDATE_DATE // 最后与服务器连接时间
BIT_MAX_OFFLINE_MINUTES // 强制认证最大离线时间(分钟)

返回:
根据输入类型返回的会话信息。

GetRequestInfo

    public Function GetRequestInfo (
                 ByVal sn As String,
                 ByVal type As BindingType) As String
获取当前运行环境的升级请求码,用于发起本地授权激活及升级请求。

参数:
sn - [IN] 授权码(SN)字符串。如果为空(空串或NULL)则尝试寻找所有当前本机可用的SN
type - [IN] 本地授权绑定类型。 包含以下类型:
Existing // 使用当前绑定类型,对已激活授权码进行升级时使用。
Local // 使用本机指纹进行绑定
UsbStorage // 使用USB存储器进行绑定

返回:
用于完成后续升级操作的升级请求码。

GetUpdateInfo

    public Function GetUpdateInfo (
                 ByVal url As String,
                 ByVal sn As String,
                 ByVal requestInfo As String) As String
使用请求码与授权服务器进行连接,获取升级码。本函数需要进行网络连接。

参数:
url - [IN] 自定义授权服务器地址,包括端口。如未使用自定义授权服务器则为NULL。
sn - [IN] 授权码(SN)字符串
requestInfo - [IN] 由获取请求码函数得到的请求码。

返回:
由授权服务器获得的本地授权升级码。

ApplyUpdateInfo

    public Function ApplyUpdateInfo (
                 ByVal updateInfo As String) As String
应用升级码完成本地授权激活或升级。本函数必须在获取请求码的同一环境下执行。

参数:
updateInfo - [IN] 由授权服务器获得的本地授权升级码。

返回:
确认码,记录升级状态,可在控制台上解析。

UpdateOnline

    public Sub UpdateOnline (
                 ByVal url As String,
                 ByVal sn As String)
此函数用于与授权服务器在线连接,自动完成本地授权的升级操作。本函数需要进行网络连接。

参数:
url - [IN] 自定义授权服务器地址,包括端口。如未使用自定义授权服务器则为NULL。
sn - [IN] 授权码(SN)字符串。如果为空(空串或NULL)则尝试寻找所有当前本机可用的SN

返回:

Revoke

    public Function Revoke (
                 ByVal sn As String) As String
获取用于迁出浮动授权码的请求码,以实现离线迁出操作。执行本函数后该授权码将不可用。

参数:
sn - [IN] 授权码(SN)字符串

返回:
返回用于授权码迁出的请求码。请求码应发给服务器获取迁出升级串(GetUpdateInfo),并在本地应用升级串(ApplyUpdateInfo)后才能最终完成迁出操作。

RevokeOnline

    public Sub RevokeOnline (
                 ByVal url As String,
                 ByVal sn As String)
从客户端迁出已激活的浮动授权码。授权码迁出后,可以用于其它的客户端。本函数需要进行网络连接。

参数:
url - [IN] 自定义授权服务器地址,包括端口。如未使用自定义授权服务器则为NULL。
sn - [IN] 授权码(SN)字符串

返回:

CheckOutSn

    public Sub CheckOutSn (
                 ByVal url As String,
                 ByVal featureId As UInteger)
从集团授权服务器借出一个完整的授权码,以允许客户端脱离集团服务器单独使用。被借出的集团授权码必须具有可借出属性,并在客户端成功借出后减少一个可用用户数。被借出的用户数在到期后将自动返还给集团服务器。

参数:
url - [IN] 集团授权服务器地址,包括端口。如输入NULL,则使用配置文件地址;如输入 * 号,则使用广播查找地址。
featureId - [IN] 指定借出授权码需要包含的特征项ID,为 0 则寻找第一个可借出授权码。

返回:

CheckOutFeatures

    public Sub CheckOutFeatures (
                 ByVal url As String)
从集团授权服务器借出一组特征项,这些特征项必须包含在同一个授权码中。被借出的集团授权码必须具有可借出属性,并在客户端成功借出后减少一个可用用户数。被借出的用户数在到期后将自动返还给集团服务器。

参数:
url - [IN] 集团授权服务器地址,包括端口。如输入NULL,则使用配置文件地址;如输入 * 号,则使用广播查找地址。

返回:

CheckIn

    public Sub CheckIn (
                 ByVal url As String,
                 ByVal featureId As UInteger)
提前返还从集团授权服务器借出的授权。要提前返还授权,该授权码必须具有允许提前返还属性。

参数:
url - [IN] 集团授权服务器地址,包括端口。如输入NULL,则使用配置文件地址;如输入 * 号,则使用广播查找地址。
featureId - [IN] 指定要返还授权码需要包含的特征项ID,为 0 则寻找第一个可返还授权码。

返回:

GetInfo

    public Function GetInfo (
                 ByVal sn As String,
                 ByVal type As InfoType) As String
获取授权信息及使用环境信息,数据以XML格式返回。调用此函数前客户端不需要执行登录操作。

参数:
sn - [IN] 授权码(SN)字符串
type - [IN] 获取信息类型。 包含以下类型:
BIT_INFO_SERVER_ADDRESS // 获取局域网内的集团授权服务器地址列表
BIT_INFO_SN // 获取本机已激活的授权码列表
BIT_INFO_SN_FEATURE // 获取本机已激活授权码的特征项列表
BIT_INFO_SN_LICENSE // 获取本机已激活授权码的授权信息
BIT_INFO_UPDATE_ERROR // 获取指定授权码的升级错误详细信息。是否存在详细信息由授权码类型及错误类型决定
BIT_INFO_CONFIG // 获取当前产品的配置文件信息
BIT_INFO_TOKEN_LIST // 获取当前机器上可用的BIT-ID列表信息

返回:
根据输入信息类型返回的XML信息数据。

RemoveSn

    public Sub RemoveSn (
                 ByVal sn As String)
删除指定授权码在本机的授权数据,可用于测试或当授权数据出现问题而不能通过升级解决时的故障处理。

参数:
sn - [IN] 授权码(SN)字符串

返回:

GetVersion

    public Function GetVersion () As UInteger
获取客户端安全库版本号。

参数:

返回:
客户端安全库版本号。