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

feat(sdk): AuthConfigs, JSON Schema, examples, and release checksum CI

Browse Source 
Add craftlabs-auth-config.schema.json, Java AuthConfigs model with tests,
example configs aligned to BP-10, C/Java/auth-config documentation,
native header notes, RELEASING guide, and workflow to verify SDK
artifact checksums on release tags.

Made-with: Cursor
This commit is contained in:
huangping
2026-04-06 21:05:12 +08:00
parent 65eb983035
commit f94f03bcc2
31 changed files with 1219 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/auth-config.md
+35
View File
@@ -0,0 +1,35 @@
# `initialize(config_json)` 配置说明
`AuthProvider.initialize(String)` 与 C API `auth_initialize(const char* config_json)` 共用同一 JSON 语义，版本由 **`schemaVersion: 1`** 锁定。
## 规范与示例
| 资源 | 路径 |
|------|------|
| JSON Schema | `schemas/craftlabs-auth-config.schema.json` |
| 码头 / 集团拓扑示例 | `examples/config/wharf.bitanswer.json` |
| 学校 / 边设备示例 | `examples/config/school.bitanswer.json` |
| 流动人口 / 项目示例 | `examples/config/floating.bitanswer.json` |
| 学校 / 自研 HTTP 示例 | `examples/config/school.selfhosted.json` |
## Java 解析与校验
```java
import cn.craftlabs.auth.config.AuthConfig;
import cn.craftlabs.auth.config.AuthConfigException;
import cn.craftlabs.auth.config.AuthConfigs;
AuthConfig cfg = AuthConfigs.parse(jsonString);
// 再交给实现（与校验使用同一字符串即可）
provider.initialize(jsonString);
```
`AuthConfig` 提供 `bitanswerFeatureId(String logicalKey)` 等辅助方法，供后续在 `hasFeature` 与比特 `QueryFeature` 之间做映射。
## 场景字段摘要
- **wharf**：`wharf.topology`（`cloud` / `group` / `local_float`）等与集中授权拓扑相关的**提示**；实际连网方式仍以 `bitanswer.url` 为准。
- **school**：`school.edgeDeviceId` 等用于运营对账；是否写入比特自定义字段由实现阶段决定。
- **floating**：**必填** `floating.projectId`；表达「按项目」授权锚点，与商务合同、控制台业务模板需一致。
后续优化（错误码、OIDC、集团占点策略等）在保持 `schemaVersion` 或递增版本的前提下扩展字段即可。
docs/c.md
+71 -10
View File
@@ -1,12 +1,11 @@
# 比特授权云 · C 语言接口定义（离线摘录）
> 本文档由官网页面离线摘录并整理排版，便于本地检索。官方地址：<https://doc.bitanswer.cn/docs/client-api/c-interface-definitions-v2/>
> 本文档由官网页面离线摘录并整理排版，便于本地检索。官方地址：[https://doc.bitanswer.cn/docs/client-api/c-interface-definitions-v2/](https://doc.bitanswer.cn/docs/client-api/c-interface-definitions-v2/)
---
## 认证
### Bit_Login / Bit_LoginEx
```c
@@ -26,6 +25,7 @@ BIT_STATUS Bit_LoginEx(
BIT_HANDLE *pHandle,
LOGIN_MODE mode);
```
授权登录。初始化运行环境，获取操作句柄。必须在除升级函数之外的其它操作前执行。根据登录模式的不同可能需要连接授权服务器。
Bit_Login 等价于 Bit_LoginEx（…, featureId=0，szReserved=NULL, …)，当需要登录包含指定特征项的授权时才需要调用Bit_LoginEx。
@@ -50,6 +50,7 @@ Bit_Login 等价于 Bit_LoginEx（…, featureId=0，szReserved=NULL, …)，当
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。
@@ -57,10 +58,10 @@ lic:///tmp,lic:///data,bit://127.0.0.1:8273
| **类型** | **格式** | **说明** |
| -------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| **授权码** | 比特授权云平台产生的SN 示例：`JNLTGZSE********` | 检查指定SN的License |
| **授权码** | 比特授权云平台产生的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> | |
| **既输入SN又输入激活口令** | `xxx<password>`，授权码后边紧跟“<>” 示例：`JNLTGZSE******`**<123> | |
- **featureId** - [IN] 登录授权所需要包含的特征项ID。
@@ -73,6 +74,7 @@ lic:///tmp,lic:///data,bit://127.0.0.1:8273
<feature id="" name="" ver=""/>
</scope>
```
- **pApplicationData** - [IN] 产品识别码，在Bitanswer SDK头文件里。
- **pHandle** - [OUT] 通过Login函数返回的上下文句柄。
- **mode** - [IN] 登录模式，按位操作。
@@ -154,6 +156,7 @@ BIT_STATUS Bit_LoginByToken(
BIT_UCHAR *pApplicationData,
BIT_HANDLE *pHandle)
```
帐号授权的登录接口。仅支持两种认证方式，这里是使用比特授权云平台自己产生的access_token进行认证。
### 参数
@@ -182,6 +185,7 @@ BIT_STATUS Bit_LoginByTokenEx(
BIT_UCHAR *pApplicationData,
BIT_HANDLE *pHandle)
```
帐号授权的登录接口。仅支持两种认证方式，这里是使用OIDC协议产生的id_token认证。
### 参数
@@ -213,6 +217,7 @@ BIT_STATUS Bit_LoginByPassword(
BIT_UCHAR *pApplicationData,
BIT_HANDLE *pHandle);
```
通过用户名和密码登录帐号授权。
### 参数
@@ -231,6 +236,7 @@ BIT_STATUS Bit_LoginByPassword(
BIT_STATUS Bit_Logout (
BIT_HANDLE handle)
```
此函数用于释放上下文句柄，退出登录状态，与Login相关接口一一对应。
### 参数
@@ -247,6 +253,7 @@ BIT_STATUS Bit_Revoke (
BIT_CHAR *pRevocationInfo,
BIT_UINT32 *pRevocationInfoSize)
```
从客户端迁出已激活的浮动授权码。授权码迁出后，可以用于其它的客户端。根据输入参数的不同，本函数可用于在线或离线迁出。
### 参数
@@ -264,6 +271,7 @@ BIT_STATUS Bit_RemoveSn (
BIT_PCSTR szSN,
BIT_UCHAR *pApplicationData)
```
删除指定授权码在本机的授权数据。
### 参数
@@ -278,6 +286,7 @@ BIT_STATUS Bit_Heartbeat(
BIT_HANDLE handle,
BIT_UINT32 *pReconnectsNum)
```
手动心跳，可以无限次调用，10s只会触发一次。
注：当自动心跳停止后，调用该接口可以尝试恢复自动心跳。
@@ -298,6 +307,7 @@ BIT_STATUS Bit_SessionControl(
BIT_CHAR *pValue,
BIT_UINT32 *pValueLen)
```
控制或设置session的信息。具体使用场景可参考《浏览器并发控制》文档。
### 参数
@@ -325,6 +335,7 @@ BIT_STATUS Bit_SetSessionState (
BIT_UINT32 state,
BIT_VOID *pReserved)
```
设置客户端的状态为空闲状态或繁忙状态或激活状态。
### 参数
@@ -358,7 +369,6 @@ if (用户正在操作) {
## 激活升级
### Bit_UpdateOnline
```c
@@ -367,6 +377,7 @@ BIT_STATUS Bit_UpdateOnline (
BIT_PCSTR szSN,
BIT_UCHAR *pApplicationData)
```
此函数用于与授权服务器在线连接，自动完成本地授权的升级操作。本函数需要进行网络连接。
### 参数
@@ -395,6 +406,7 @@ BIT_STATUS Bit_GetRequestInfo (
BIT_CHAR *pRequestInfo,
BIT_UINT32 *pRequestInfoSize)
```
获取当前运行环境的升级请求码，用于发起本地授权激活及升级请求。如果第一次调用返回错误码260，说明传入的pRequestInfoSize太小，可传入返回的pRequestInfoSize再重新调用一次。
### 参数
@@ -442,6 +454,7 @@ BIT_STATUS Bit_ApplyUpdateInfo(
BIT_CHAR *pReceipt,
BIT_UINT32 *pReceiptSize)
```
应用升级码完成本地授权激活或升级。本函数必须在获取请求码的同一环境下执行。
### 参数
@@ -475,6 +488,7 @@ BIT_STATUS Bit_ApplyUpdateInfoEx(
BIT_CHAR *pReceipt,
BIT_UINT32 *pReceiptSize);
```
应用升级码完成远程集团授权激活或升级。一般不建议使用。
### 参数
@@ -495,6 +509,7 @@ BIT_STATUS Bit_GetUpdateInfo (
BIT_CHAR *pUpdateInfo,
BIT_UINT32 *pUpdateInfoSize)
```
使用请求码与授权服务器进行连接，获取升级码。本函数需要进行网络连接。
### 参数
@@ -508,7 +523,6 @@ BIT_STATUS Bit_GetUpdateInfo (
## 特征项操作
### Bit_BatchBegin
```c
@@ -516,6 +530,7 @@ BIT_STATUS Bit_BatchBegin(
BIT_HANDLE handle,
BIT_UINT32 mode)
```
开启批量Query模式，调用此API后调用的所有Query相关API，全部由Bit_BatchEnd接口批量提交连接集团服务。
### 参数
@@ -538,6 +553,7 @@ BIT_STATUS Bit_BatchEnd(
BIT_UINT32 *pResultList,
BIT_UINT32 *pResultListSize)
```
批量提交Query请求。
### 参数
@@ -577,6 +593,7 @@ BIT_STATUS Bit_QueryFeature (
BIT_UINT32 featureId,
BIT_UINT32 *pCapacity)
```
开发商可以对软件的某个功能进行单独授权，当程序运行该模块时，可以通过该接口检查是否可用。
对于单机授权：只检查特征项是否可用。
@@ -610,6 +627,7 @@ BIT_STATUS Bit_ReleaseFeature (
BIT_UINT32 featureId,
BIT_UINT32 *pCapacity)
```
释放所占用的用户数，该函数和Bit_QueryFeature一一对应。
### 参数
@@ -643,6 +661,7 @@ BIT_STATUS Bit_QueryFeatureEx (
BIT_UINT32 *pCapacity,
BIT_PCSTR xmlScope)
```
集团授权专用，该接口支持占用指定用户数，支持通过特征项版本进行检查。
### 参数
@@ -702,6 +721,7 @@ BIT_STATUS Bit_ReleaseFeatureEx (
BIT_UINT32 *pCapacity,
BIT_PCSTR xmlScope)
```
集团授权专用，释放指定的用户数。该接口与Bit_QueryFeatureEx对应。
### 参数
@@ -740,6 +760,7 @@ BIT_STATUS Bit_QueryFeatureEx2 (
BIT_PCSTR xmlScope,
BIT_TICKET *pTicket)
```
可以使用“特征项名称 + 特征项版本”进行用户数占用，支持队列模式。
对于单机授权：只检查特征项是否可用。
@@ -796,6 +817,7 @@ BIT_STATUS Bit_ReleaseFeatureEx2 (
BIT_TICKET ticket,
BIT_UINT32 consumed)
```
释放ticket所占用的用户数。该函数和Bit_QueryFeatureEx2一一对应。
### 参数
@@ -811,6 +833,7 @@ if (status == BIT_SUCCESS) {
// 释放ticket占用的用户数
}
```
**特征项Query相关接口比较**
@@ -830,6 +853,7 @@ BIT_STATUS Bit_GetFeatureInfo2 (
BIT_PCSTR xmlScope,
BIT_INT32 *pExpired)
```
检查特征项是否存在，不会占用授权码或特征项的用户数，获取特征项的剩余有效期。
### 参数
@@ -845,6 +869,7 @@ BIT_STATUS Bit_GetFeatureInfo2 (
<!-- 或者直接输入：'1.1' -->
```
- **pExpired** - [OUT] 返回该特征项的剩余有效期，正数代表剩余有效期，负数代表过期天数，36500代表永久有效。
### Bit_GetFeatureInfoEx2
@@ -857,6 +882,7 @@ BIT_STATUS Bit_GetFeatureInfoEx2(
BIT_CHAR *pFeatureInfo,
BIT_UINT32 *pFeatureInfoSize);
```
获取指定feature的信息，以XML格式返回。
### 参数
@@ -872,6 +898,7 @@ BIT_STATUS Bit_GetFeatureInfoEx2(
<!-- 或者直接输入：'1.1' -->
```
- **pFeatureInfo** - [OUT] feature信息存储区地址。
- **pFeatureInfoSize** - [IN/OUT] 会话存储区大小。
@@ -884,6 +911,7 @@ BIT_STATUS Bit_GetTicketInfo(
BIT_CHAR *pXmlInfo,
BIT_UINT32 *pSize)
```
获取ticket信息。
### 参数
@@ -946,6 +974,7 @@ BIT_STATUS Bit_ConvertFeature(
BIT_UINT32 para4,
BIT_UINT32 *pResult);
```
使用“算法”类型的特征项对输入参数进行变换操作，得到唯一对应的4字节结果。
### 参数
@@ -981,6 +1010,7 @@ BIT_STATUS Bit_EncryptFeature(
BIT_VOID *pCipherBuffer,
BIT_UINT32 dataBufferSize);
```
使用“密钥”类型的特征项对输入的明文进行加密，返回密文结果。
### 参数
@@ -1013,6 +1043,7 @@ BIT_STATUS Bit_DecryptFeature(
BIT_VOID *pPlainBuffer,
BIT_UINT32 dataBufferSize);
```
使用“密钥”类型的特征项对输入的密文进行解密，返回明文结果。
### 参数
@@ -1043,6 +1074,7 @@ BIT_STATUS Bit_ReadFeature(
BIT_UINT32 featureId,
BIT_UINT32 *pFeatureValue);
```
读取特征项的数据内容，可用于“只读”和“读写”特征类型。
### 参数
@@ -1059,6 +1091,7 @@ BIT_STATUS Bit_WriteFeature(
BIT_UINT32 featureId,
BIT_UINT32 featureValue);
```
更新“读写”类型的特征项的数据内容。
### 参数
@@ -1069,7 +1102,6 @@ BIT_STATUS Bit_WriteFeature(
## 配置项操作
### Bit_GetDataItem
```c
@@ -1079,6 +1111,7 @@ BIT_STATUS Bit_GetDataItem (
BIT_VOID *pDataItemValue,
BIT_UINT32 *pDataItemValueSize)
```
读取指定的配置项数据。
### 参数
@@ -1097,6 +1130,7 @@ BIT_STATUS Bit_SetDataItem (
BIT_VOID *pDataItemValue,
BIT_UINT32 dataItemValueSize)
```
创建或更新配置项。如果相同名称的配置项存在，则会更新其中的数据；否则将添加新的授权码配置项。
### 参数
@@ -1113,6 +1147,7 @@ BIT_STATUS Bit_GetDataItemNum (
BIT_HANDLE handle,
BIT_UINT32 *pNum)
```
此函数用于获取可访问配置项的数量，一般用于配置项的枚举操作。
### 参数
@@ -1129,6 +1164,7 @@ BIT_STATUS Bit_GetDataItemName (
BIT_CHAR *pDataItemName,
BIT_UINT32 *pDataItemNameSize)
```
根据配置项索引获取其名称，一般用于配置项的枚举操作。
### 参数
@@ -1145,6 +1181,7 @@ BIT_STATUS Bit_RemoveDataItem (
BIT_HANDLE handle,
BIT_PCSTR szDataItemName)
```
删除指定的配置项。该操作无法删除通过控制台设置的产品配置项或模版配置项。
### 参数
@@ -1154,7 +1191,6 @@ BIT_STATUS Bit_RemoveDataItem (
## 信息获取
### Bit_GetSessionInfo
```c
@@ -1164,6 +1200,7 @@ BIT_STATUS Bit_GetSessionInfo (
BIT_CHAR *pSessionInfo,
BIT_UINT32 *pSessionInfoSize)
```
获取当前会话信息，以字符串形式返回。根据获取的内容不同，返回结果可能是XML格式或非XML格式。返回数据中的日期项已根据客户端的本地时区进行调整。如果Login时未指定SN，返回串为当前系统所有可用SN的综合结果。
当函数返回BIT_ERR_BUFFER_SMALL时，pSessionInfoSize保存的是实际数据的大小。
@@ -1242,6 +1279,7 @@ BIT_STATUS Bit_GetInfo (
BIT_CHAR *pInfo,
BIT_UINT32 *pInfoSize)
```
获取本地授权信息。
如果要获取集团授权的信息，则szSN输入“`@bit://ip:port`”，会获取集团授权信息（仅支持type=BIT_INFO_SN）。
@@ -1281,6 +1319,7 @@ BIT_STATUS Bit_GetServerInfo(
BIT_CHAR *pServerInfo,
BIT_UINT32 *pServerInfoSize);
```
获取集团服务的License信息，数据以XML格式返回。调用此函数前客户端不需要执行登录操作。
### 参数
@@ -1321,6 +1360,7 @@ BIT_STATUS Bit_GetServerInfo(
……
</features>
```
1. 指定分组（group）查询
仅支持BIT_SERVER_INFO_SN_USERS、BIT_SERVER_INFO_FEATURE_USERS、BIT_SERVER_INFO_FEATURE_USERS_EX三种类型，通过name限定待查询的分组。
@@ -1332,6 +1372,7 @@ BIT_STATUS Bit_GetServerInfo(
……
</groups>
```
> 说明：通过Bit_SetCustomInfo的CUSTOM_GROUP_NAME(0xA)设置分组。
### 返回XML数据说明
@@ -1360,6 +1401,7 @@ XML返回示例：
BIT_STATUS Bit_GetVersion (
BIT_UINT32 *pVersion)
```
获取客户端安全库版本号。
### 参数
@@ -1373,6 +1415,7 @@ BIT_STATUS Bit_GetNextHandle(
BIT_HANDLE handle,
BIT_HANDLE *pNextHandle)
```
用来遍历当前进程内的handle。
### 参数
@@ -1398,6 +1441,7 @@ BIT_STATUS Bit_TestBitService (
BIT_UINT32 featureId,
BIT_UCHAR *pApplicationData)
```
测试集团授权的特征项是否可用，不会占用授权码或特征项的用户数。
### 参数
@@ -1421,6 +1465,7 @@ BIT_STATUS Bit_GetProductPath(
BIT_CHAR *pPath,
BIT_UINT32 lenPath);
```
获取授权存储目录。
### 参数
@@ -1434,6 +1479,7 @@ BIT_STATUS Bit_GetProductPath(
```c
BIT_STATUS Bit_GetLastError();
```
获取上一个API调用返回的错误码。
### 参数
@@ -1442,7 +1488,6 @@ BIT_STATUS Bit_GetLastError();
## 属性设置
### Bit_SetAttr
```c
@@ -1451,6 +1496,7 @@ BIT_STATUS Bit_SetAttr (
BIT_UINT32 type,
BIT_VOID *pValue)
```
设置全局配置或当前会话的配置。
### 参数
@@ -1516,6 +1562,7 @@ BIT_STATUS Bit_SetProxy (
BIT_PCSTR szUserID,
BIT_PCSTR szPassword)
```
设置代理服务的地址和端口。
### 参数
@@ -1540,6 +1587,7 @@ BIT_STATUS Bit_SetCustomInfo (
BIT_VOID *pInfoData,
BIT_UINT32 infoDataSize)
```
设置客户端运行自定义信息，需要在程序的最开始调用。
### 参数
@@ -1589,6 +1637,7 @@ if (status == BIT_SUCCESS) {
BIT_STATUS Bit_SetRootPath (
BIT_PCSTR szPath)
```
设置授权文件的存储路径。
### 参数
@@ -1604,6 +1653,7 @@ BIT_STATUS Bit_SetLocalServer (
BIT_UINT32 nPort,
BIT_UINT32 nTimeoutSecondes)
```
设置集团服务的地址和端口。
### 参数
@@ -1615,7 +1665,6 @@ BIT_STATUS Bit_SetLocalServer (
## 借出操作
### Bit_GetBorrowRequest
```c
@@ -1626,6 +1675,7 @@ BIT_STATUS Bit_GetBorrowRequest(
BIT_CHAR *pRequestInfo,
BIT_UINT32 *pRequestInfoSize)
```
获取借出请求串，用来离线借出。
### 参数
@@ -1647,6 +1697,7 @@ BIT_STATUS Bit_GetBorrowFeatureRequest(
BIT_CHAR *pRequestInfo,
BIT_UINT32 *pRequestInfoSize)
```
获取借出请求串，该接口支持指定特征项借出。
### 参数
@@ -1684,6 +1735,7 @@ BIT_STATUS Bit_CheckOutSnEx(
BIT_UCHAR *pApplicationData,
BIT_UINT32 nDurationDays);
```
从授权服务器在线借出一个完整的授权码，以允许客户端服务器单独使用。被借出的授权码必须具有可借出属性，并在客户端成功借出后减少一个可用用户数。被借出的用户数在到期后将自动返还给服务器。
### 参数
@@ -1721,6 +1773,7 @@ BIT_STATUS Bit_CheckOut(
BIT_UCHAR *pApplicationData,
BIT_UINT32 nDurationDays)
```
从授权服务器在线借出授权码或者特征项。
### 参数
@@ -1740,6 +1793,7 @@ type：借出类型。目前仅支持ws，表示从外网借出（针对云授
sn：指定借出的SN
-->
```
- **pFeatureList** xml结构，指定借出的特征项列表，如果不传则借出整个SN。
```xml
@@ -1749,6 +1803,7 @@ sn：指定借出的SN
<feature id='10'/>
</features>
```
当feature指定了借出时间，则会覆盖nDurationDays该时间，没有指定，则借出nDurationDays天。
借出feature时，如果指定了版本，则直接大于等于借出版本的特征项，只借一个，如果没有指定版本，则该特征项的所有版本都借出一个。
@@ -1792,6 +1847,7 @@ BIT_STATUS Bit_CheckOutFeatures(
BIT_UINT32 nFeatureInList,
BIT_UINT32 nDurationDays);
```
从集团授权服务器借出一组特征项，这些特征项必须包含在同一个授权码中。被借出的集团授权码必须具有可借出属性，并在客户端成功借出后减少一个可用用户数。被借出的用户数在到期后将自动返还给集团服务器。
### 参数
@@ -1831,6 +1887,7 @@ BIT_STATUS Bit_CheckIn(
BIT_UINT32 featureId,
BIT_UCHAR *pApplicationData)
```
提前返还从集团授权服务器借出的授权。要提前返还授权，该授权码必须具有允许提前返还属性。
### 参数
@@ -1848,6 +1905,7 @@ BIT_STATUS Bit_CheckInEx(
BIT_PCSTR szScope,
BIT_UCHAR *pApplicationData)
```
提前返还从授权服务器借出的授权。要提前返还授权，该授权码必须具有允许提前返还属性。
### 参数
@@ -1861,6 +1919,7 @@ BIT_STATUS Bit_CheckInEx(
<type>ws</type> <!-- type：归还类型，ws表示归还到云授权服务，默认是归还到集团授权服务 -->
</scope>
```
用于指定借出的参数，格式：wsxxxx，type设定为ws时表示从云授权服务器借出和归还。
- **pApplicationData** - [IN] 产品识别码。记录在接口定义文件中，与产品一一对应。
@@ -1872,9 +1931,11 @@ BIT_STATUS Bit_ApplyBorrowInfo(
BIT_UCHAR *pApplicationData,
BIT_PCSTR pBorrowInfo)
```
客户端应用离线借出串，Bit_ApplyUpdateInfo可以兼容该接口。
### 参数
- **pApplicationData** - [IN] 产品识别码。记录在接口定义文件中，与产品一一对应。
- **pBorrowInfo** - [IN] 借出请求串。
docs/java.md
+62 -10
View File
@@ -1,12 +1,11 @@
# 比特授权云 · Java 语言接口（离线摘录）
> 本文档由官网页面离线摘录并整理排版，便于本地检索。官方地址：<https://doc.bitanswer.cn/docs/client-api/java-interface-v2/>
> 本文档由官网页面离线摘录并整理排版，便于本地检索。官方地址：[https://doc.bitanswer.cn/docs/client-api/java-interface-v2/](https://doc.bitanswer.cn/docs/client-api/java-interface-v2/)
---
## 构造方法详细信息
### BitAnswer
```java
@@ -16,7 +15,6 @@ public BitAnswer(String url, String sn, LoginMode mode)
## 认证
### login / loginEx
```java
@@ -30,6 +28,7 @@ void loginEx (String url,
String xmlScope,
LoginMode mode)
```
授权登录。初始化运行环境，获取操作句柄。必须在除升级函数之外的其它操作前执行。根据登录模式的不同可能需要连接授权服务器。
Login 等价于 LoginEx（featureId=0）；当需要登录包含指定特征项的授权时才需要调用LoginEx。
@@ -75,6 +74,7 @@ Login 等价于 LoginEx（featureId=0）；当需要登录包含指定特征项
void loginByToken (String url,
String token)
```
帐号授权的登录接口。仅支持两种认证方式，这里是使用比特授权云平台自己产生的access_token进行认证。
### 参数
@@ -95,6 +95,7 @@ void loginByTokenEx (String url,
String idpGuid,
String grantType)
```
帐号授权的登录接口。仅支持两种认证方式，这里是使用OIDC协议产生的id_token认证。
### 参数
@@ -118,6 +119,7 @@ void loginByPassword (String url,
String account,
String password)
```
通过用户名和密码登录帐号授权。
### 参数
@@ -137,6 +139,7 @@ void loginByPassword (String url,
```java
void logout()
```
此函数用于释放上下文句柄，退出登录状态，与Login相关接口一一对应。
### 参数
@@ -152,6 +155,7 @@ void logout()
```java
String revoke (String sn)
```
从客户端迁出已激活的浮动授权码。授权码迁出后，可以用于其它的客户端。根据输入参数的不同，本函数可用于在线或离线迁出。
### 参数
@@ -168,6 +172,7 @@ String revoke (String sn)
void revokeOnline (String url,
String sn)
```
从客户端迁出已激活的浮动授权码。授权码迁出后，可以用于其它的客户端。本函数需要进行网络连接。
### 参数
@@ -184,6 +189,7 @@ void revokeOnline (String url,
```java
void removeSn (String sn)
```
删除指定授权码在本机的授权数据。
### 参数
@@ -199,6 +205,7 @@ void removeSn (String sn)
```java
int heartbeat()
```
手动心跳，可以无限次调用，10s只会触发一次。
注：当自动心跳停止后，调用该接口可以尝试恢复自动心跳。
@@ -218,6 +225,7 @@ String sessionControl (String url,
String sessionId,
SessionCtlType type)
```
控制或设置session的信息。具体使用场景可参考《浏览器并发控制》文档。
### 参数
@@ -243,6 +251,7 @@ String sessionControl (String url,
void setSessionState (int state,
byte[] pReserved)
```
设置客户端的状态为空闲状态或繁忙状态或激活状态。
### 参数
@@ -264,13 +273,13 @@ void setSessionState (int state,
## 激活升级
### updateOnline
```java
void updateOnline (String url,
String sn)
```
此函数用于与授权服务器在线连接，自动完成本地授权的升级操作。本函数需要进行网络连接。
### 参数
@@ -288,6 +297,7 @@ void updateOnline (String url,
String getRequestInfo (String sn,
BindingType type)
```
获取当前运行环境的升级请求码，用于发起本地授权激活及升级请求。
### 参数
@@ -310,6 +320,7 @@ String getRequestInfo (String sn,
```java
String applyUpdateInfo (String updateInfo)
```
应用升级码完成本地授权激活或升级。本函数必须在获取请求码的同一环境下执行。
### 参数
@@ -327,6 +338,7 @@ String getUpdateInfo (String url,
String sn,
String requestInfo)
```
使用请求码与授权服务器进行连接，获取升级码。本函数需要进行网络连接。
### 参数
@@ -341,12 +353,12 @@ String getUpdateInfo (String url,
## 特征项操作
### batchBegin
```java
void batchBegin (BatchMode mode)
```
开启批量Query模式，调用此API后调用的所有Query相关API，全部由Bit_batchEnd接口批量提交连接集团服务。
### 参数
@@ -365,6 +377,7 @@ void batchBegin (BatchMode mode)
```java
int[] batchEnd()
```
批量提交Query请求。
### 参数
@@ -380,6 +393,7 @@ int[] batchEnd()
```java
int queryFeature (int featureId)
```
开发商可以对软件的某个功能进行单独授权，当程序运行该模块时，可以通过该接口检查是否可用。
### 参数
@@ -395,6 +409,7 @@ int queryFeature (int featureId)
```java
int releaseFeature (int featureId)
```
释放所占用的用户数，该函数和Bit_QueryFeature一一对应。
### 参数
@@ -413,6 +428,7 @@ int queryFeatureEx (int featureId,
int required,
String scope)
```
集团授权专用，该接口支持占用指定用户数，支持通过特征项版本进行检查。
### 参数
@@ -439,6 +455,7 @@ int releaseFeatureEx (int featureId,
int consumed,
String scope)
```
集团授权专用，释放指定的用户数。该接口与Bit_QueryFeatureEx对应。
### 参数
@@ -459,6 +476,7 @@ long queryFeatureEx2 (String featureName,
int required,
String scope)
```
可以使用“特征项名称 + 特征项版本”进行用户数占用，支持队列模式。
### 参数
@@ -486,6 +504,7 @@ long queryFeatureEx2 (String featureName,
void releaseFeatureEx2 (byte[] ticket,
int consumed)
```
释放ticket所占用的用户数。该函数和Bit_QueryFeatureEx2一一对应。
### 参数
@@ -503,6 +522,7 @@ void releaseFeatureEx2 (byte[] ticket,
int getFeatureInfo2 (String featureName,
String scope)
```
检查特征项是否存在，不会占用授权码或特征项的用户数，获取特征项的剩余有效期。
### 参数
@@ -520,6 +540,7 @@ int getFeatureInfo2 (String featureName,
String getFeatureInfoEx2 (String featureName,
String scope)
```
获取指定feature的信息，以XML格式返回。
### 参数
@@ -544,6 +565,7 @@ String getFeatureInfoEx2 (String featureName,
String getTicketInfo (byte[] ticket,
int type)
```
获取ticket信息。
### 参数
@@ -568,6 +590,7 @@ int convertFeature (int featureId,
int para3,
int para4)
```
使用“算法”类型的特征项对输入参数进行变换操作，得到唯一对应的4字节结果。
### 参数
@@ -588,6 +611,7 @@ int convertFeature (int featureId,
byte[] encryptFeature (int featureId,
byte[] pPlainBuffer)
```
使用“密钥”类型的特征项对输入的明文进行加密，返回密文结果。
### 参数
@@ -605,6 +629,7 @@ byte[] encryptFeature (int featureId,
byte[] decryptFeature (int featureId,
byte[] pCipherBuffer)
```
使用“密钥”类型的特征项对输入的密文进行解密，返回明文结果。
### 参数
@@ -621,6 +646,7 @@ byte[] decryptFeature (int featureId,
```java
int readFeature (int featureId)
```
读取特征项的数据内容，可用于“只读”和“读写”特征类型。
### 参数
@@ -637,6 +663,7 @@ int readFeature (int featureId)
void writeFeature (int featureId,
int featureValue)
```
更新“读写”类型的特征项的数据内容。
### 参数
@@ -650,12 +677,12 @@ void writeFeature (int featureId,
## 配置项操作
### getDataItem
```java
byte[] getDataItem (String dataItemName)
```
读取指定的配置项数据。
### 参数
@@ -672,6 +699,7 @@ byte[] getDataItem (String dataItemName)
void setDataItem (String dataItemName,
byte[] dataItemValue)
```
创建或更新配置项。如果相同名称的配置项存在，则会更新其中的数据；否则将添加新的授权码配置项。
### 参数
@@ -688,6 +716,7 @@ void setDataItem (String dataItemName,
```java
int getDataItemNum()
```
此函数用于获取可访问配置项的数量，一般用于配置项的枚举操作。
### 参数
@@ -703,6 +732,7 @@ int getDataItemNum()
```java
String getDataItemName (int index)
```
根据配置项索引获取其名称，一般用于配置项的枚举操作。
### 参数
@@ -718,6 +748,7 @@ String getDataItemName (int index)
```java
void removeDataItem (String dataItemName)
```
删除指定的配置项。该操作无法删除通过控制台设置的产品配置项或模版配置项。
### 参数
@@ -730,12 +761,12 @@ void removeDataItem (String dataItemName)
## 信息获取
### getSessionInfo
```java
String getSessionInfo (SessionType type)
```
获取当前会话信息，以字符串形式返回。根据获取的内容不同，返回结果可能是XML格式或非XML格式。返回数据中的日期项已根据客户端的本地时区进行调整。如果Login时未指定SN，返回串为当前系统所有可用SN的综合结果。
### 参数
@@ -771,6 +802,7 @@ String getSessionInfo (SessionType type)
String getInfo (String sn,
InfoType type)
```
获取本地授权信息。
### 参数
@@ -800,6 +832,7 @@ String getServerInfo (String url,
String scope,
ServerInfoType type)
```
获取集团服务的license信息，数据以XML格式返回。调用此函数前客户端不需要执行登录操作。
### 参数
@@ -824,6 +857,7 @@ String getServerInfo (String url,
```java
int getVersion()
```
获取客户端安全库版本号。
### 参数
@@ -841,6 +875,7 @@ void testBitService (String url,
String sn,
int featureId)
```
测试集团授权的特征项是否可用，不会占用授权码或特征项的用户数。
### 参数
@@ -858,6 +893,7 @@ void testBitService (String url,
```java
String getProductPath()
```
获取授权存储目录。
### 参数
@@ -873,6 +909,7 @@ String getProductPath()
```java
int getLastError()
```
获取上一个API调用返回的错误码。
### 参数
@@ -889,13 +926,13 @@ int getLastError()
## 属性设置
### setAttr
```java
void setAttr (int type,
byte[] pValue)
```
设置全局配置或当前会话的配置。
### 参数
@@ -924,6 +961,7 @@ void setProxy (String hostName,
String userId,
String password)
```
设置代理服务的地址和端口。
### 参数
@@ -943,6 +981,7 @@ void setProxy (String hostName,
void setCustomInfo (int infoId,
String infoData)
```
设置客户端运行自定义信息，需要在程序的最开始调用。infoId定义详见CustomInfo类型。
### 参数
@@ -958,6 +997,7 @@ void setCustomInfo (int infoId,
void setCustomInfo (int infoId,
int infoData)
```
设置客户端运行自定义信息，需要在程序的最开始调用。infoId定义详见CustomInfo类型。
### 参数
@@ -980,6 +1020,7 @@ void setCustomInfo (int infoId,
```java
void setRootPath (String rootPath)
```
设置授权文件的存储路径。
### 参数
@@ -997,6 +1038,7 @@ void setLocalServer (String hostName,
int port,
int timeout)
```
设置集团服务的地址和端口。
### 参数
@@ -1011,13 +1053,13 @@ void setLocalServer (String hostName,
## 借出操作
### getBorrowRequest
```java
String getBorrowRequest (String sn,
int durationDay)
```
获取借出请求串，用来离线借出。
### 参数
@@ -1035,6 +1077,7 @@ String getBorrowRequest (String sn,
String getBorrowFeatureRequest (int durationDay,
String borrowScope)
```
获取借出请求串，该接口支持指定特征项借出。
### 参数
@@ -1056,6 +1099,7 @@ String getBorrowFeatureRequest (int durationDay,
void checkOutSn (String url,
int featureId)
```
从授权服务器在线借出一个完整的授权码，以允许客户端服务器单独使用。被借出的授权码必须具有可借出属性，并在客户端成功借出后减少一个可用用户数。被借出的用户数在到期后将自动返还给服务器。
### 参数
@@ -1075,6 +1119,7 @@ void checkOutSnEx (String url,
String xmlScope,
int durationDays)
```
从授权服务器在线借出一个完整的授权码，以允许客户端服务器单独使用。被借出的授权码必须具有可借出属性，并在客户端成功借出后减少一个可用用户数。被借出的用户数在到期后将自动返还给服务器。
### 参数
@@ -1096,6 +1141,7 @@ void checkOut (String url,
String featureList,
int durationDays)
```
从授权服务器在线借出授权码或者特征项。
### 参数
@@ -1113,6 +1159,7 @@ void checkOut (String url,
type：借出类型。目前仅支持ws，表示从外网借出（针对云授权和集团授权）
sn：指定借出的SN
```
- **featureList** - [IN] 特征项列表，指定借出的特征项列表，如果不传则借出整个SN。示例：
```xml
@@ -1125,6 +1172,7 @@ sn：指定借出的SN
当feature指定了借出时间，则会覆盖nDurationDays该时间，没有指定，则借出nDurationDays天。
借出feature时，如果指定了版本，则直接大于等于借出版本的特征项，只借一个，如果没有指定版本，则该特征项的所有版本都借出一个。
```
- **durationDays** - [IN] 借出有效期，单位为天，需小于等于授权码允许的最大借出天数。
### 返回
@@ -1138,6 +1186,7 @@ void checkOutFeatures (String url,
int[] featureList,
int durationDays)
```
从集团授权服务器借出一组特征项，这些特征项必须包含在同一个授权码中。被借出的集团授权码必须具有可借出属性，并在客户端成功借出后减少一个可用用户数。被借出的用户数在到期后将自动返还给集团服务器。
### 参数
@@ -1156,6 +1205,7 @@ void checkOutFeatures (String url,
void checkIn (String url,
int featureId)
```
提前返还从集团授权服务器借出的授权。要提前返还授权，该授权码必须具有允许提前返还属性。
### 参数
@@ -1174,6 +1224,7 @@ void checkInEx (String url,
int featureId,
String xmlScope)
```
提前返还从授权服务器借出的授权。要提前返还授权，该授权码必须具有允许提前返还属性。
### 参数
@@ -1191,6 +1242,7 @@ void checkInEx (String url,
```java
void ApplyBorrowInfo (string borrowInfo)
```
客户端应用离线借出串，ApplyUpdateInfo可以兼容该接口。
### 参数
@@ -1199,4 +1251,4 @@ void ApplyBorrowInfo (string borrowInfo)
### 返回
无
无