hpd840321
25 KiB
比特授权云：客户端 API 梳理（基于官方文档）
来源：C 语言接口定义 v2、Java 语言接口 v2、SDK 概述、典型场景。
其它语言入口（文档中心列举）：Delphi、C#、VB.Net、VB6。
整理日期：2026-04-06
说明：本文为对公开文档的纲要式整理，参数细节、错误码与边界条件以官方页面及随产品下发的bitanswer.h/接口文件为准。
本地对照：已与仓库内手工备份的 C 接口[docs/c.md](c.md)、Java 接口[docs/java.md](java.md)交叉核对（见文末「审核说明」及 附录 A）。
1. SDK 交付形态与前置条件
- 获取方式：在比特授权云平台「模块下载」获取与产品绑定的静态库/动态库及接口定义；不同产品库不可混用（文档说明
Login不匹配会返回0x105类错误）。 - C：头文件
bitanswer.h+ 平台库（文档示例如libxxx_xxx_x64.a）。 - Java：JNI + 主封装类
**BitAnswer**（方法名为 camelCase，语义与 C API 大体一一对应；签名与枚举见 附录 A /[docs/java.md](java.md)）。 - 支持平台（SDK 概述列举）：Windows、Linux、Android、ARM Linux、MIPS Linux、macOS、iOS、HarmonyOS、QNX 等。
运行期共性概念（SDK 概述）
| 概念 | 含义 |
|---|---|
application_data / 产品识别码 |
编译进接口定义、与产品一一对应，多数 API 必填。 |
BIT_HANDLE / 会话句柄 |
Bit_Login / Bit_LoginEx 等成功后返回，后续特征项/心跳等依赖此句柄。 |
BIT_STATUS |
API 返回状态码；具体取值与错误码见官方「错误码」文档。 |
| 授权文件默认目录（典型场景） | Linux：{当前用户}/BitAnswer；Windows：{系统盘}/ProgramData/BitAnswer；可用 Bit_SetRootPath 自定义。 |
2. URL / 地址约定（Bit_Login 的 szURL 等）
文档说明 szURL 可表达多种「授权来源」（节选）：
| 形式 | 含义 |
|---|---|
bit://ip:port |
集团授权服务地址。 |
http://ip:port |
授权服务中心（如云/E3 等）。 |
root://路径 |
仅在该路径下查找授权，效果类似先 Bit_SetRootPath。 |
lic://文件路径 / 目录 / License 串 |
内存或本地文件加载：lic:// 可加载文件内容、目录下 *.lic、或直接传入 License 串；多个路径用逗号分隔（c.md 示例为半角 ,）。 |
| 简写 | 文档示例：/tmp,/data,127.0.0.1:8273 等与 lic://.../bit://... 组合等价写法。 |
配置优先级（文档）：同一设置同时存在时 — 环境变量 > 调用 API 传入 > 配置文件（bit_config.xml，典型场景详述多 Server/Proxy 节点）。
3. 登录模式与标识（LOGIN_MODE / LoginMode）
与 Bit_Login / Bit_LoginEx 的 mode 为按位组合。文档列出的典型取值（C 名 / Java 名对应）：
| C（示意） | Java（示意） | 语义摘要 |
|---|---|---|
BIT_MODE_LOCAL |
LOCAL |
仅本地（单机、BIT-ID、内存授权等）。 |
BIT_MODE_REMOTE |
REMOTE |
仅远端（云、帐号、集团等）。 |
BIT_MODE_AUTO |
AUTO |
本地与远端都尝试；优先级：本地 > 远端（在已配置远端前提下）。 |
BIT_MODE_CACHE |
CACHE |
云授权 SN 缓存，便于下次免输 SN。 |
BIT_MODE_USB |
USB |
USB 相关授权。 |
LOGIN_MODE_PROCESS |
PROCESS |
集团：按进程占并发点；其它模式无效。 |
LOGIN_MODE_SESSION |
SESSION |
集团：更细粒度会话占点。 |
LOGIN_MODE_HIGH_PRIORITY |
HIGH_PR |
云：高优先级登录可挤占普通登录。 |
LOGIN_MODE_NO_NETWORK |
NO_NETWORK |
禁止库联网。 |
LOGIN_MODE_CHECK_USERNAME |
CHECK_USERNAME |
集团：设备+用户名才视为同一点。 |
LOGIN_MODE_USE_SESSIONID |
USE_SESSIONID |
Logout 不释放点数，由第三方维护心跳。 |
LOGIN_MODE_HIGH_PERFORMANCE |
HIGH_PERFORMANCE |
集团：合并请求降负载。 |
LOGIN_MODE_PERSISTENT_CONN |
PERSISTENT_CONN |
集团长连接。 |
LOGIN_MODE_CREATE_HANDLE_ONLY |
CREATE_HANDLE_ONLY |
仅创建句柄，真正校验推迟到 Query。 |
LOGIN_MODE_CREATE_NEW_HANDLE |
CREATE_NEW_HANDLE |
每次唯一句柄，属性互不干扰。 |
LOGIN_MODE_MID / ACCOUNT / GROUP |
MID / ACCOUNT / GROUP |
按设备、帐号、分组名占点等。 |
C 示例中常写作 LOGIN_MODE(BIT_MODE_REMOTE | LOGIN_MODE_HIGH_PERFORMANCE) 等形式，即用 LOGIN_MODE 宏包装按位或（见 c.md）。
szSN / sn 常见形态（文档）：云平台 SN；#0 / #bitid:0 等形式选 BIT-ID；<口令> 激活口令；SN<口令> 拼接；帐号授权可与密码类参数配合（具体见帐号授权专章）。
4. API 分组：认证与会话（C 名为主，Java 对照）
| 功能 | C API | Java API（文档） |
|---|---|---|
| 登录 | Bit_Login, Bit_LoginEx |
login, loginEx |
| 帐号 Token | Bit_LoginByToken, Bit_LoginByTokenEx |
loginByToken, loginByTokenEx |
| 帐号密码 | Bit_LoginByPassword |
loginByPassword |
| 登出 | Bit_Logout |
logout |
| 浮动迁出 | Bit_Revoke（在线/离线迁出、请求码） |
revoke, revokeOnline |
| 删除本机 SN 数据 | Bit_RemoveSn |
removeSn |
| 手动心跳 | Bit_Heartbeat（10s 内最多触发一次等说明） |
heartbeat |
| Session 控制 | Bit_SessionControl, Bit_SetSessionState |
sessionControl, setSessionState |
5. API 分组：激活与离线/在线升级
| 功能 | C API | Java（BitAnswer，docs/java.md） |
|---|---|---|
| 在线激活/升级 | Bit_UpdateOnline |
void updateOnline(String url, String sn) |
| 取升级请求串 | Bit_GetRequestInfo（绑定类型、设备码 REQ_TYPE_MID 等） |
String getRequestInfo(String sn, BindingType type) |
| 应用升级包 | Bit_ApplyUpdateInfo |
String applyUpdateInfo(String updateInfo) |
| 远程集团应用升级 | Bit_ApplyUpdateInfoEx |
java.md 未收录；若需远程集团升级请以随包接口为准 |
| 用请求串换升级码 | Bit_GetUpdateInfo |
String getUpdateInfo(String url, String sn, String requestInfo) |
典型场景补充
- 在线：
Bit_UpdateOnline(NULL, sn, application_data)；BIT-ID 可用#0等形式。 - 离线：本机
Bit_GetRequestInfo→ 联网换取 License 串 → 本机Bit_ApplyUpdateInfo；涉密场景可用设备码缩短人工传递长度。 - 内存授权：从离线包取
<code>，拼lic://...作为Bit_Login的 url，模式BIT_MODE_LOCAL。
6. API 分组：特征项（功能模块与加密点）
| 功能 | C API | Java API（文档） |
|---|---|---|
| 批量 Query | Bit_BatchBegin, Bit_BatchEnd |
batchBegin, batchEnd |
| 基础占用/释放 | Bit_QueryFeature, Bit_ReleaseFeature |
queryFeature, releaseFeature |
| 集团扩展占用 | Bit_QueryFeatureEx, Bit_ReleaseFeatureEx |
queryFeatureEx, releaseFeatureEx |
| 按名称+版本/队列 | Bit_QueryFeatureEx2, Bit_ReleaseFeatureEx2 |
queryFeatureEx2, releaseFeatureEx2 |
| 查存在/有效期（不占点） | Bit_GetFeatureInfo2, Bit_GetFeatureInfoEx2 |
getFeatureInfo2, getFeatureInfoEx2 |
| Ticket 信息 | Bit_GetTicketInfo |
getTicketInfo |
| 算法特征 | Bit_ConvertFeature |
convertFeature |
| 密钥特征加解密 | Bit_EncryptFeature, Bit_DecryptFeature |
encryptFeature, decryptFeature |
| 读写特征值 | Bit_ReadFeature, Bit_WriteFeature |
readFeature, writeFeature |
文档强调：集团授权下 QueryFeature / ReleaseFeature（及 Ex 系列）需成对使用以正确占用/释放并发用户数；QueryFeatureEx 支持多种 mode（默认非阻塞、尽可能占用、仅检查计数等）。
7. API 分组：配置项（Data）
| 功能 | C API | Java API（文档） |
|---|---|---|
| 读 | Bit_GetDataItem |
getDataItem |
| 写/创建 | Bit_SetDataItem |
setDataItem |
| 枚举数量/名称 | Bit_GetDataItemNum, Bit_GetDataItemName |
getDataItemNum, getDataItemName |
| 删（授权码侧） | Bit_RemoveDataItem |
removeDataItem |
Java 文档对名称/值长度有简要限制说明（如名称最长 128 字节、值 1024 字节量级，以官方为准）。
8. API 分组：信息查询
与 c.md 中 「信息获取」 大节对应。该节除下表外，还包括版本/句柄/诊断等 API（为减少重复，详见 §10）。
| 功能 | C API | 说明（摘要） |
|---|---|---|
| 会话信息 | Bit_GetSessionInfo |
XML 或字段型信息：SN/特征/配置项摘要、服务器时间、授权类型组合、起止日期、离线分钟数等。 |
| 本机/环境信息 | Bit_GetInfo |
已激活 SN 列表、特征列表、集团服务器发现、BIT-ID 列表、升级错误详情等。 |
| 集团服务信息 | Bit_GetServerInfo |
无需先 Login；查集团侧授权/特征等 XML。 |
与 c.md 源码块核对：Bit_GetServerInfo 小节内的函数名被写成 Bit_GeServerInfo（缺字母 t），与章节标题不一致，应视为复制/排版笔误；集成时以 bitanswer.h 为准。
9. API 分组：借出 / 归还（浮动与集团场景扩展）
文档在 C / Java 接口中均用「借出操作」类章节描述。C 名称见下左列；Java（BitAnswer） 见 docs/java.md 及下表。
| C API | Java 方法（docs/java.md） |
|---|---|
Bit_GetBorrowRequest |
String getBorrowRequest(String sn, int durationDay) |
Bit_GetBorrowFeatureRequest |
String getBorrowFeatureRequest(int durationDay, String borrowScope) |
Bit_CheckOutSn |
void checkOutSn(String url, int featureId) |
Bit_CheckOutSnEx |
void checkOutSnEx(String url, int featureId, String xmlScope, int durationDays) |
Bit_CheckOut |
void checkOut(String url, String scope, String featureList, int durationDays) |
Bit_CheckOutFeatures |
void checkOutFeatures(String url, int[] featureList, int durationDays) |
Bit_CheckIn |
void checkIn(String url, int featureId) |
Bit_CheckInEx |
void checkInEx(String url, int featureId, String xmlScope) |
Bit_ApplyBorrowInfo |
void ApplyBorrowInfo(String borrowInfo)（文档锚点为大写 ApplyBorrowInfo；参数类型应以实际 SDK 的 String 为准） |
参数语义、scope / featureList XML 格式等以原文为准。Java 文档注明 applyUpdateInfo 可兼容离线借出串（与 ApplyBorrowInfo 重叠场景见原文）。
10. API 分组：路径、代理、属性与其它工具
对应 c.md 中 「信息获取」 后半（Bit_GetVersion 起）与 「属性设置」 全节。常见于部署与诊断：
| C API | 用途摘要 |
|---|---|
Bit_SetRootPath |
授权文件根路径。 |
Bit_SetProxy |
HTTP/SOCKS 等代理参数。 |
Bit_SetLocalServer |
本地/集团服务发现相关设置（见原文）。 |
Bit_GetProductPath |
产品路径查询。 |
Bit_GetVersion |
库版本。 |
Bit_GetLastError |
上一 API 错误码。 |
Bit_GetNextHandle |
枚举/遍历句柄（见原文）。 |
Bit_SetAttr / Bit_SetCustomInfo |
句柄/会话属性与自定义信息。 |
Bit_TestBitService |
探测集团服务等可达性。 |
Java（docs/java.md）对应：int getVersion() · String getProductPath() · int getLastError() · void testBitService(String url, String sn, int featureId) · void setRootPath(String rootPath) · void setLocalServer(String hostName, int port, int timeout) · void setProxy(String hostName, int port, String userId, String password) · void setAttr(int type, byte[] pValue) · void setCustomInfo(...)（String / int 重载）。未在 java.md 列出：Bit_GetNextHandle 的 Java 对等方法（若需遍历句柄请查随包 JNI 或新版文档）。
附录 A：Java BitAnswer API（依据 docs/java.md）
A.1 类型与构造
| 项 | 说明 |
|---|---|
| 主类 | BitAnswer（实例方法；通过 JNI 调用 native，与 C SDK 同库） |
| 构造方法 | BitAnswer()；BitAnswer(String url, String sn, LoginMode mode)（便捷构造，等价于再调用 login 的用法以官方示例为准） |
| 错误处理 | 多数 API 为 void 或返回数据；int getLastError() 返回当前线程最近一次调用的错误码（成功为 0，见 java.md） |
A.2 文档中出现的枚举 / 参数类型（用于方法签名）
| 名称 | 用途（节选） |
|---|---|
LoginMode |
login / loginEx、构造器第三参数；与 C 侧 LOGIN_MODE 按位语义对应，Java 侧为枚举常量（LOCAL、REMOTE、AUTO、CACHE、USB、PROCESS、SESSION、HIGH_PR、NO_NETWORK、CHECK_USERNAME、USE_SESSIONID、HIGH_PERFORMANCE、PERSISTENT_CONN、CREATE_HANDLE_ONLY、CREATE_NEW_HANDLE、MID、ACCOUNT、GROUP） |
BindingType |
getRequestInfo：EXISTING、LOCAL、USB_STORAGE |
BatchMode |
batchBegin：BIT_BATCH_MODE_CONTINUE、BIT_BATCH_MODE_BREAK |
SessionType |
getSessionInfo：XML_TYPE_SN_INFO、XML_TYPE_FEATURE_INFO、XML_TYPE_DATA_INFO、BIT_SERVER_ADDRESS、BIT_SERVER_TIME、BIT_CONTROL_TYPE 及各日期/次数/离线字段常量（见 java.md） |
InfoType |
getInfo：BIT_INFO_SERVER_ADDRESS、BIT_INFO_SN、BIT_INFO_SN_FEATURE 等 |
ServerInfoType |
getServerInfo：BIT_SERVER_INFO_SN、BIT_SERVER_INFO_SN_FEATURE、BIT_SERVER_INFO_SN_LICENSE 等 |
SessionCtlType |
sessionControl：SESSION_CTL_LOGOUT、SESSION_CTL_CHECK |
setAttr 的 type |
ATTR_HB_RETRY_FAILED_CALLBACK、ATTR_WAIT_TIMEOUT、ATTR_RETRY_COUNT 等（见 java.md） |
setCustomInfo 的 infoId |
CustomInfo：CUSTOM_CLIENT_ID、CUSTOM_OPTION 等（java.md 列至 CUSTOM_GROUP_NAME(0xA)） |
A.3 方法签名全表（与 C 对照）
认证
| Java |
|---|
void login(String url, String sn, LoginMode mode) |
void loginEx(String url, String sn, int featureId, String xmlScope, LoginMode mode) |
void loginByToken(String url, String token) |
void loginByTokenEx(String url, String businessGuid, String token, String idpGuid, String grantType) |
void loginByPassword(String url, String guid, String secret, String account, String password) |
void logout() |
String revoke(String sn) |
void revokeOnline(String url, String sn) |
void removeSn(String sn) |
int heartbeat() |
String sessionControl(String url, String sessionId, SessionCtlType type) |
void setSessionState(int state, byte[] pReserved) |
激活升级（另见 §5 表格）
特征项
| Java |
|---|
void batchBegin(BatchMode mode) · int[] batchEnd() |
int queryFeature(int featureId) · int releaseFeature(int featureId) |
int queryFeatureEx(int featureId, int mode, int required, String scope) · int releaseFeatureEx(int featureId, int consumed, String scope) |
long queryFeatureEx2(String featureName, int mode, int required, String scope) · void releaseFeatureEx2(byte[] ticket, int consumed) |
int getFeatureInfo2(String featureName, String scope) · String getFeatureInfoEx2(String featureName, String scope) |
String getTicketInfo(byte[] ticket, int type)（type 如 BIT_TICKET_TYPR_USERS，原文档拼写如此） |
int convertFeature(int featureId, int para1, int para2, int para3, int para4) |
byte[] encryptFeature(int featureId, byte[] pPlainBuffer) · byte[] decryptFeature(int featureId, byte[] pCipherBuffer) |
int readFeature(int featureId) · void writeFeature(int featureId, int featureValue) |
配置项
| Java |
|---|
byte[] getDataItem(String dataItemName) · void setDataItem(String dataItemName, byte[] dataItemValue) |
int getDataItemNum() · String getDataItemName(int index) · void removeDataItem(String dataItemName) |
（java.md：配置项名称最大 128 字节等限制与 C 侧一致。）
信息获取
| Java |
|---|
String getSessionInfo(SessionType type) · String getInfo(String sn, InfoType type) |
String getServerInfo(String url, String sn, String scope, ServerInfoType type) |
int getVersion() · void testBitService(String url, String sn, int featureId) · String getProductPath() · int getLastError() |
借出操作（另见 §9 表）
A.4 与 C 覆盖差异（据 docs/java.md 全文）
| C API | Java（docs/java.md） |
|---|---|
Bit_ApplyUpdateInfoEx |
未收录 |
Bit_GetNextHandle |
未收录 |
补充：C 侧 Bit_GetRequestInfo 的 BINDING_TYPE 含 REQ_TYPE_MID（设备码）；java.md 在 getRequestInfo 的 BindingType 中仅列出 EXISTING、LOCAL、USB_STORAGE。设备码流程在 Java 是否另有接口，以 随包 SDK / 更新版 java.md 为准。
A.5 文档小瑕疵（复制源）
loginEx说明中「Login 等价于 LoginEx」与 C 页类似，易误解；需包含指定 featureId 时用loginEx。batchBegin正文写「由 Bit_batchEnd 提交」应为batchEnd（Java） /Bit_BatchEnd（C）。ApplyBorrowInfo参数写string应为 JavaString。
11. C API 名称索引（供检索）
下列名称与 c.md 中全部 ## [Bit_…] 小节一致，共 59 个独立函数（其中 Bit_CheckOutSn / Bit_CheckOutSnEx 合并在同一文档小节）。若与头文件有出入以 bitanswer.h 为准：
Bit_ApplyBorrowInfo · Bit_ApplyUpdateInfo · Bit_ApplyUpdateInfoEx · Bit_BatchBegin · Bit_BatchEnd · Bit_CheckIn · Bit_CheckInEx · Bit_CheckOut · Bit_CheckOutFeatures · Bit_CheckOutSn · Bit_CheckOutSnEx · Bit_ConvertFeature · Bit_DecryptFeature · Bit_EncryptFeature · Bit_GetBorrowFeatureRequest · Bit_GetBorrowRequest · Bit_GetDataItem · Bit_GetDataItemName · Bit_GetDataItemNum · Bit_GetFeatureInfo2 · Bit_GetFeatureInfoEx2 · Bit_GetInfo · Bit_GetLastError · Bit_GetNextHandle · Bit_GetProductPath · Bit_GetRequestInfo · Bit_GetServerInfo · Bit_GetSessionInfo · Bit_GetTicketInfo · Bit_GetUpdateInfo · Bit_GetVersion · Bit_Heartbeat · Bit_Login · Bit_LoginEx · Bit_LoginByPassword · Bit_LoginByToken · Bit_LoginByTokenEx · Bit_Logout · Bit_QueryFeature · Bit_QueryFeatureEx · Bit_QueryFeatureEx2 · Bit_ReadFeature · Bit_ReleaseFeature · Bit_ReleaseFeatureEx · Bit_ReleaseFeatureEx2 · Bit_RemoveDataItem · Bit_RemoveSn · Bit_Revoke · Bit_SessionControl · Bit_SetAttr · Bit_SetCustomInfo · Bit_SetDataItem · Bit_SetLocalServer · Bit_SetProxy · Bit_SetRootPath · Bit_SetSessionState · Bit_TestBitService · Bit_UpdateOnline · Bit_WriteFeature
12. 与mgmt/运营侧 API 的边界
开发者控制台还提供 Backoffice API（REST/数据结构），用于授权码、用户、业务等服务端自动化，与上表客户端安全库 API 不同层。若需「控制台可调用的 HTTP API」，请单独以 Backoffice 文档为准。
13. 免责声明
本文档不替代比特授权云官方文档与随 SDK 发布的法律/技术支持条款；集成与合规问题请咨询官方渠道。
14. 对照本地备份的审核结论（2026-04-06）
14.1 docs/c.md
| 项 | 结论 |
|---|---|
| 函数覆盖 | c.md 中列出的全部 Bit 客户端 API 均已在本梳理的分组或 §11 索引中覆盖；无遗漏。 |
| 章节结构 | 「信息获取」后半与「属性设置」对应 §8 / §10，表头已说明。 |
| Bit_GetServerInfo | c.md 代码块误写为 Bit_GeServerInfo；§8 已注释。 |
| Bit_LoginEx 说明 | c.md 中 featured=0 等笔误；本梳理未复述。 |
| 多路径分隔符 | 已标明示例为半角 ,。 |
| 登录模式 | 与 c.md 表一致；已补充 LOGIN_MODE(...) 宏。 |
| §11 索引 | 以 c.md 小节为对齐基准。 |
14.2 docs/java.md
| 项 | 结论 |
|---|---|
| 对等性 | java.md 中 BitAnswer 实例方法与 C API 基本全覆盖；附录 A 为完整签名与枚举清单。 |
| 缺失相对 C | Bit_ApplyUpdateInfoEx、Bit_GetNextHandle 在 java.md 中未出现（§A.4）。 |
getServerInfo |
Java 文档写为 getServerInfo；无 C 页 GeServerInfo 笔误问题。 |
| 借出 | §9 已按 java.md 补全 checkOut* / checkIn* / ApplyBorrowInfo 等 Java 方法表。 |