admin/craftlabs-authorization-sdk
1
0
Fork 0
mirror of https://github.com/hpd840321/craftlabs-authorization-sdk.git synced 2026-06-09 10:00:30 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity
Files
3f577b34d543c196a32c0daba056110e15876ff6
craftlabs-authorization-sdk/docs/c.md
T
hpd840321 3894315759 feat: add native/Java auth SDK, docs, CI, and examples 
Made-with: Cursor
2026-04-06 17:42:09 +08:00

1881 lines
106 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 比特授权云 · C 语言接口定义（离线摘录）
> 本文档由官网页面离线摘录并整理排版，便于本地检索。官方地址：<https://doc.bitanswer.cn/docs/client-api/c-interface-definitions-v2/>
---
## 认证
### Bit_Login / Bit_LoginEx
```c
BIT_STATUS Bit_Login(
BIT_PCSTR szURL,
BIT_PCSTR szSN,
BIT_UCHAR *pApplicationData,
BIT_HANDLE *pHandle,
LOGIN_MODE mode);
BIT_STATUS Bit_LoginEx(
BIT_PCSTR szURL,
BIT_PCSTR szSN,
BIT_UINT32 featureId,
BIT_PCSTR szReserved,
BIT_UCHAR *pApplicationData,
BIT_HANDLE *pHandle,
LOGIN_MODE mode);
```
授权登录。初始化运行环境，获取操作句柄。必须在除升级函数之外的其它操作前执行。根据登录模式的不同可能需要连接授权服务器。
Bit_Login 等价于 Bit_LoginEx（…, featureId=0，szReserved=NULL, …)，当需要登录包含指定特征项的授权时才需要调用Bit_LoginEx。
### 参数
- **szURL** - [IN] 自定义授权服务地址，包括端口，如未使用自定义授权服务器则为NULL。授权服务地址可以是网络地址、本地授权目录以及License串。
| **类型** | **格式** | **说明** |
| ------------- | -------------------------------- | ------------------------------------------------------------------------------ |
| **授权服务器地址** | `bit://ip:port`或`http://ip:port` | “`bit://`”开头表示集团授权服务地址 “`http://`”开头表示授权服务中心地址，一般是E3系统或者比特授权云的地址 |
| **授权文件路径** | `root://xxx` | 传入授权文件所在路径，Login就只会在该路径下查找授权，该设置等同于调用Bit_SetRootPath接口 |
| **License文件** | `lic://xxx` | 传入文件路径：读取文件内容，并加载到内存里使用 传入目录：自动加载该目录下的*.lic的授权文件 传入License串：将该License串加载到内存里使用 |
允许设置多个授权路径，通过“，”拆分。
如下：
```c
lic:///tmp,lic:///data,bit://127.0.0.1:8273
/tmp,/data,127.0.0.1:8273 // 等价第1条
```
> 注意：该接口支持通过[配置文件](https://doc.bitanswer.cn/docs/client-api/examples-of-using-the-sdk/#%E9%85%8D%E7%BD%AE%E6%96%87%E4%BB%B6)和[环境变量](https://doc.bitanswer.cn/docs/client-api/examples-of-using-the-sdk/#%E7%8E%AF%E5%A2%83%E5%8F%98%E9%87%8F)来设置该值，如果同时设置优先级为：环境变量 > API传入 > 配置文件。
- **szSN** - [IN] 授权码（SN）字符串。如果为空（空串或NULL）则尝试寻找所有当前本机可用的SN。
| **类型** | **格式** | **说明** |
| -------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| **授权码** | 比特授权云平台产生的SN 示例：`JNLTGZSE********` | 检查指定SN的License |
| **BIT-ID（BIT-ID硬件，类似于加密的USB设备）** | 格式：#`<序号>` 或 #bitid:`<序号>` 说明：`<序号>` 为 BIT-ID 的索引号，从 0 开始递增 示例：#0、#1、#`bitid:0、#bitid:1` | 使用BIT-ID授权 |
| **激活口令（帐号授权密码或SN激活口令）** | <`xxx`> 通过“<>”包裹起来，中间部分为密码 示例：<1234>, <1233>65447> | 激活口令，是指授权码激活时，需要输入的一种口令，激活后不再需要，目前仅支持浮动授权 使用帐号授权时保存的是帐号授权的密码（已经不推荐），其它授权代表激活口令 |
| **既输入SN又输入激活口令** | `xxx<password>`，授权码后边紧跟“<>” 示例：`JNLTGZSE********`<123> | |
- **featureId** - [IN] 登录授权所需要包含的特征项ID。
- **szReserved** - [IN] 一个xml串，表示登录的SN范围。
  xml格式如下：
```xml
<scope>
<feature id="" name="" ver=""/>
</scope>
```
- **pApplicationData** - [IN] 产品识别码，在Bitanswer SDK头文件里。
- **pHandle** - [OUT] 通过Login函数返回的上下文句柄。
- **mode** - [IN] 登录模式，按位操作。
| **值** | **说明** |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| **BIT_MODE_LOCAL(0x01)** | 只检查本地授权（单机授权、BIT-ID授权、内存授权） |
| **BIT_MODE_REMOTE(0x02)** | 只检查远端授权（云授权、帐号授权、集团授权） |
| **BIT_MODE_AUTO(0x03)** | 既检查本地授权，也检查远端授权（配置了远端IP的条件下） 优先级：本地授权 > 远端授权 |
| **BIT_MODE_CACHE(0x4)** | 云授权缓存 由于云授权SN比较难记，但登录时又必须传输，则可以使用该选项将SN串缓存起来，下次使用Login登录时可以不输入SN |
| **BIT_MODE_USB(0x8)** | USB授权 |
| **LOGIN_MODE_PROCESS(0x10)** | 按进程模式登录 **集团授权**：普通模式一台机器占用一个用户数，进程模式是一个进程占用一个用户数 **其它授权**：不生效 |
| **LOGIN_MODE_SESSION(0x40)** | Session模式登录 **集团授权**：该模式比LOGIN_MODE_PROCESS控制的更细，一次会话占用一个点 **其它授权**：不生效 |
| **LOGIN_MODE_HIGH_PRIORITY(0x20)** | 高优先级登录 **云授权：**用户可以通过高优先级登录来挤掉普通登录。如果登录模式都是高优先级或者普通优先级则不生效 **其它授权：**不生效 |
| **LOGIN_MODE_NO_NETWORK（0x200）** | 禁用网络 禁止库联网时使用 |
| **LOGIN_MODE_CHECK_USERNAME(0x800)** | 检查当前设备的用户名 **集团授权：**默认情况下：一台的设备用户名不一样，会被识别为同一个机器，加了该模式，会识别为不同的设备。即：原来一台设备占用一个点，加了这个选项，“一台设备 + 用户名”占用一个点 **其它授权**：不生效 |
| **LOGIN_MODE_USE_SESSIONID(0x1000)** | Logout时不释放点数，并由第三方程序维护心跳 |
| **LOGIN_MODE_HIGH_PERFORMANCE(0x2000)** | 使用高性能模式登录 **集团授权：**将Login的两次请求转化为一次请求，可以减少服务负载 **其它授权：**不支持 |
| **LOGIN_MODE_PERSISTENT_CONN(0x4000)** | 使用长连接模式登录，只有集团授权支持，其它授权不支持 通过长连接可以减少TCP的频繁创建带来的性能损耗，但是会增加服务的socket连接数 |
| **LOGIN_MODE_CREATE_HANDLE_ONLY(0x10000)** | 仅创建handle，不检查License **集团授权：**Login默认情况下会连接集团服务并占用一个用户数，加了该模式之后，在调用Query相关接口时才会连接服务器 **其它授权：**Login默认情况下会检查授权的可用性，加了该模式之后，在Query时才会检查 |
| **LOGIN_MODE_CREATE_NEW_HANDLE(0x20000)** | 创建新handle，每次创建的handle唯一 Login的请求默认都发pid 可以针对每一个handle进行设置属性，不会相互影响 |
| **LOGIN_MODE_MID(0x40000)** | 按设备占点（当没有设置LOGIN_MODE_ACCOUNT和LOGIN_MODE_GROUP时，默认按设备扣点） |
| **LOGIN_MODE_ACCOUNT(0x80000)** | 按帐号占点 |
| **LOGIN_MODE_GROUP(0x100000)** | 按分组名占点 |
### 示例
```c
// 使用高性能模式检查集团授权
BIT_HANDLE handle = NULL;
BIT_STATUS status = Bit_Login(
NULL, NULL, application_data,
&handle, LOGIN_MODE(BIT_MODE_REMOTE | LOGIN_MODE_HIGH_PERFORMANCE ));
if (status == BIT_SUCCESS) {
// 校验成功
}
// 使用Session + 长连接模式检查集团授权
BIT_HANDLE handle = NULL;
BIT_STATUS status = Bit_Login(
NULL, NULL, application_data,
&handle, LOGIN_MODE(BIT_MODE_REMOTE | LOGIN_MODE_SESSION | LOGIN_MODE_PERSISTENT_CONN ));
if (status == BIT_SUCCESS) {
// 校验成功
}
// 使用内存License
BIT_HANDLE handle = NULL;
BIT_CHAR *pLicense = "lic://xxxxxxx";
BIT_STATUS status = Bit_Login(pLicense, NULL, application_data, &handle, BIT_MODE_AUTO);
if (status == BIT_SUCCESS) {
// 校验成功
}
// 先检查单机授权吗，如果没有再检查集团授权或云授权
BIT_HANDLE handle = NULL;
BIT_STATUS status = Bit_Login(NULL, NULL, application_data, &handle, BIT_MODE_AUTO);
if (status == BIT_SUCCESS) {
// 校验成功
}
// 检查包含指定特征项的授权
BIT_HANDLE handle = NULL;
BIT_UINT32 featureId = 1;
BIT_STATUS status = Bit_LoginEx(NULL, NULL, featureId, NULL, application_data, &handle, BIT_MODE_AUTO);
if (status == BIT_SUCCESS) {
// 校验成功
}
```
### Bit_LoginByToken
```c
BIT_STATUS Bit_LoginByToken(
BIT_PCSTR pUrl,
BIT_PCSTR pToken,
BIT_UCHAR *pApplicationData,
BIT_HANDLE *pHandle)
```
帐号授权的登录接口。仅支持两种认证方式，这里是使用比特授权云平台自己产生的access_token进行认证。
### 参数
- **pUrl** - [IN] 服务器地址，可以为空。
- **pToken** - [IN] 第三方身份源颁发的token或id_token，通过前缀区分。
| **值** | **说明** |
| ----------------- | ---------------- |
| **token:xxx或xxx** | 使用access_token登录 |
- **pApplicationData** - [IN] 产品识别码，记录在接口定义文件中，与产品一一对应。
- **pHandle** - [OUT] 通过Login函数返回的上下文句柄。
### Bit_LoginByTokenEx
```c
BIT_STATUS Bit_LoginByTokenEx(
BIT_PCSTR pUrl,
BIT_PCSTR pBusinessGuid,
BIT_PCSTR pToken,
BIT_PCSTR pIdpGuid,
BIT_PCSTR pGrantType,
BIT_UCHAR *pApplicationData,
BIT_HANDLE *pHandle)
```
帐号授权的登录接口。仅支持两种认证方式，这里是使用OIDC协议产生的id_token认证。
### 参数
- **pUrl** - [IN] 服务器地址，可以为空。
- **pBussinessGuid** - [IN] 业务guid，在比特授权云平台获取。
- **pToken** - [IN] 第三方身份源颁发的token或id_token，通过前缀区分。
| **值** | **说明** |
| ---------------- | ------------ |
| **id_token:xxx** | 使用id_token登录 |
- **pIdpGuid** - [IN] 第三方身份源guid，在比特授权云平台获取。参数为空表示使用比特授权云平台产生的token进行登录，即Bit_LoginByToken。
- **pGrantType** - [IN] 授权类型。固定值为“bitanswer:idp:oidc:id_token”。
- **pApplicationData** - [IN] 产品识别码，记录在接口定义文件中，与产品一一对应。
- **pHandle** - [OUT] 通过Login函数返回的上下文句柄。
### Bit_LoginByPassword
```c
BIT_STATUS Bit_LoginByPassword(
BIT_PCSTR szURL,
BIT_PCSTR szBusinessGuid,
BIT_PCSTR szBusinessSecret,
BIT_PCSTR szAccount,
BIT_PCSTR szPassword,
BIT_UCHAR *pApplicationData,
BIT_HANDLE *pHandle);
```
通过用户名和密码登录帐号授权。
### 参数
- **szURL** - [IN] 服务器地址，可以为空。
- **pBussinessGuid** - [IN] 业务编号，在比特授权云平台获取。
- **szBusinessSecret** [IN] 业务密钥，在比特授权云平台获取。
- **szAccount** - [IN] 用户帐号。
- **szPassword** - [IN] 用户密码。
- **pApplicationData** - [IN] 产品识别码，记录在接口定义文件中，与产品一一对应。
- **pHandle** - [OUT] 通过Login函数返回的上下文句柄。
### Bit_Logout
```c
BIT_STATUS Bit_Logout (
BIT_HANDLE handle)
```
此函数用于释放上下文句柄，退出登录状态，与Login相关接口一一对应。
### 参数
- **handle** - [IN] 通过Login函数返回的上下文句柄。
### Bit_Revoke
```c
BIT_STATUS Bit_Revoke (
BIT_PCSTR szURL,
BIT_PCSTR szSN,
BIT_UCHAR *pApplicationData,
BIT_CHAR *pRevocationInfo,
BIT_UINT32 *pRevocationInfoSize)
```
从客户端迁出已激活的浮动授权码。授权码迁出后，可以用于其它的客户端。根据输入参数的不同，本函数可用于在线或离线迁出。
### 参数
- **szURL** - [IN] 自定义授权服务器地址，包括端口。如未使用自定义授权服务器则为NULL。
- **szSN** - [IN] 授权码（SN）字符串。
- **pApplicationData** - [IN] 产品识别码。记录在接口定义文件中，与产品一一对应。
- **pRevocationInfo** - [OUT] 迁出请求码的存储区地址。为NULL表示进行在线迁出，否则API将执行手工离线迁出，请求码应发给服务器进行确认。
- **pRevocationInfoSize** - [IN/OUT] 输入时为请求码存储区大小，输出时为请求码长度。如此参数为NULL，函数将选择在线迁出。
### Bit_RemoveSn
```c
BIT_STATUS Bit_RemoveSn (
BIT_PCSTR szSN,
BIT_UCHAR *pApplicationData)
```
删除指定授权码在本机的授权数据。
### 参数
- **szSN** - [IN] 授权码（SN）字符串。
- **pApplicationData** - [IN] 产品识别码。记录在接口定义文件中，与产品一一对应。
### Bit_Heartbeat
```c
BIT_STATUS Bit_Heartbeat(
BIT_HANDLE handle,
BIT_UINT32 *pReconnectsNum)
```
手动心跳，可以无限次调用，10s只会触发一次。
注：当自动心跳停止后，调用该接口可以尝试恢复自动心跳。
### 参数
- **handle** - [IN] 通过Login函数返回的上下文句柄。
- **pReconnectsNum** - [OUT] 保存心跳失败次数，开发上可以根据该次数决定是否退出程序。
### Bit_SessionControl
```c
BIT_STATUS Bit_SessionControl(
BIT_PCSTR szURL,
BIT_PCSTR pSessionId,
BIT_UINT32 type,
BIT_UCHAR *pApplicationData,
BIT_CHAR *pValue,
BIT_UINT32 *pValueLen)
```
控制或设置session的信息。具体使用场景可参考《浏览器并发控制》文档。
### 参数
- **szURL** - [IN] 自定义授权服务器地址，包括端口。如未使用自定义授权服务器则为NULL。
- **pSessionId** - [IN] Login后的sessionId，通过[Bit_GetSessionInfo](https://doc.bitanswer.cn/docs/client-api/c-interface-definitions-v2/#Bit_GetSessionInfo)可以获取。
- **type** - [IN] 类型。
| **类型** | **说明** |
| --------------------------- | ------------------ |
| **SESSION_CTL_LOGOUT(0x1)** | 释放session |
| **SESSION_CTL_CHECK(0x2)** | 触发心跳并获取sessionId状态 |
- **pApplicationData** - [IN] 产品识别码。记录在接口定义文件中，与产品一一对应。
- **pValue** - [OUT] 数据缓存区。
- **pValueLen** - [IN/OUT] 输入时是数据缓存区的大小，输出时是实际数据长度。
### Bit_SetSessionState
```c
BIT_STATUS Bit_SetSessionState (
BIT_HANDLE handle,
BIT_UINT32 state,
BIT_VOID *pReserved)
```
设置客户端的状态为空闲状态或繁忙状态或激活状态。
### 参数
- **handle** - [IN] 通过Login函数返回的上下文句柄。
- **state** - [IN] 设置客户端的状态选项。
| **值** | **说明** |
| ------------------------ | -------------------------------------------------- |
| **SESSION_STATE_UNSET** | 默认值，表示不设置客户端的状态，服务端根据心跳状态来维护session，心跳断开则释放session |
| **SESSION_STATE_IDLE** | 表示设置客户端为空闲态，服务端会在空闲时间超过设10分钟后自动释放session |
| **SESSION_STATE_BUSY** | 表示设置客户端为繁忙状态，服务端不会自动释放，直到心跳断开或者客户端主动释放 |
| **SESSION_STATE_ACTIVE** | 表示设置客户端为活跃状态，重新计算空闲时间 |
- **pReserved** - [OUT] 目前保留必须传NULL。
### 示例
```c
BIT_STATUS status = BIT_SUCCESS;
BIT_UINT32 reserved = 0;
if (用户正在操作) {
status = Bit_SetSessionState (handle, SESSION_STATE_ACTIVE, &reserved);
} else if (用户空闲) {
status = Bit_SetSessionState (handle, SESSION_STATE_IDLE, &reserved);
}
```
## 激活升级
### Bit_UpdateOnline
```c
BIT_STATUS Bit_UpdateOnline (
BIT_PCSTR szURL,
BIT_PCSTR szSN,
BIT_UCHAR *pApplicationData)
```
此函数用于与授权服务器在线连接，自动完成本地授权的升级操作。本函数需要进行网络连接。
### 参数
- **szURL** - [IN] 自定义授权服务器地址，包括端口。如未使用自定义授权服务器则为NULL。
- **szSN** - [IN] 该参数可以传入授权码；激活口令；帐号密码；BIT-ID序号。传入方式参考[Bit_Login](https://doc.bitanswer.cn/docs/client-api/c-interface-definitions-v2/#Bit_LoginBit_LoginEx)的szSN参数说明。
- **pApplicationData** - [IN] 产品识别码。记录在接口定义文件中，与产品一一对应。
### 示例
```c
BIT_CHAR *pSn = "<授权码>";
BIT_STATUS status = Bit_UpdateOnline("", pSn, application_data);
if (status == BIT_SUCCESS) {
// 激活或升级成功
}
```
### Bit_GetRequestInfo
```c
BIT_STATUS Bit_GetRequestInfo (
BIT_PCSTR szSN,
BIT_UCHAR *pApplicationData,
BINDING_TYPE type,
BIT_CHAR *pRequestInfo,
BIT_UINT32 *pRequestInfoSize)
```
获取当前运行环境的升级请求码，用于发起本地授权激活及升级请求。如果第一次调用返回错误码260，说明传入的pRequestInfoSize太小，可传入返回的pRequestInfoSize再重新调用一次。
### 参数
- **szSN** - [IN] 授权码（SN）字符串。如果为空（空串或NULL）则尝试寻找所有当前本机可用的SN。
- **pApplicationData** - [IN] 产品识别码。记录在接口定义文件中，与产品一一对应。
- **type** - [IN] 获取请求码的类型。
| **类型** | **说明** |
| -------------------- | ----------------------- |
| **BINDING_EXISTING** | 使用当前绑定类型，对已激活授权码进行升级时使用 |
| **BINDING_LOCAL** | 使用本机指纹进行绑定 |
| **REQ_TYPE_MID** | 获取设备码 |
- **pRequestInfo** - [OUT] 用于存储请求码的存储区地址。
- **pRequestInfoSize** - [IN/OUT] 输入时为请求码存储区大小，输出时为请求码长度。
### 示例
```c
// 获取请求串
BIT_CHAR *pSn = "<授权码>";
BIT_CHAR buff[1024] = { 0 };
BIT_UINT32 len = sizeof(buff);
BIT_STATUS status = Bit_GetRequestInfo (pSn, application_data, BINDING_LOCAL, buff, &len);
if (status == BIT_SUCCESS) {
// 请求串保存在buff里
}
// 获取设备码
BIT_STATUS status = Bit_GetRequestInfo (NULL, application_data, REQ_TYPE_MID, buff, &len);
if (status == BIT_SUCCESS) {
// 设备码保存在buff里
}
```
### Bit_ApplyUpdateInfo
```c
BIT_STATUS Bit_ApplyUpdateInfo(
BIT_UCHAR *pApplicationData,
BIT_PCSTR pUpdateInfo,
BIT_CHAR *pReceipt,
BIT_UINT32 *pReceiptSize)
```
应用升级码完成本地授权激活或升级。本函数必须在获取请求码的同一环境下执行。
### 参数
- **pApplicationData** - [IN] 产品识别码。记录在接口定义文件中，与产品一一对应。
- **pUpdateInfo** - [IN] 由授权服务器获得的本地授权升级码。
- **pReceiptInfo** - [OUT] 确认码，记录升级状态，可在控制台上解析。
- **pReceiptInfoSize** - [IN/OUT] 输入时为存储区大小，输出时为确认码长度。
### 示例
```c
// 获取请求串
BIT_CHAR *pUpdateInfo = "<升级串>";
BIT_CHAR buff[1024] = { 0 };
BIT_UINT32 len = sizeof(buff);
BIT_STATUS status = Bit_ApplyUpdateInfo(application_data, pUpdateInfo, buff, &len);
if (status == BIT_SUCCESS) {
// 升级串使用成功，Buff里保存的是确认串
}
```
### Bit_ApplyUpdateInfoEx
```c
BIT_STATUS Bit_ApplyUpdateInfoEx(
BIT_CHAR *pScope,
BIT_UCHAR *pApplicationData,
BIT_PCSTR pUpdateInfo,
BIT_CHAR *pReceipt,
BIT_UINT32 *pReceiptSize);
```
应用升级码完成远程集团授权激活或升级。一般不建议使用。
### 参数
- **pScope** - [IN] 集团服务的URL。
- **pApplicationData** - [IN] 产品识别码。记录在接口定义文件中，与产品一一对应。
- **pUpdateInfo** - [IN] 由授权服务器获得的本地授权升级码。
- **pReceiptInfo** - [OUT] 确认码，记录升级状态，可在控制台上解析。pReceiptInfoSize - [IN/OUT] 输入时为存储区大小，输出时为确认码长度。
### Bit_GetUpdateInfo
```c
BIT_STATUS Bit_GetUpdateInfo (
BIT_PCSTR szURL,
BIT_PCSTR szSN,
BIT_UCHAR *pApplicationData,
BIT_PCSTR pRequestInfo,
BIT_CHAR *pUpdateInfo,
BIT_UINT32 *pUpdateInfoSize)
```
使用请求码与授权服务器进行连接，获取升级码。本函数需要进行网络连接。
### 参数
- **szURL** - [IN] 自定义授权服务器地址，包括端口。如未使用自定义授权服务器则为NULL。
- **szSN** - [IN] 授权码（SN）字符串。
- **pApplicationData** - [IN] 产品识别码。记录在接口定义文件中，与产品一一对应。
- **pRequestInfo** - [IN] 由获取请求码函数得到的请求码。
- **pUpdateInfo** - [OUT] 由授权服务器获得的本地授权升级码。
- **pUpdateInfoSize** - [IN/OUT] 输入时为存储区大小，输出时为升级码长度。
## 特征项操作
### Bit_BatchBegin
```c
BIT_STATUS Bit_BatchBegin(
BIT_HANDLE handle,
BIT_UINT32 mode)
```
开启批量Query模式，调用此API后调用的所有Query相关API，全部由Bit_BatchEnd接口批量提交连接集团服务。
### 参数
- **handle** - [IN] 通过Login函数返回的上下文句柄。
- **mode** - [IN] 批量请求的行为模式。
| **类型** | **说明** |
| --------------------------------- | ----------------------------- |
| **BIT_BATCH_MODE_CONTINUE (0x0)** | 批量提交过程中，遇到失败的接口会记录错误信息，并且继续执行 |
| **BIT_BATCH_MODE_BREAK (0x01)** | 批量提交过程中，遇到失败的接口会记录错误信息，直接返回错误 |
### Bit_BatchEnd
```c
BIT_STATUS Bit_BatchEnd(
BIT_HANDLE handle,
BIT_UINT32 *pResultList,
BIT_UINT32 *pResultListSize)
```
批量提交Query请求。
### 参数
- **handle** - [IN] 通过Login函数返回的上下文句柄。
- **pResultList** - [OUT] 按顺序返回每个接口的错误码，0表示成功，非0表示失败，传NULL表示清理添加的批量数据。
- **pResultListSize** - [OUT] 返回调用接口的数量。
### 示例
```c
// 开启批次
Bit_BatchBegin(handle, BIT_BATCH_MODE_CONTINUE);
BIT_UINT32 result[3] = { 0 };
BIT_UINT32 resultNum = 3;
BIT_TICKET ticket = NULL;
BIT_UINT32 capacity = 0;
Bit_QueryFeature(handle, 1, &capacity);
Bit_QueryFeatureEx2(handle, "test", 0, 10, "1.0", &ticket);
// 批量提交
Bit_BatchEnd(handle, result,& resultNum) ;
if (result[0] == BIT_SUCCESS)
{
// Bit_QueryFeature(1) success
}
if (result[1] == BIT_SUCCESS)
{
// Bit_QueryFeatureEx2 ("test") success}
}
```
### Bit_QueryFeature
```c
BIT_STATUS Bit_QueryFeature (
BIT_HANDLE handle,
BIT_UINT32 featureId,
BIT_UINT32 *pCapacity)
```
开发商可以对软件的某个功能进行单独授权，当程序运行该模块时，可以通过该接口检查是否可用。
对于单机授权：只检查特征项是否可用。
云/帐号/集团授权：调用该接口将占用一个用户数，用户数占满时，调用该接口会报错。开发商可以通过该方式来控制并发。（当客户端断开连接后，服务端会自动释放占用的用户数）
### 参数
- **handle** - [IN] 通过Login函数返回的上下文句柄。
- **featureId** - [IN] 特征项ID。
- **pCapacity** - [OUT] 当不为NULL时，获取特征项当前可用用户数。
重复调用引用会+1，通过Bit_ReleaseFeature来减少引用，当引用减少到0时，释放占用的用户数。
### 示例
```c
BIT_UINT32 featureId = 1;
BIT_UINT32 capacity = 0;
BIT_STATUS status = Bit_QueryFeature(handle, featured, &capacity);
if (status == BIT_SUCCESS) {
// 特征项1有效
}
```
### Bit_ReleaseFeature
```c
BIT_STATUS Bit_ReleaseFeature (
BIT_HANDLE handle,
BIT_UINT32 featureId,
BIT_UINT32 *pCapacity)
```
释放所占用的用户数，该函数和Bit_QueryFeature一一对应。
### 参数
- **handle** - [IN] 通过Login函数返回的上下文句柄。
- **featureId** - [IN] 特征项ID。
- **pCapacity** - [OUT] 当不为NULL时，获取特征项当前可用用户数。
### 示例
```c
BIT_UINT32 capacity = 0;
BIT_STATUS status = Bit_QueryFeature(handle, 1, capacity);
if (status != BIT_SUCCESS) {
return;
}
// 执行业务逻辑
// 执行后，进行释放
status = Bit_ReleaseFeature(handle, 1, &capacity);
```
### Bit_QueryFeatureEx
```c
BIT_STATUS Bit_QueryFeatureEx (
BIT_HANDLE handle,
BIT_UINT32 featureId,
BIT_UINT32 mode,
BIT_UINT32 required,
BIT_UINT32 *pCapacity,
BIT_PCSTR xmlScope)
```
集团授权专用，该接口支持占用指定用户数，支持通过特征项版本进行检查。
### 参数
- **handle** - [IN] 通过Login函数返回的上下文句柄。
- **featureId** - [IN] 特征项ID。
- **mode** - [IN]
| **类型** | **说明** |
| ----------------------------- | ------------------------------------------------------------------------------------- |
| **BIT_QUERY_DEFAULT(0x0)** | 非阻塞占用required个用户数，如果用户数不够将返回错误 |
| **BIT_QUERY_AVAILABLE(0x01)** | 尽可能的占用required个用户数，如果用户数不够将占用剩余用户数 例如：Feature剩余10个用户数。Required需要占用20个，则返回成功，并占用10个用户数 |
| **BIT_QUERY_CHECK(0x02)** | 获取当前session占用的用户数 |
| **BIT_QUERY_TEST(0x100)** | 该类型可以与上面的选项组合使用，检查操作是否可以成功，但并不占用用户数 例如：（BIT_QUERY_DEFAULT |
- **required** - [IN] 请求的用户数，该接口可以调用多次，实际的占用的用户数为，每次调用的最大值。
  示例：
  第一次：required了10个。
  第二次：required了8个，此时总共占用10个。
  第三次：required了15个，此时总共占用15个。
- **pCapacity** - [OUT] 当不为NULL时，获取特征项当前可用用户数。
- **xmlScope** - [IN] 可以传入特征项版本。示例“1.0”，“2.0”，如果为空，则匹配任意版本的特征项。
### 示例
```c
// 占用特征项ID为8的10个用户数：
BIT_UINT32 capacity = 0;
BIT_STATUS status = Bit_QueryFeatureEx (
handle,
8,
BIT_QUERY_DEFAULT,
10,
&capacity,
NULL);
if (status == BIT_SUCCESS) {
// 特征项“8”用户数占用成功
// 执行业务逻辑代码
}
```
### Bit_ReleaseFeatureEx
```c
BIT_STATUS Bit_ReleaseFeatureEx (
BIT_HANDLE handle,
BIT_UINT32 featureId,
BIT_UINT32 consumed,
BIT_UINT32 *pCapacity,
BIT_PCSTR xmlScope)
```
集团授权专用，释放指定的用户数。该接口与Bit_QueryFeatureEx对应。
### 参数
- **handle** - [IN] 通过Login函数返回的上下文句柄。
- **featureId** - [IN] 特征项ID。
- **consumed** - [IN] 释放指定用户数，如果为0，表示释放全部用户数。
- **pCapacity** - [OUT] 返回剩余用户数。
- **xmlScope** - [IN] 可以传入特征项版本。注意：必须与Bit_QueryFeatureEx的输入的版本一致，才可以释放。
### 示例
```c
// 释放占用特征项ID为8的2个用户数：
BIT_UINT32 capacity = 0;
BIT_STATUS status = Bit_ReleaseFeatureEx (
handle,
8,
2,
&capacity,
NULL)
if (status == BIT_SUCCESS) {
// 用户数释放成功
}
```
### Bit_QueryFeatureEx2
```c
BIT_STATUS Bit_QueryFeatureEx2 (
BIT_HANDLE handle,
BIT_PCSTR featureName,
BIT_UINT32 mode,
BIT_UINT32 required,
BIT_PCSTR xmlScope,
BIT_TICKET *pTicket)
```
可以使用“特征项名称 + 特征项版本”进行用户数占用，支持队列模式。
对于单机授权：只检查特征项是否可用。
云/帐号/集团授权：调用该接口将占用一个用户数，用户数占满时，调用该接口会报错。开发商可以通过该方式来控制并发。（当客户端断开连接后，服务端会自动释放占用的用户数）
### 参数
- **handle** - [IN] 通过Login函数返回的上下文句柄。
- **featureName** - [IN] 特征项名称。
- **mode** - [IN]
| **类型** | **说明** |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **BIT_QUERY_DEFAULT(0x00)** | 非阻塞占用required个用户数，如果用户数不够将返回错误 **注意：**云/帐号授权仅支持该模式 |
| **BIT_QUERY_AVAILABLE(0x01)** | 尽可能的占用required个用户数，如果用户数不够将占用剩余用户数。 例如：Feature剩余10个用户数。Required需要占用20个，则返回成功，并占用10个用户数。 |
| **BIT_QUERY_WAIT(0x03)** | 加入等待队列，可以设置超时，超时后，将自动返回 |
| **BIT_QUERY_QUEUE(0x04)** | 加入队列，通过Bit_GetTicketInfo可以查看队列状态 |
| **BIT_QUERY_TEST(0x100)** | 该类型可以与上面的选项组合使用，检查操作是否可以成功，但并不占用用户数 例如：（BIT_QUERY_DEFAULT |
| **BIT_QUERY_SHARED_USERS(0x200)** | User用户数共享。 默认情况下调用该接口的用户数是不共享的，即：第一次QueryFeatureEx2了10个用户数，第二次QueryFeatureEx2了10个用户数，总共占用20个用户数。 当设置了该属性，如果两次QueryFeature的特征项名称、版本都一致，则用户数是可以合并的，例如：两次各QueryFeatureEx2了10个用户数，则总共占用10用户数。 |
| **BIT_QUERY_SERVICE_RANDOM(0x400)** | IP随机。 该模式需要与Login的LOGIN_MODE_CREATE_HANDLE_ONLY配合使用。 设置了该模式后，当Login的handle没有登录过，则在连接服务器时会随机轮询IP。 默认情况下，客户端会按配置的IP顺序挨个查找，设置了该模式会随机轮询，从而减少排在前面的IP负载。 |
| **BIT_QUERY_USE_ID(0x800)** | 使用featureId占用feature。 设置了该模式后，featureName参数必须传入纯数字的字符串，例如“1”，客户端会将该字符串转化为featureId发送给服务端来占用featureId为1的feature。 |
| **BIT_QUERY_MID_ONLY(0x1000)** | 按MID占用特征项。 - 未指定MID_ONLY时：默认优先占用已绑定MID的特征项；若不存在，则占用未绑定MID的特征项。- 指定MID_ONLY时：仅允许占用已绑定MID的特征项，具体场景及返回结果如下： - 若集团服务的所有特征项均未绑定MID，返回错误码1924。 - 若集团服务存在绑定MID的特征项，但客户端传入的MID与集团授权绑定的MID不匹配，返回错误码416。 - 若集团服务存在绑定MID的特征项，且客户端传入的MID与集团授权绑定的MID匹配，正常占用特征项。**版本支持：**14.5.0及以上版本新增类型，需配合14.5.0及以上版本的集团服务和客户端库使用 |
- **required** - [IN] 请求的用户数。
- **xmlScope** - [IN] 可以传入特征项版本。示例：“1.0”，“2.1”。
- **pTicket** - [OUT]
### 示例
```c
// 占用特征项A 1.0版本，5个用户数：
BIT_TICKET ticket = NULL;
BIT_STATUS status = Bit_QueryFeatureEx2 (
handle,
"特征项A",
BIT_QUERY_DEFAULT,
5,
"1.0",
&ticket);
if (status == BIT_SUCCESS) {
// 占用成功，执行业务逻辑
}
```
### Bit_ReleaseFeatureEx2
```c
BIT_STATUS Bit_ReleaseFeatureEx2 (
BIT_TICKET ticket,
BIT_UINT32 consumed)
```
释放ticket所占用的用户数。该函数和Bit_QueryFeatureEx2一一对应。
### 参数
- **ticket** - [IN] 通过QueryFeatureEx2返回的句柄。
- **consumed** - [IN] 保留值，必须是0。
### 示例
```c
BIT_STATUS status = Bit_ReleaseFeatureEx2 (ticket, 0);
if (status == BIT_SUCCESS) {
// 释放ticket占用的用户数
}
```
**特征项Query相关接口比较**
| **函数** | **特征项ID** | **特征项名称** | **特征项版本** | **一次Query多个用户数** | **队列** | **用户数递增/递减** |
| ----------------------- | --------- | --------- | --------- | ---------------- | ------ | ------------ |
| **Bit_QueryFeature** | 支持 | | | | | |
| **Bit_QueryFeatureEx** | 支持 | | 支持 | 支持 | | 支持 |
| **Bit_QueryFeatureEx2** | 支持 | 支持 | 支持 | 支持 | 支持 | |
### Bit_GetFeatureInfo2
```c
BIT_STATUS Bit_GetFeatureInfo2 (
BIT_HANDLE handle,
BIT_PCSTR featureName,
BIT_PCSTR xmlScope,
BIT_INT32 *pExpired)
```
检查特征项是否存在，不会占用授权码或特征项的用户数，获取特征项的剩余有效期。
### 参数
- **handle** - [IN] 通过Login函数返回的上下文句柄。
- **featureName** - [IN] 产品的特征项名称。
- **xmlScope** - [IN] 查找范围，可以通过 xml 格式传入版本，也可以直接传入版本的字符串。
```xml
<scope>
<featureVersion>1.1</featureVersion>
</scope>
<!-- 或者直接输入：'1.1' -->
```
- **pExpired** - [OUT] 返回该特征项的剩余有效期，正数代表剩余有效期，负数代表过期天数，36500代表永久有效。
### Bit_GetFeatureInfoEx2
```c
BIT_STATUS Bit_GetFeatureInfoEx2(
BIT_HANDLE handle,
BIT_PCSTR featureName,
BIT_PCSTR xmlScope,
BIT_CHAR *pFeatureInfo,
BIT_UINT32 *pFeatureInfoSize);
```
获取指定feature的信息，以XML格式返回。
### 参数
- **handle** - [IN] 通过Login函数返回的上下文句柄。
- **featureName** - [IN] 产品的特征项名称。
- **xmlScope** - [IN] 查找范围，可以通过 xml 格式传入版本，也可以直接传入版本的字符串。
```xml
<scope>
<featureVersion>1.1</featureVersion>
</scope>
<!-- 或者直接输入：'1.1' -->
```
- **pFeatureInfo** - [OUT] feature信息存储区地址。
- **pFeatureInfoSize** - [IN/OUT] 会话存储区大小。
### Bit_GetTicketInfo
```c
BIT_STATUS Bit_GetTicketInfo(
BIT_TICKET ticket,
BIT_UINT32 type,
BIT_CHAR *pXmlInfo,
BIT_UINT32 *pSize)
```
获取ticket信息。
### 参数
- **ticket** - [IN] Bit_QueryFeatureEx2产生的句柄。
- **type** - [IN] 类型。
| **类型** | **说明** |
| ------------------------------ | -------------- |
| **BIT_TICKET_TYPE_USERS(0x1)** | 获取ticket占用的用户数 |
| **BIT_TICKET_TYPE_CHECK(0x2)** | 检查当前ticket的状态 |
| **BIT_TICKET_TYPE_INFO(0x3)** | 获取当前ticket的信息 |
- **pXmlInfo** - [OUT] ticket信息存储区地址。
- **pSize** - [IN/OUT] 输入时为存储区长度，输出时为返回信息的长度。
BIT_TICKET_TYPE_INFO返回的xml信息如下
```c
<?xml version='1.0' encoding='UTF-8'?>
<ticketInfo>
<requestInfo>
<fId>1</fId> <!-- 请求feature的id -->
<fName>test</fName> <!-- 请求feature的名称 -->
<requestUserNumber>10</requestUserNumber> <!-- 请求feature的点数 -->
<requestFversion>1.0</requestFversion> <!-- 请求feature的版本 -->
</requestInfo>
<occupationInfos>
<occupationInfo>
<snInfo>
<sn>4HAYJUOA********</sn> <!-- 占用的是那个sn下的feature -->
<controlType>Local/group</controlType> <!-- 占用的feature类型 -->
</snInfo>
<occFversion>1.0</occFversion> <!-- 占用feature的版本 -->
<occUserNumber>3</occUserNumber> <!-- 占用feature的点数 -->
</occupationInfo>
<occupationInfo>
<snInfo>
<sn>4HAYJUOA********</sn> <!-- 占用的是那个sn下的feature -->
<controlType>Local/group</controlType> <!-- 占用的feature类型 -->
</snInfo>
<occFversion>2.0</occFversion> <!-- 占用feature的版本 -->
<occUserNumber>7</occUserNumber> <!-- 占用feature的点数 -->
</occupationInfo>
</occupationInfos>
</ticketInfo>
```
### Bit_ConvertFeature
```c
BIT_STATUS Bit_ConvertFeature(
BIT_HANDLE handle,
BIT_UINT32 featureId,
BIT_UINT32 para1,
BIT_UINT32 para2,
BIT_UINT32 para3,
BIT_UINT32 para4,
BIT_UINT32 *pResult);
```
使用“算法”类型的特征项对输入参数进行变换操作，得到唯一对应的4字节结果。
### 参数
- **handle** - [IN] 通过Login函数返回的上下文句柄。
- **featureId** - [IN] 产品的特征项ID。
- **para1** - [IN] 变换输入因子1。
- **para2** - [IN] 变换输入因子2。
- **para3** - [IN] 变换输入因子3。
- **para4** - [IN] 变换输入因子4。
- **pResult** - [OUT] 变换结果。
### 示例
```c
BIT_HANDLE handle = xx,
BIT_UINT32 featureId = xx;
BIT_UINT32 par1 = 0x1234;
BIT_UINT32 par2 = 0x2234;
BIT_UINT32 par3 = 0x3234;
BIT_UINT32 par4 = 0x4234;
BIT_UINT32 convertResult;
BIT_STATUS status = Bit_ConvertFeature(handle, featureId, par1, par2, par3, par4, &convertResult);
```
### Bit_EncryptFeature
```c
BIT_STATUS Bit_EncryptFeature(
BIT_HANDLE handle,
BIT_UINT32 featureId,
BIT_VOID *pPlainBuffer,
BIT_VOID *pCipherBuffer,
BIT_UINT32 dataBufferSize);
```
使用“密钥”类型的特征项对输入的明文进行加密，返回密文结果。
### 参数
- **handle** - [IN] 通过Login函数返回的上下文句柄。
- **featureId** - [IN] 产品的特征项ID。
- **pPlainBuffer** - [IN] 数据缓存区地址，用于存储明文数据。
- **pCipherBuffer** - [OUT] 数据缓存区地址，用于存储密文数据。
- **bufferSize** - [IN] 数据长度，最大长度为256字节。
### 示例
```c
BIT_HANDLE handle = xx,
BIT_UINT32 featureId = xx;
BIT_UCHAR plainbuffer[256] = "this is plain data";
BIT_UCHAR cipherbuffer[256] = { 0 };
BIT_UINT32 dataLen = strlen(plainbuffer);
BIT_STATUS status = Bit_EncryptFeature(handle, featureId, plainbuffer, cipherbuffer, dataLen);
```
### Bit_DecryptFeature
```c
BIT_STATUS Bit_DecryptFeature(
BIT_HANDLE handle,
BIT_UINT32 featureId,
BIT_VOID *pCipherBuffer,
BIT_VOID *pPlainBuffer,
BIT_UINT32 dataBufferSize);
```
使用“密钥”类型的特征项对输入的密文进行解密，返回明文结果。
### 参数
- **handle** - [IN] 通过Login函数返回的上下文句柄。
- **featureId** - [IN] 产品的特征项ID。
- **pCipherBuffer** - [IN] 数据缓存区地址，用于存储密文数据。
- **pPlainBuffer** - [OUT] 数据缓存区地址，用于存储明文数据。
- **bufferSize** - [IN] 数据长度，最大长度为256字节。
### 示例
```c
BIT_HANDLE handle = xx,
BIT_UINT32 featureId = xx;
BIT_UCHAR plainbuffer[256] = { 0 };
BIT_UCHAR cipherbuffer[256] ="xxxxxxxxx";
BIT_UINT32 dataLen = 16;
BIT_STATUS status = Bit_DecryptFeature(handle, featureId, cipherbuffer, plainbuffer, dataLen);
```
### Bit_ReadFeature
```c
BIT_STATUS Bit_ReadFeature(
BIT_HANDLE handle,
BIT_UINT32 featureId,
BIT_UINT32 *pFeatureValue);
```
读取特征项的数据内容，可用于“只读”和“读写”特征类型。
### 参数
- **handle** - [IN] 通过Login函数返回的上下文句柄。
- **featureId** - [IN] 产品的特征项ID。
- **pFeatureValue** - [OUT] 特征项数据缓存区地址，用于存储读出的数据。
### Bit_WriteFeature
```c
BIT_STATUS Bit_WriteFeature(
BIT_HANDLE handle,
BIT_UINT32 featureId,
BIT_UINT32 featureValue);
```
更新“读写”类型的特征项的数据内容。
### 参数
- **handle** - [IN] 通过Login函数返回的上下文句柄。
- **featureId** - [IN] 产品的特征项ID。
- **featureValue** - [IN] 特征项数据值。
## 配置项操作
### Bit_GetDataItem
```c
BIT_STATUS Bit_GetDataItem (
BIT_HANDLE handle,
BIT_PCSTR szDataItemName,
BIT_VOID *pDataItemValue,
BIT_UINT32 *pDataItemValueSize)
```
读取指定的配置项数据。
### 参数
- **handle** - [IN] 通过Login函数返回的上下文句柄。
- **szDataItemName** - [IN] 数据项名称，名称最大长度为128字节。
- **pDataItemValue** - [OUT] 数据缓存区地址，数据最大长度为1024字节。
- **pDataItemValueSize** - [IN/OUT] 数据项长度。
### Bit_SetDataItem
```c
BIT_STATUS Bit_SetDataItem (
BIT_HANDLE handle,
BIT_PCSTR szDataItemName,
BIT_VOID *pDataItemValue,
BIT_UINT32 dataItemValueSize)
```
创建或更新配置项。如果相同名称的配置项存在，则会更新其中的数据；否则将添加新的授权码配置项。
### 参数
- **handle** - [IN] 通过Login函数返回的上下文句柄。
- **szDataItemName** - [IN] 数据项名称，名称最大长度为128字节。
- **pDataItemValue** - [IN] 数据项数据缓存区地址，数据最大长度为1024字节。
- **dataItemValueSize** - [IN] 数据项长度。
### Bit_GetDataItemNum
```c
BIT_STATUS Bit_GetDataItemNum (
BIT_HANDLE handle,
BIT_UINT32 *pNum)
```
此函数用于获取可访问配置项的数量，一般用于配置项的枚举操作。
### 参数
- **handle** - [IN] 通过Login函数返回的上下文句柄。
- **pNum** - [OUT] 可访问的数据项总数，包括了所有可以访问到的产品、模版及授权码的数据项。
### Bit_GetDataItemName
```c
BIT_STATUS Bit_GetDataItemName (
BIT_HANDLE handle,
BIT_UINT32 index,
BIT_CHAR *pDataItemName,
BIT_UINT32 *pDataItemNameSize)
```
根据配置项索引获取其名称，一般用于配置项的枚举操作。
### 参数
- **handle** - [IN] 通过Login函数返回的上下文句柄。
- **index** - [IN] 数据项索引。
- **pDataItemName** - [OUT] 用于存储数据项名称的存储区地址。
- **pDataItemNameSize** - [IN/OUT] 数据项名称存储区大小。
### Bit_RemoveDataItem
```c
BIT_STATUS Bit_RemoveDataItem (
BIT_HANDLE handle,
BIT_PCSTR szDataItemName)
```
删除指定的配置项。该操作无法删除通过控制台设置的产品配置项或模版配置项。
### 参数
- **handle** - [IN] 通过Login函数返回的上下文句柄。
- **szDataItemName** - [IN] 数据项名称，名称最大长度为128字节。
## 信息获取
### Bit_GetSessionInfo
```c
BIT_STATUS Bit_GetSessionInfo (
BIT_HANDLE handle,
SESSION_TYPE type,
BIT_CHAR *pSessionInfo,
BIT_UINT32 *pSessionInfoSize)
```
获取当前会话信息，以字符串形式返回。根据获取的内容不同，返回结果可能是XML格式或非XML格式。返回数据中的日期项已根据客户端的本地时区进行调整。如果Login时未指定SN，返回串为当前系统所有可用SN的综合结果。
当函数返回BIT_ERR_BUFFER_SMALL时，pSessionInfoSize保存的是实际数据的大小。
### 参数
- **handle** - [IN] 通过Login函数返回的上下文句柄。
- **type** - [IN] 获取会话信息类型。
| 类型 | 说明 |
| ----------------------------- | ------------------------------------------------------------------------------------------------ |
| **XML_TYPE_SN_INFO** | 获取当前会话中授权码的授权信息，以XML形式返回。未做限制的授权项将不会返回 |
| **XML_TYPE_FEATURE_INFO** | 获取当前会话中授权码的特征项信息，以XML形式返回 |
| **XML_TYPE_SN_FEATURE_INFO** | 获取当前会话中授权码及授权码特征项的授权信息，以XML形式返回 **版本支持：**14.5.2及以上版本客户端库和集团服务支持返回MID信息（设置时才显示）、特征项的index（用于唯一标识） |
| **XML_TYPE_DATA_INFO** | 获取当前会话中授权码的配置项信息，以XML形式返回 |
| **BIT_SERVER_ADDRESS** | 授权服务器IP地址。单机授权不支持 |
| **BIT_SERVER_TIME** | 授权服务器系统时间。如果是本地授权，将返回本机系统时间 |
| **BIT_CONTROL_TYPE** | 授权类型。是以逗号分隔的以下几种类型的组合：Group（集团授权）, Smart（智能连接）, Float（可浮动）, Demo（演示授权）, USB（U盘授权）, Force（强制认证） |
| **BIT_VOLUME_NUMBER** | 允许使用的机器数量 |
| **BIT_START_DATE** | 授权开始日期，Unlimited表示无限制 |
| **BIT_END_DATE** | 授权结束日期，Unlimited表示无限制 |
| **BIT_EXPIRATION_DAYS** | 授权有效期，单位为天。有效期从激活时间算起，Unlimited表示无限制 |
| **BIT_USAGE_NUMBER** | 最大使用次数 |
| **BIT_CONSUMED_USAGE_NUMBER** | 对于设定最大使用次数的授权码，返回当前使用次数 |
| **BIT_ACTIVATE_DATE** | 授权码激活时间 |
| **BIT_USER_LIMIT** | 集团授权用户数，返回纯数字。对其它方式的授权返回0 |
| **BIT_LAST_UPDATE_DATE** | 最后与服务器连接时间 |
| **BIT_MAX_OFFLINE_MINUTES** | 强制认证最大离线时间（分钟），返回Unlimited表示无强制认证 |
| **BIT_SESSION_ID** | 获取当前会话的字符串sessionId |
| **BIT_SERVER_HB_STATUS** | 获取心跳状态，pSessionInfo无数据，状态通过函数返回值区分 |
| **BIT_TICKET_LIST_BIN** | 获取TICKET列表 |
- **pSessionInfo** - [OUT] 会话信息存储区地址。可以为NULL，此时仅用于获取存储区大小。
- **pSessionInfoSize** - [IN/OUT] 会话存储区大小。
### 示例
```c
BIT_UINT32 buffSize = 10240;
BIT_CHAR *pBuff = (BIT_CHAR *)malloc(buffSize);
if (pBuff == NULL) {
return;
}
memset(pBuff, 0, buffSize);
BIT_STATUS status = Bit_GetSessionInfo (handle,
XML_TYPE_SN_INFO,
pBuff,
& buffSize);
if (status == BIT_ERR_BUFFER_SMALL) {
free(pBuff);
pBuff = malloc(buffSize + 1);
memset(pBuff, 0, buffSize + 1);
status = Bit_GetSessionInfo (handle,
XML_TYPE_SN_INFO,
pBuff,
&buffSize);
}
if (status == BIT_SUCCESS) {
// pBuff 保存的是需要查找的数据
}
free(pBuff);
```
### Bit_GetInfo
```c
BIT_STATUS Bit_GetInfo (
BIT_PCSTR szSN,
BIT_UCHAR *pApplicationData,
INFO_TYPE type,
BIT_CHAR *pInfo,
BIT_UINT32 *pInfoSize)
```
获取本地授权信息。
如果要获取集团授权的信息，则szSN输入“`@bit://ip:port`”，会获取集团授权信息（仅支持type=BIT_INFO_SN）。
由于集团授权需要登录才能获取信息，而登录需要占用用户数，此方式提供了一个在不登录的情况下来获取集团授权信息。
### 参数
- **szSN** - [IN] 输入要检索的SN，如果为NULL，表示获取所有SN。
- **pApplicationData** - [IN] 产品识别码。记录在接口定义文件中，与产品一一对应。
- **type** - [IN] 类型。
| **类型** | **说明** |
| --------------------------- | --------------------------------------- |
| **BIT_INFO_SERVER_ADDRESS** | 获取局域网内的集团授权服务器地址列表 |
| **BIT_INFO_SN** | 获取本机已激活的授权码列表 |
| **BIT_INFO_SN_FEATURE** | 获取本机已激活授权码的特征项列表 **版本支持：**集团授权支持返回MID信息 |
| **BIT_INFO_SN_LICENSE** | 获取本机已激活授权码的授权信息 |
| **BIT_INFO_UPDATE_ERROR** | 获取指定授权码的升级错误详细信息。是否存在详细信息由授权码类型及错误类型决定 |
| **BIT_INFO_CONFIG** | 获取当前产品的配置文件信息 |
| **BIT_INFO_TOKEN_LIST** | 获取当前机器上可用的BIT-ID列表信息 |
- **pInfo** - [OUT] 数据缓存区地址。
- **pInfoSize** - [IN/OUT] 输入时是数据缓存区大小，输出时是实际数据的长度。
### Bit_GetServerInfo
```c
BIT_STATUS Bit_GetServerInfo(
BIT_PCSTR szURL,
BIT_PCSTR szSN,
BIT_PCSTR xmlScope,
BIT_UCHAR *pApplicationData,
BIT_INFO_EX_TYPE type,
BIT_CHAR *pServerInfo,
BIT_UINT32 *pServerInfoSize);
```
获取集团服务的License信息，数据以XML格式返回。调用此函数前客户端不需要执行登录操作。
### 参数
- szURL - [IN] 指定集团授权服务器地址，包括端口。
- szSN - [IN] 授权码（SN）字符串。
- xmlScope- [IN] 查询指定特征项的信息，以XML格式传入。14.6.0及以上版本支持传入groupName指定查询分组，具体使用规则参见下文xmlScope使用说明。
- pApplicationData - [IN] 产品识别码。记录在接口定义文件中，与产品一一对应。
- type- [IN] 获取信息类型。
| **类型** | **说明** |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **BIT_SERVER_INFO_SN** | 获取集团服务的授权码列表 |
| **BIT_SERVER_INFO_SN_FEATURE** | 获取集团服务的授权码的特征项列表 **版本支持：**14.5.2及以上版本客户端库和集团服务支持返回MID信息（设置时才显示）、特征项的index（用于唯一标识） |
| **BIT_SERVER_INFO_SN_LICENSE** | 获取集团服务的授权码的授权信息 |
| **BIT_SERVER_INFO_FEATURE_LICENSE** | 获取集团服务的特征项的授权信息 **版本支持：**14.5.2及以上版本客户端库和集团服务支持返回MID信息（设置时才显示）、特征项的index（用于唯一标识） |
| **BIT_SERVER_INFO_SN_USERS** | 获取集团服务被占用的SN的用户信息 **版本支持：**14.6.0及以上版本支持通过xmlScope传入groupName指定查询分组，需配合14.6.0及以上版本集团服务使用 |
| **BIT_SERVER_INFO_FEATURE_USERS** | 获取集团服务被占用的feature的用户信息 **版本支持：**14.6.0及以上版本支持通过xmlScope传入groupName指定查询分组，需配合14.6.0及以上版本集团服务使用 |
| **BIT_SERVER_INFO_FEATURE_USERS_EX** | 获取集团服务被占用的feature的用户信息 **版本支持：**- 14.5.2及以上版本：新增类型，在BIT_SERVER_INFO_FEATURE_USERS基础上，额外多返回属性，包含id，version，index（值为name名称）- 14.6.0及以上版本：支持通过xmlScope传入groupName指定查询分组，需配合14.6.0及以上版本集团服务使用 |
- pServiceLicenseInfo - [OUT] 用于存储返回XML信息数据的存储区地址。
- pServiceLicenseInfoSize - [IN/OUT] 输入的存储区长度。
### xmlScope使用说明
支持指定特征项查询和指定分组查询两种方式，暂不支持同时指定特征项和分组信息。
1. 指定特征项（feature）查询
适用于所有BIT_INFO_EX_TYPE类型，通过id、name、version限定待查询的特征项。
```xml
<features>
<feature id="xxxx" name="xxxx" version="xxxx"/> # xxxx处替换为实际特征项参数
<feature id="xxxx" name="xxxx" version="xxxx"/> # 允许设置多个
……
</features>
```
1. 指定分组（group）查询
仅支持BIT_SERVER_INFO_SN_USERS、BIT_SERVER_INFO_FEATURE_USERS、BIT_SERVER_INFO_FEATURE_USERS_EX三种类型，通过name限定待查询的分组。
```c
<groups>
<group name="xxxx"/> # xxxx处替换为实际分组名称
<group name="xxxx"/> # 允许设置多个
……
</groups>
```
> 说明：通过Bit_SetCustomInfo的CUSTOM_GROUP_NAME(0xA)设置分组。
### 返回XML数据说明
传入分组名称，仅返回当前分组内的用户信息；不传入分组名称，默认返回所有用户信息。如果客户端调用Bit_SetCustomInfo指定group后，返回的XML数据中，userInfo节点会新增groupName字段。
XML返回示例：
```c
<?xml version="1.0" encoding="UTF-8"?>
<serverInfo timeZone="+08:00">
<userInfo>
<sn>CLMDMJDR********</sn>
<userName>98001</userName>
<machineName>bit</machineName>
<ip>127.0.0.1</ip>
<loginTime>2026-02-26 01:49:28</loginTime>
<groupName>bit</groupName>
</userInfo>
</serverInfo>
```
### Bit_GetVersion
```c
BIT_STATUS Bit_GetVersion (
BIT_UINT32 *pVersion)
```
获取客户端安全库版本号。
### 参数
- **pVersion** - [OUT] 客户端安全库版本号。
### Bit_GetNextHandle
```c
BIT_STATUS Bit_GetNextHandle(
BIT_HANDLE handle,
BIT_HANDLE *pNextHandle)
```
用来遍历当前进程内的handle。
### 参数
- **handle** – [IN] 当前handle。如果传NULL，pNextHandle返回第一个handle。
- **pNextHandle** – [OUT] 返回handle指向的下一个handle，如果返回为NULL，则表示已经到了末尾。
### 示例
```c
BIT_HANDLE nextHandle = NULL;
while (Bit_GetNextHandle(nextHandle , &nextHandle) == BIT_SUCCESS && nextHandle != NULL) {
// 使用nextHandle处理业务逻辑
}
```
### Bit_TestBitService
```c
BIT_STATUS Bit_TestBitService (
BIT_PCSTR szURL,
BIT_PCSTR szSN,
BIT_UINT32 featureId,
BIT_UCHAR *pApplicationData)
```
测试集团授权的特征项是否可用，不会占用授权码或特征项的用户数。
### 参数
- **szURL** - [IN] 自定义授权服务器地址，需包括端口。如未使用自定义授权服务器则为NULL。
- **szSN** - [IN] 授权码（SN）字符串。如果为空（空字符串""或NULL）则尝试寻找所有当前本机可用的SN。
- **featureId** - [IN] 登录授权所需要包含的特征项ID。
- **pApplicationData** - [IN] 产品识别码。记录在接口定义文件中，与产品一一对应。
> **注意：szSN和featureId为二选一互斥关系**，需遵循以下规则
>
> - 指定授权码：当szSN不为NULL或空字符串（""）时，featureId必须设为0。
> - 指定特征项：当featureId不为0时，szSN必须设为NULL或空字符串（""）。
> - 特殊情况：允许szSN为NULL或空字符串，且featureId为0。
### Bit_GetProductPath
```c
BIT_STATUS Bit_GetProductPath(
BIT_UCHAR *pApplicationData,
BIT_CHAR *pPath,
BIT_UINT32 lenPath);
```
获取授权存储目录。
### 参数
- **pApplicationData** - [IN] 产品识别码。记录在接口定义文件中，与产品一一对应。
- **pPath** - [OUT] 授权存储目录。
- **lenPath** - [IN] 指定授权目录pPath数据长度。建议值：Windows：PATH_MAX (260) Linux/Unix：PATH_MAX (4096)。
### Bit_GetLastError
```c
BIT_STATUS Bit_GetLastError();
```
获取上一个API调用返回的错误码。
### 参数
无
## 属性设置
### Bit_SetAttr
```c
BIT_STATUS Bit_SetAttr (
BIT_HANDLE handle,
BIT_UINT32 type,
BIT_VOID *pValue)
```
设置全局配置或当前会话的配置。
### 参数
- **handle** - [IN] 通过Login函数返回的上下文句柄。如果传NULL，表示设置全局，不为NULL表示设置该会话。
- **type** - [IN] 类型。
| **类型** | **值** | **说明** |
| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **ATTR_HB_STOPED_CALLBACK（0x1）** | void (*T_HbStopedCallback)(BIT_HANDLE, void* pData) | 心跳停止回调函数 心跳停止后会回调该函数，可检测与授权服务的连接状态 **注意事项：**handle不能为NULL |
| **ATTR_WAIT_TIMEOUT(0x2)** | BIT_UINT32 * | 队列等待超时时间 最小16秒，最大15天，默认0表示无限等待 **注意事项：**handle可为NULL，也可不为NULL |
| **ATTR_RETRY_COUNT(0x3)** | BIT_UINT32 * | 心跳连接重试次数 当心跳时候，总的重试次数 **取值说明：** 0：表示无限重试，直到客户端超时或授权失效，才会停止，默认是0 -1：表示无限重试，无论客户端是否超时或授权失效，都会重试 **注意事项：**handle可为NULL，也可不为NULL |
| **ATTR_RETRY_INTERVAL(0x4)** | BIT_UINT32 * | 心跳连接重试间隔 心跳失败后下次重试的间隔 最小10秒，最大4小时，默认10秒 **注意事项：**handle可为NULL，也可不为NULL |
| **ATTR_CONNECT_TIMEOUT(0x5)** | BIT_UINT32 * | 建立连接超时时间 最小1秒，最大32秒，默认32秒 **注意事项：**handle可为NULL，也可不为NULL |
| **ATTR_CONNECT_RETRY_COUNT(0x6)** | BIT_UINT32 * | 连接重试次数 最小0次，最大10次，默认3次 **注意事项：**handle可为NULL，也可不为NULL |
| **ATTR_HB_INTERVAL(0x8)** | BIT_UINT32 * | 心跳间隔 最小30秒，默认由服务端控制 **注意事项：**handle可为NULL，也可不为NULL |
| **ATTR_HB_AUTO_ENABLE(0x9)** | BIT_UINT32 * | 是否启动自动心跳 **注意事项：**handle可为NULL，也可不为NULL |
| **ATTR_HB_TIMEOUT(0x10)** | BIT_UINT32 * | 心跳周期（超过则被踢出） 集团服务端也可以设置心跳周期，该周期会覆盖服务端的设置 最小60秒，最大30天，默认由服务端控制 **注意事项：**handle可为NULL，也可不为NULL |
| **ATTR_HB_STOPED_CALLBACK_DATA(0x12)** | void * | 心跳停止回调函数自定义数据 触发心跳停止回调时，会将该值传递到ATTR_HB_STOPED_CALLBACK回调函数的最后一个参数 **注意事项：**handle不能为NULL |
| **ATTR_HB_STOPED_CALLBACK_EX(0x13)** | void (*T_HbStopedCallbackEx)(BIT_HANDLE, BIT_TICKET, BIT_STATUS, void* pData); | 特征项的心跳停止回调函数 **参数说明：** - BIT_HANDLE handle：login接口返回的handle- BIT_TICKET ticket：query接口返回的ticket- BIT_STATUS status：心跳停止返回的错误码- void *pData：开发商自定义数据，需通过ATTR_HB_STOPED_CALLBACK_EX_DATA传入**注意事项：**handle不能为NULL |
| **ATTR_HB_STOPED_CALLBACK_EX_DATA(0x14)** | void * | 特征项的心跳停止回调函数自定义数据 触发特征项的心跳停止回调时，会将该值传递到ATTR_HB_STOPED_CALLBACK_EX回调函数的最后一个参数 **注意事项：**handle不能为NULL |
| **ATTR_HB_RETRY_CALLBACK_EX(0x15)** | void (*T_HbRetryFailedCallbackEx)(BIT_HANDLE, BIT_TICKET, BIT_STATUS, void* pData); | 心跳重试回调函数 **参数说明：** - BIT_HANDLE handle：login接口返回的handle- BIT_TICKET ticket：query接口返回的ticket- BIT_STATUS status：心跳重试返回的错误码- void *pData：开发商自定义数据，需通过ATTR_HB_RETRY_CALLBACK_EX_DATA传入**注意事项：**handle不能为NULL |
| **ATTR_HB_RETRY_CALLBACK_EX_DATA(0x16)** | void * | 心跳重试回调函数自定义数据 触发心跳重试回调时，会将该值传递到ATTR_HB_RETRY_CALLBACK_EX回调函数的最后一个参数 **注意事项：**handle不能为NULL |
| **ATTR_SET_LOGIN_MODE(0x17)** | BIT_UINT32 * | 设置Login的mode值 **注意事项：**handle不能为NULL |
| **ATTR_UNSET_LOGIN_MODE(0x18)** | BIT_UINT32 * | 取消Login的mode值 **注意事项：**handle不能为NULL |
| **ATTR_DISABLE_ENV(0x19)** | BIT_BOOL * | 禁用环境变量 传1表示禁用，设置禁用后客户端库将不再读取环境变量 **注意事项：**handle可为NULL，也可不为NULL |
| **ATTR_REQUEST_TIMEOUT(0x1A)** | BIT_UINT32 * | 自定义receiveTimeout 最小16秒，最大64秒，默认32秒 **注意事项：**handle可为NULL，也可不为NULL |
| **ATTR_HB_RETRY_FAILED_CALLBACK(0x7)** | void (*T_HbRetryFailedCallback)(BIT_HANDLE, BIT_STATUS, void* pData) | 心跳重试失败回调函数 **参数说明：** - BIT_HANDLE handle：login接口返回的handle- BIT_STATUS status：心跳失败返回的错误码- void *pData：开发商自定义数据，需通过ATTR_HB_RETRY_FAILED_CALLBACK_DATA传入**注意事项：**handle不能为NULL |
| **ATTR_HB_RETRY_FAILED_CALLBACK_DATA(0x11)** | void * | 心跳重试失败回调函数自定义数据 触发心跳失败回调时，会将该值传递到ATTR_HB_RETRY_FAILED_CALLBACK回调函数的最后一个参数 **注意事项：**handle不能为NULL |
| **ATTR_HB_RETRY_FAILED_CALLBACK_EX2(0x1B)** | void (*T_HbRetryFailedCallback)(BIT_HANDLE, BIT_TICKET, BIT_STATUS, BIT_UINT32, BIT_UINT32, BIT_UINT32* pData)) | 心跳重试失败回调函数（Ex2） **参数说明：** - BIT_HANDLE handle：login接口返回的handle- BIT_TICKET ticket：query接口返回的ticket- BIT_STATUS status：心跳失败返回的错误码- BIT_UINT32 currentNumber：当前回调次数- BIT_UINT32 maxNumber：最大回调次数- BIT_UINT32 interval：回调间隔（单位：秒）- void *pData：开发商自定义数据，需通过ATTR_HB_RETRY_FAILED_CALLBACK_EX2_DATA传入**注意事项：**handle不能为NULL |
| **ATTR_HB_RETRY_FAILED_CALLBACK_EX2_DATA(0x1C)** | void * | 心跳重试失败回调自定义数据（Ex2） 触发QueryFeatureEx2的心跳失败回调时，会将该值传递到ATTR_HB_RETRY_FAILED_CALLBACK_EX2回调函数的最后一个参数 **注意事项：**handle不能为NULL |
| **ATTR_HB_RETRY_SUCCESS_CALLBACK(0x1D)** | void (*T_HbRetrySuccessCallbackEx2)(BIT_HANDLE, BIT_TICKET, BIT_UINT32, BIT_UINT32, BIT_UINT32 *pDate) | 心跳重试成功回调函数 **参数说明：** - BIT_HANDLE handle：login接口返回的handle- BIT_TICKET ticket：query接口返回的ticket- BIT_UINT32 currentNumber：当前回调次数- BIT_UINT32 maxNumber：最大回调次数- BIT_UINT32 interval：回调间隔（单位：秒）- void *pData：开发商自定义数据，需通过ATTR_HB_RETRY_SUCCESS_CALLBACK_DATA传入**注意事项：**handle不能为NULL |
| **ATTR_HB_RETRY_SUCCESS_CALLBACK_DATA(0x1E)** | void * | 心跳重试成功回调自定义数据 触发心跳成功回调时，会将该值传递到ATTR_HB_RETRY_SUCCESS_CALLBACK回调函数的最后一个参数 **注意事项：**handle不能为NULL |
| **ATTR_QUEUE_WAIT_CALLBACK(0x21)** | void (*QueueWaitCallback)(BIT_HANDLE, BIT_TICKET, BIT_STATUS, BIT_UINT32, BIT_UINT32 *pUserData) | 排队回调函数 **生效前提（满足其一即可）：** - Bit_QueryFeatureEx2接口已设置BIT_QUERY_WAIT（等待模式）- 环境变量BITANSWER_MODE已配置为wait（排队等待模式）**参数说明：** - BIT_HANDLE handle：login接口返回的handle- BIT_TICKET ticket：query接口返回的ticket- BIT_STATUS status：BIT_SUCCESS（表示排队中），其他（表示排队失败）- BIT_UINT32 queueLength：前面排队长度- BIT_UINT32 waitSecond：预计等待总秒数（不足1秒部分会被舍去）- void *pUserData：开发商自定义数据，需通过ATTR_QUEUE_WAIT_CALLBACK_DATA传入**注意事项：**handle不能为NULL **版本支持：**14.5.2及以上版本新增类型，需配合14.5.2及以上版本的集团服务和客户端库使用 |
| **ATTR_QUEUE_WAIT_CALLBACK_DATA(0x22)** | void * | 排队回调自定义数据 触发QueryFeatureEx2的排队回调时，会将该值传递到ATTR_QUEUE_WAIT_CALLBACK回调函数的最后一个参数 **注意事项：**handle不能为NULL |
| **ATTR_ENABLE_DIAGS_LOG(0x1F)** | BIT_UINT32 * | 控制诊断log的生成 **取值说明：**- 0：表示禁用（默认，禁用后环境变量不生效）- 1：表示启动**注意事项：**handle必须为NULL |
| **ATTR_HB_DEFAULT_STOPED_CALLBACK(0x20)** | BIT_BOOL * | 控制心跳停止程序自动退出功能 **取值说明：**- 0：表示禁用（默认）- 1：表示启动，若经过最大次重试次数后仍未重新建立连接，应用程序会默认终止运行，并输出错误信息：“许可证丢失，无法重新连接”（UNIX系统输出至stderr，Windows系统弹出对话框）**注意事项：**- 如果注册了ATTR_HB_STOPED_CALLBACK或ATTR_HB_STOPED_CALLBACK_EX默认退出行为将不再生效- handle不能为NULL**版本支持：**14.5.0及以上版本新增类型 |
| **ATTR_LOGIN_URL_SCOPE（0x23）** | BIT_UINT32 * | 控制Login连接的服务器类型 **取值说明：**- ATTR_LOGIN_URL_UNKNOW (0x0) - 默认行为，加载配置中所有类型的服务器- ATTR_LOGIN_URL_WS (0x1) - 表示仅连接ws类型服务（云授权服务器）- ATTR_LOGIN_URL_BIT (0x2) - 表示仅连接bit类型服务（集团授权服务器）**注意事项：**- 调用SetAttr接口时，第一个参数handle必须传入NULL，表示该配置全局生效；若传入非NULL值，接口会返回错误码259- handle必须为NULL**示例：**- 场景：环境变量中配置了混合类型的服务器地址：`bit://127.0.0.1:8273,ws:bitanswer.cn`，需仅连接bit类型服务器- API调用：SetAttr(NULL, ATTR_LOGIN_URL_SCOPE（0x23）, 2)- 执行结果：程序仅加载并连接`bit://127.0.0.1:8273`（bit类型服务器），忽略ws类型的`ws:bitanswer.cn`**版本支持：**14.5.4及以上版本新增类型 |
- **pValue** - [IN] 不同类型，对应了不同的值。
### 示例
```c
// 设置队列等待超时为20秒
BIT_UINT32 value = 20;
BIT_STATUS status = Bit_SetAttr (handle, ATTR_WAIT_TIMEOUT, &value);
if (status == BIT_SUCCESS) {
// 设置成功
}
```
### Bit_SetProxy
```c
BIT_STATUS Bit_SetProxy (
BIT_UCHAR *pApplicationData,
BIT_PCSTR szHostName,
BIT_UINT32 nPort,
BIT_PCSTR szUserID,
BIT_PCSTR szPassword)
```
设置代理服务的地址和端口。
### 参数
- **pApplicationData** - [IN] 产品识别码。记录在接口定义文件中，与产品一一对应。
- **szHostName** - [IN] 代理服务所在机器的IP地址。
> 说明：
>
> - 14.3.0及以上版本，将该参数扩展为支持`Type:HostName`格式，其中Type表示服务器类型，可取值为ws或bit，ws表示云授权服务器，bit表示集团授权服务器。
> - 为保持向后兼容，若不指定`Type://前缀`，则默认视为ws类型。
- **nPort** - [IN] 代理服务开启的通讯端口。
- **szUserID** - [IN] 代理服务所在机器的用户名。
- **szPassword** - [IN] 代理服务所在机器的密码。
### Bit_SetCustomInfo
```c
BIT_STATUS Bit_SetCustomInfo (
BIT_UINT32 infoId,
BIT_VOID *pInfoData,
BIT_UINT32 infoDataSize)
```
设置客户端运行自定义信息，需要在程序的最开始调用。
### 参数
- **infoId** - [IN] 自定义信息类型。
| **类型** | **值** | **说明** |
| --------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **CUSTOM_CLIENT_ID（0x1）** | 字符串 | 自定义终端标识，配置后该自定义标识会发送给服务器并用于今后的机器指纹匹配 **注意：**必须同时将CUSTOM_OPTION_CLOUD_CLIENTID选项设置为启用状态，此配置才能生效 |
| **CUSTOM_ACCOUNT_LOCAL(0x2)** | 字符串 | 自定义客户端用户帐号，用于集团服务标识客户端用户 |
| **CUSTOM_COMMENT(0x3)** | 字符串 | 自定义客户端登录注释，用于集团服务管理员获取用户登录请求信息 |
| **CUSTOM_OPTION(0x4)** | BIT_UINT32 | 按位进行操作 - CUSTOM_OPTION_SD1_FIRST (0x1) - 仅限Android选项，只检查第一张SD卡- - CUSTOM_OPTION_HIDE_FOLDER (0x2) - 隐藏默认的BitAnswer文件夹- CUSTOM_OPTION_SOAP_USERNAME (0x4) - 机器用户信息添加到soap头中- CUSTOM_OPTION_CONFINED_LINK (0x8) - 取消连接次数限制(1800)- CUSTOM_OPTION_BINARY_NAME(0x10) – 客户向集团服务发送进程名- CUSTOM_OPTION_DOCKER_INFO(0x40) – 客户端向服务端发送设备运行于Docker环境时的标识信息- CUSTOM_OPTION_CLOUD_CLIENTID(0x20) – 用于启用CUSTOM_CLIENT_ID（自定义终端标识）功能，开启后，系统会将已设置的CUSTOM_CLIENT_ID作为该设备的唯一标识，用于今后的机器指纹匹配与管理（需配合14.5.0及以上版本的集团服务和客户端库使用）**示例：** 既要取消连接次数限制，又要隐藏BitAnswer目录，则传入：(CUSTOM_OPTION_HIDE_FOLDER |
| **CUSTOM_PRODUCT_CODE(0x6)** | 字符串 | 自定义授权目录名称 |
| **CUSTOM_ACCOUNT_DEVELOPER(0x7)** | 字符串 | 自定义登录帐号，用于帐号授权 （既使用account登录，又设置了此选项，则直接忽略） |
| **CUSTOM_VENDOR_CODE(0x8)** | 字符串 | 自定义开发商信息目前仅用于自定义环境变量名称 |
| **CUSTOM_HTTP_HEADER(0x9)** | 字符串 类似于“`auth:xxxx`”，普遍用于自定义认证信息 | 自定义HTTP头，所有联网的请求都会自带这个请求头 |
| **CUSTOM_GROUP_NAME(0xA)** | 字符串 | 设置自定义分组名 当开发商需要按照自定义的分组扣点（比如：部门，角色，窗口名等），可以设置此选项，并结合Bit_Login的LOGIN_MODE设置扣点方式 |
- **pInfoData** - [IN] 自定义信息的存储地址。
- **infoDataSize** - [IN] 自定义信息长度。针对CUSTOM_OPTION类型，该参数应为BIT_UINT32类型大小。
### 示例
```c
// 设置字符串类型
// 自定义终端标识
BIT_PCSTR clientID = "Machine-123";
BIT_STATUS status = Bit_ SetCustomInfo (CUSTOM_CLIENT_ID, clientID, strlen(clientID));
if (status == BIT_SUCCESS) {
// 设置成功
}
// 设置BIT_UINT32类型
// 机器用户信息添加到soap头中
BIT_UINT32 optSoapUserName = 4;
BIT_STATUS status = Bit_ SetCustomInfo (CUSTOM_OPTION, & optSoapUserName, sizeof(optSoapUserName));
if (status == BIT_SUCCESS) {
// 设置成功
}
```
### Bit_SetRootPath
```c
BIT_STATUS Bit_SetRootPath (
BIT_PCSTR szPath)
```
设置授权文件的存储路径。
### 参数
- **szPath** - [IN] 数据缓存区地址，用于存储授权文件的路径。
### Bit_SetLocalServer
```c
BIT_STATUS Bit_SetLocalServer (
BIT_UCHAR *pApplicationData,
BIT_PCSTR szHostName,
BIT_UINT32 nPort,
BIT_UINT32 nTimeoutSecondes)
```
设置集团服务的地址和端口。
### 参数
- **pApplicationData** - [IN] 产品识别码。记录在接口定义文件中，与产品一一对应。
- **szHostName** - [IN] 集团服务所安装机器的IP地址。
- **nPort** - [IN] 客户端应用程序的通讯端口，默认为8273。
- **nTimeoutSecondes** - [IN] 客户端超时秒数。
## 借出操作
### Bit_GetBorrowRequest
```c
BIT_STATUS Bit_GetBorrowRequest(
BIT_PCSTR szSN,
BIT_UCHAR *pApplicationData,
BIT_UINT32 nDurationDays,
BIT_CHAR *pRequestInfo,
BIT_UINT32 *pRequestInfoSize)
```
获取借出请求串，用来离线借出。
### 参数
- **szSN** - [IN] 指定要借出的SN，如果为NULL，找满足条件的第一个SN。
- **pApplicationData** - [IN] 产品识别码，在Bitanswer SDK头文件里。
- **nDurationDays** - [IN] 借出时间。100年代表永久借出（分发），0表示产生归还串。
- **pRequestInfo** - [OUT] 借出请求串缓存区地址。
- **pRequestInfoSize** - [IN/OUT] 输入的是缓存区大小，输出的是示例数据的大小。
### Bit_GetBorrowFeatureRequest
```c
BIT_STATUS Bit_GetBorrowFeatureRequest(
BIT_PCSTR pReserve,
BIT_UCHAR *pApplicationData,
BIT_UINT32 nDurationDays,
BIT_PCSTR pBorrowScope,
BIT_CHAR *pRequestInfo,
BIT_UINT32 *pRequestInfoSize)
```
获取借出请求串，该接口支持指定特征项借出。
### 参数
- **pReserve** - [IN] 保留，必须是NULL。
- **pApplicationData** - [IN] 产品识别码，在Bitanswer SDK头文件里。
- **nDurationDays** - [IN] 借出时间。
- **pBorrowScope** - [IN] xml结构。
- **pRequestInfo** - [OUT] 借出请求串缓存区地址。
- **pRequestInfoSize** - [IN/OUT] 输入的是缓存区大小，输出的是示例数据的大小。
### Scope示例
```xml
<features>
<feature id='' days=''/>
<feature id='' days=''/>
…
</features>
```
### Bit_CheckOutSn / Bit_CheckOutSnEx
```c
BIT_STATUS Bit_CheckOutSn(
BIT_PCSTR szURL,
BIT_UINT32 featureId,
BIT_UCHAR *pApplicationData,
BIT_UINT32 nDurationDays);
BIT_STATUS Bit_CheckOutSnEx(
BIT_PCSTR szURL,
BIT_UINT32 featureId,
BIT_PCSTR pScope,
BIT_UCHAR *pApplicationData,
BIT_UINT32 nDurationDays);
```
从授权服务器在线借出一个完整的授权码，以允许客户端服务器单独使用。被借出的授权码必须具有可借出属性，并在客户端成功借出后减少一个可用用户数。被借出的用户数在到期后将自动返还给服务器。
### 参数
- **szURL** - [IN] 集团授权服务器地址，包括端口。如输入NULL，则使用配置文件地址；如输入 * 号，则使用广播查找地址。
- **featured** - [IN] 指定借出授权码需要包含的特征项ID，为0则寻找第一个可借出授权码。
- **pApplicationData** - [IN] 产品识别码。记录在接口定义文件中，与产品一一对应。
- **pScope** - [IN] xml结构，允许传NULL。
- **nDurationDays** - [IN] 借出时间，单位为天。借出时间不能超过被借出集团授权的强制认证周期或有效期。
### Scope示例
```xml
<scope>
<type>ws</type>
<sn>xxx</sn>
<featureVersion>xxx</featureVersion>
</scope>
<!--
说明：
type：借出类型。目前仅支持ws，表示从外网借出（针对云授权和集团授权）
featureVersion：借出的特征项版本
sn：指定借出的SN
-->
```
### Bit_CheckOut
```c
BIT_STATUS Bit_CheckOut(
BIT_PCSTR szURL,
BIT_PCSTR pScope,
BIT_PCSTR pFeatureList,
BIT_UCHAR *pApplicationData,
BIT_UINT32 nDurationDays)
```
从授权服务器在线借出授权码或者特征项。
### 参数
- **szURL** 集团授权服务器地址，包括端口。如输入NULL，则从本地配置文件或者环境变量读取服务地址。
- **pScope** xml结构，允许传NULL。
```xml
<scope>
<type>ws</type>
<sn>xxx</sn>
</scope>
<!--
说明：
type：借出类型。目前仅支持ws，表示从外网借出（针对云授权和集团授权）
sn：指定借出的SN
-->
```
- **pFeatureList** xml结构，指定借出的特征项列表，如果不传则借出整个SN。
```xml
<features>
<feature id='1' ver='2.0' days='10' required='0|1'/>
<!-- id：特征项编号，ver：特征项版本，days：借出时间, required：0可选，1必选（默认是1） -->
<feature id='10'/>
</features>
```
当feature指定了借出时间，则会覆盖nDurationDays该时间，没有指定，则借出nDurationDays天。
借出feature时，如果指定了版本，则直接大于等于借出版本的特征项，只借一个，如果没有指定版本，则该特征项的所有版本都借出一个。
- **pApplicationData** 产品识别码。记录在接口定义文件中，与产品一一对应。
- **nDurationDays** 借出时间，单位为天，最大不超过100年。
```c
// 借出特征项1和特征项2，各借10天
BIT_STATUS status = Bit_CheckOut(
"bit://127.0.0.1:8273",
NULL,
"<features><feature id=\"1\"/><feature id=\"2\"/></features>",
application_data,
10);
if (status == BIT_SUCCESS) {
// 借出成功
}
// 借出特征项1(5天) 和 特征项2（2天）
BIT_STATUS status = Bit_CheckOut(
"bit://127.0.0.1:8273",
NULL,
"<features><feature id=\"1\" days=\"5\"/><feature id=\"2\" days=\"2\"/></features>",
application_data,
5);
if (status == BIT_SUCCESS) {
// 借出成功
}
```
### Bit_CheckOutFeatures
```c
BIT_STATUS Bit_CheckOutFeatures(
BIT_PCSTR szURL,
BIT_UCHAR *pApplicationData,
BIT_UINT32 *pFeatureList,
BIT_UINT32 nFeatureInList,
BIT_UINT32 nDurationDays);
```
从集团授权服务器借出一组特征项，这些特征项必须包含在同一个授权码中。被借出的集团授权码必须具有可借出属性，并在客户端成功借出后减少一个可用用户数。被借出的用户数在到期后将自动返还给集团服务器。
### 参数
- **szURL** - [IN] 集团授权服务器地址，包括端口。如输入NULL，则使用配置文件地址；如输入 * 号，则使用广播查找地址。
- **pApplicationData** - [IN] 产品识别码。记录在接口定义文件中，与产品一一对应。
- **pFeatureList** - [IN] 要借出的特征项列表。
- **nFeatureInList** - [IN] 要借出的特征项数量。
- **nDurationDays** - [IN] 借出时间，单位为天，最大不超过100年。
### 示例
```c
// 借出特征项1和特征项2，借3天
BIT_UINT32 borrowFeature[2] = { 0 };
borrowFeature[0] = 1;
borrowFeature[1] = 2;
BIT_STATUS status = Bit_CheckOutFeatures("bit://127.0.0.1:8273",
application_data,
borrowFeature,
2,
3);
if (status == BIT_SUCCESS) {
// 借出成功
} else {
// 借出失败
}
```
### Bit_CheckIn
```c
BIT_STATUS Bit_CheckIn(
BIT_PCSTR szURL,
BIT_UINT32 featureId,
BIT_UCHAR *pApplicationData)
```
提前返还从集团授权服务器借出的授权。要提前返还授权，该授权码必须具有允许提前返还属性。
### 参数
- **szURL** - [IN] 集团授权服务器地址，包括端口。如输入NULL，则使用配置文件地址；如输入 * 号，则使用广播查找地址。
- **featureId** - [IN] 指定要返还授权码需要包含的特征项ID，为0则寻找第一个可返还授权码。
- **pApplicationData** - [IN] 产品识别码。记录在接口定义文件中，与产品一一对应。
### Bit_CheckInEx
```c
BIT_STATUS Bit_CheckInEx(
BIT_PCSTR szURL,
BIT_UINT32 featureId,
BIT_PCSTR szScope,
BIT_UCHAR *pApplicationData)
```
提前返还从授权服务器借出的授权。要提前返还授权，该授权码必须具有允许提前返还属性。
### 参数
- **szURL** - [IN] 集团授权服务器地址，包括端口。如输入NULL，则使用配置文件地址；如输入 * 号，则使用广播查找地址。
- **featureId** - [IN] 指定要返还授权码需要包含的特征项ID，为0则寻找第一个可返还授权码。
- **xmlScope** - [IN] xml结构，允许传NULL。
```xml
<scope>
<type>ws</type> <!-- type：归还类型，ws表示归还到云授权服务，默认是归还到集团授权服务 -->
</scope>
```
用于指定借出的参数，格式：wsxxxx，type设定为ws时表示从云授权服务器借出和归还。
- **pApplicationData** - [IN] 产品识别码。记录在接口定义文件中，与产品一一对应。
### Bit_ApplyBorrowInfo
```c
BIT_STATUS Bit_ApplyBorrowInfo(
BIT_UCHAR *pApplicationData,
BIT_PCSTR pBorrowInfo)
```
客户端应用离线借出串，Bit_ApplyUpdateInfo可以兼容该接口。
### 参数
- **pApplicationData** - [IN] 产品识别码。记录在接口定义文件中，与产品一一对应。
- **pBorrowInfo** - [IN] 借出请求串。
Reference in New Issue View Git Blame Copy Permalink