craftlabs-authorization-sdk/docs/java.md

# 比特授权云 · Java 语言接口（离线摘录）

> 本文档由官网页面离线摘录并整理排版，便于本地检索。官方地址：[https://doc.bitanswer.cn/docs/client-api/java-interface-v2/](https://doc.bitanswer.cn/docs/client-api/java-interface-v2/)

---

## 构造方法详细信息

### BitAnswer

```java
public BitAnswer()
public BitAnswer(String url, String sn, LoginMode mode)
```

## 认证

### login / loginEx

```java
void login (String url,
            String sn,
            LoginMode mode)

void loginEx (String url,
              String sn,
              int featureId,
              String xmlScope,
              LoginMode mode)
```

授权登录。初始化运行环境，获取操作句柄。必须在除升级函数之外的其它操作前执行。根据登录模式的不同可能需要连接授权服务器。

Login 等价于 LoginEx（featureId=0）；当需要登录包含指定特征项的授权时才需要调用LoginEx。

### 参数

- **url** - [IN] 自定义授权服务器地址，包括端口。如未使用自定义授权服务器则为NULL。
- **sn** - [IN] 授权码（SN）字符串。如果为空（空串或NULL）则尝试寻找所有当前本机可用的SN。
- **featureId** - [IN] 登录授权所需要包含的特征项ID。
- **xmlScope** - [IN] 登录范围。用于提供更多的登录条件，格式为标准XML字符串。目前保留，必须为NULL
- **mode** - [IN] 登录模式，按位操作。


| **值**                  | **说明**                                                                                                                                |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **LOCAL**              | 只检查本地授权（单机授权、BIT-ID授权、内存授权）                                                                                                           |
| **REMOTE**             | 只检查远端授权（云授权、帐号授权、集团授权）                                                                                                                |
| **AUTO**               | 既检查本地授权，也检查远端授权（配置了远端IP的条件下） 优先级：本地授权 > 远端授权                                                                                          |
| **CACHE**              | 云授权缓存 由于云授权SN比较难记，但登录时又必须传输，则可以使用该选项将SN串缓存起来，下次使用Login登录时可以不输入SN                                                                      |
| **USB**                | USB授权                                                                                                                                 |
| **PROCESS**            | 按进程模式登录 **集团授权**：普通模式一台机器占用一个用户数，进程模式是一个进程占用一个用户数 **其它授权**：不生效                                                                        |
| **SESSION**            | Session模式登录 **集团授权**：该模式比LOGIN_MODE_PROCESS控制的更细，一次会话占用一个点 **其它授权**：不生效                                                               |
| **HIGH_PR**            | 高优先级登录 **云授权：**用户可以通过高优先级登录来挤掉普通登录。如果登录模式都是高优先级或者普通优先级则不生效 **其它授权：**不生效                                                               |
| **NO_NETWORK**         | 禁用网络 禁止库联网时使用                                                                                                                         |
| **CHECK_USERNAME**     | 检查当前设备的用户名 **集团授权：**默认情况下：一台的设备用户名不一样，会被识别为同一个机器，加了该模式，会识别为不同的设备。即：原来一台设备占用一个点，加了这个选项，“一台设备 + 用户名”占用一个点 **其它授权**：不生效                  |
| **USE_SESSIONID**      | Logout时不释放点数，并由第三方程序维护心跳                                                                                                              |
| **HIGH_PERFORMANCE**   | 使用高性能模式登录 **集团授权：**将Login的两次请求转化为一次请求，可以减少服务负载 **其它授权：**不支持                                                                           |
| **PERSISTENT_CONN**    | 使用长连接模式登录，只有集团授权支持，其它授权不支持 通过长连接可以减少TCP的频繁创建带来的性能损耗，但是会增加服务的socket连接数                                                                 |
| **CREATE_HANDLE_ONLY** | 仅创建handle，不检查license **集团授权：**Login默认情况下会连接集团服务并占用一个用户数，加了该模式之后，在调用Query相关接口时才会连接服务器 **其它授权：**Login默认情况下会检查授权的可用性，加了该模式之后，在Query时才会检查 |
| **CREATE_NEW_HANDLE**  | 创建新handle，每次创建的handle唯一 Login的请求默认都发pid 可以针对每一个handle进行设置属性，不会相互影响                                                                    |
| **MID**                | 按设备占点（当没有设置LOGIN_MODE_ACCOUNT和LOGIN_MODE_GROUP时，默认按设备扣点）                                                                              |
| **ACCOUNT**            | 按帐号占点                                                                                                                                 |
| **GROUP**              | 按分组名占点                                                                                                                                |


### 返回

无

### loginByToken

```java
void loginByToken (String url,
                   String token)
```

帐号授权的登录接口。仅支持两种认证方式，这里是使用比特授权云平台自己产生的access_token进行认证。

### 参数

- **url** - [IN] 服务器地址，可以为空。
- **token** - [IN] 第三方身份源颁发的token或id_token，通过前缀区分。

### 返回

无

### loginByTokenEx

```java
void loginByTokenEx (String url,
                     String businessGuid,
                     String token,
                     String idpGuid,
                     String grantType)
```

帐号授权的登录接口。仅支持两种认证方式，这里是使用OIDC协议产生的id_token认证。

### 参数

- **url** - [IN] 服务器地址，可以为空。
- **businessGuid** - [IN] 业务guid，在比特授权云平台获取。
- **token** - [IN] 第三方身份源颁发的token或id_token，通过前缀区分。
- **idpGuid** - [IN] 第三方身份源guid，在比特授权云平台获取。参数为空表示使用比特授权云平台产生的token进行登录，即Bit_LoginByToken。
- **grantType** - [IN] 授权类型。固定值为“`bitanswer:idp:oidc:id_token`”。

### 返回

无

### loginByPassword

```java
void loginByPassword (String url,
                      String guid,
                      String secret,
                      String account,
                      String password)
```

通过用户名和密码登录帐号授权。

### 参数

- **url** - [IN] 服务器地址，可以为空。
- **guid** - [IN] 业务编号，在比特授权云平台获取。
- **secret** - [IN] 业务密钥，在比特授权云平台获取。
- **account** - [IN] 用户帐号。
- **password** - [IN] 用户密码。

### 返回

无

### logout

```java
void logout()
```

此函数用于释放上下文句柄，退出登录状态，与Login相关接口一一对应。

### 参数

无

### 返回

无

### revoke

```java
String revoke (String sn)
```

从客户端迁出已激活的浮动授权码。授权码迁出后，可以用于其它的客户端。根据输入参数的不同，本函数可用于在线或离线迁出。

### 参数

- **sn** - [IN] 授权码（SN）字符串。

### 返回

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

### revokeOnline

```java
void revokeOnline (String url,
                   String sn)
```

从客户端迁出已激活的浮动授权码。授权码迁出后，可以用于其它的客户端。本函数需要进行网络连接。

### 参数

- **url** - [IN] 服务器地址，可以为空。
- **sn** - [IN] 授权码（SN）字符串。

### 返回

无

### removeSn

```java
void removeSn (String sn)
```

删除指定授权码在本机的授权数据。

### 参数

- **sn** - [IN] 授权码（SN）字符串。

### 返回

无

### heartbeat

```java
int heartbeat()
```

手动心跳，可以无限次调用，10s只会触发一次。

注：当自动心跳停止后，调用该接口可以尝试恢复自动心跳。

### 参数

无

### 返回

心跳期间的重连次数（0表示无重连，大于0表示心跳过程中发生过连接断开并重新连接）。

### sessionControl

```java
String sessionControl (String url,
                       String sessionId,
                       SessionCtlType type)
```

控制或设置session的信息。具体使用场景可参考《浏览器并发控制》文档。

### 参数

- **url** - [IN] 自定义授权服务器地址，包括端口。如未使用自定义授权服务器则为NULL。
- **sessionId** - [IN] 会话ID，登录成功后获取的有效会话标识。
- **type** - [IN] 类型。


| **类型**                      | **说明**             |
| --------------------------- | ------------------ |
| **SESSION_CTL_LOGOUT(0x1)** | 释放session          |
| **SESSION_CTL_CHECK(0x2)**  | 触发心跳并获取sessionId状态 |


### 返回

会话控制结果（字符串格式），根据控制类型返回对应信息。

### setSessionState

```java
void setSessionState (int state,
                      byte[] pReserved)
```

设置客户端的状态为空闲状态或繁忙状态或激活状态。

### 参数

- **state** - [IN] 设置客户端的状态选项。


| **值**                    | **说明**                                             |
| ------------------------ | -------------------------------------------------- |
| **SESSION_STATE_UNSET**  | 默认值，表示不设置客户端的状态，服务端根据心跳状态来维护session，心跳断开则释放session |
| **SESSION_STATE_IDLE**   | 表示设置客户端为空闲态，服务端会在空闲时间超过设10分钟后自动释放session           |
| **SESSION_STATE_BUSY**   | 表示设置客户端为繁忙状态，服务端不会自动释放，直到心跳断开或者客户端主动释放             |
| **SESSION_STATE_ACTIVE** | 表示设置客户端为活跃状态，重新计算空闲时间                              |


### 返回

无

## 激活升级

### updateOnline

```java
void updateOnline (String url,
                   String sn)
```

此函数用于与授权服务器在线连接，自动完成本地授权的升级操作。本函数需要进行网络连接。

### 参数

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

### 返回

无

### getRequestInfo

```java
String getRequestInfo (String sn,
                       BindingType type)
```

获取当前运行环境的升级请求码，用于发起本地授权激活及升级请求。

### 参数

- **sn** - [IN] 授权码（SN）字符串。如果为空（空串或NULL）则尝试寻找所有当前本机可用的SN
- **type** - [IN] 本地授权绑定类型。

### type类型

- **EXISTING** - 使用当前绑定类型，对已激活授权码进行升级时使用。
- **LOCAL** - 使用本机指纹进行绑定
- **USB_STORAGE** - 使用USB存储器进行绑定

### 返回

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

### applyUpdateInfo

```java
String applyUpdateInfo (String updateInfo)
```

应用升级码完成本地授权激活或升级。本函数必须在获取请求码的同一环境下执行。

### 参数

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

### 返回

确认码，记录升级状态，可在控制台上解析。

### getUpdateInfo

```java
String getUpdateInfo (String url,
                      String sn,
                      String requestInfo)
```

使用请求码与授权服务器进行连接，获取升级码。本函数需要进行网络连接。

### 参数

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

### 返回

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

## 特征项操作

### batchBegin

```java
void batchBegin (BatchMode mode)
```

开启批量Query模式，调用此API后调用的所有Query相关API，全部由Bit_batchEnd接口批量提交连接集团服务。

### 参数

- **mode** - [IN] 批量模式，详见BatchMode枚举。
- **BatchMode类型**
  - BIT_BATCH_MODE_CONTINUE- 批量提交过程中，遇到失败的接口会记录错误信息，并且继续执行
  - BIT_BATCH_MODE_BREAK (0x01) 批量提交过程中，遇到失败的接口会记录错误信息，直接返回错误

### 返回

无

### batchEnd

```java
int[] batchEnd()
```

批量提交Query请求。

### 参数

无

### 返回

批量请求的执行结果数组（每个元素对应一个Query请求的错误码，0表示执行成功，非0表示对应请求失败），结果数组顺序与Query请求调用顺序一致。

### queryFeature

```java
int queryFeature (int featureId)
```

开发商可以对软件的某个功能进行单独授权，当程序运行该模块时，可以通过该接口检查是否可用。

### 参数

- **featureId** - [IN] 产品的特征项ID。

### 返回

当不为NULL时，获取特征项当前可用用户数。

### releaseFeature

```java
int releaseFeature (int featureId)
```

释放所占用的用户数，该函数和Bit_QueryFeature一一对应。

### 参数

- **featureId** - [IN] 产品的特征项ID。

### 返回

当不为NULL时，获取特征项当前可用用户数。

### queryFeatureEx

```java
int queryFeatureEx (int featureId,
                    int mode,
                    int required,
                    String scope)
```

集团授权专用，该接口支持占用指定用户数，支持通过特征项版本进行检查。

### 参数

- **featureId** - [IN] 产品的特征项ID。
- **mode** - [IN] QueryEx的登录模式。
- **required** - [IN] 表示需要占用的总用户数，总用户数包括当前设备已经占用的用户数，如果传入的数量大于当前特征项的最大用户数，则占用全部用户数。
- **scope** - [IN] 特征项支持小数版本，可以通过xml格式传入版本，也可以直接传入版本的字符串。

### mode类型

- **BIT_QUERY_DEFAULT** - 非阻塞登录，占用required个用户数，如果用户数不够将返回错误，pCapacity 保存剩余用户数。
- **BIT_QUERY_AVAILABLE** - 尽可能的占用 required（不能为 0）个用户数，如果用户数不够将占用剩余的用户数，pCapacity 保存当前申请到的用户数。
- **BIT_QUERY_CHECK** - pCapacity 返回总共占用的用户数,required 必须为 0。

### 返回

特征项数据缓存区地址，用于存储读出的数据，根据mode参数的不同返回剩余用户数或者已占用户数。

### releaseFeatureEx

```java
int releaseFeatureEx (int featureId,
                      int consumed,
                      String scope)
```

集团授权专用，释放指定的用户数。该接口与Bit_QueryFeatureEx对应。

### 参数

- **featureId** - [IN] 产品的特征项ID。
- **consumed** - [IN] 需要释放的用户数，传0代表释放所有用户数，如果传入的释放数大于当前登录的用户数则释放所有用户数。
- **scope** - [IN] 特征项支持小数版本，可以通过xml格式传入版本，也可以直接传入版本的字符串。

### 返回

特征项数据缓存区地址，用于存储读出的数据，返回已释放的用户数。

### queryFeatureEx2

```java
long queryFeatureEx2 (String featureName,
                        int mode,
                        int required,
                        String scope)
```

可以使用“特征项名称 + 特征项版本”进行用户数占用，支持队列模式。

### 参数

- **featureName** - [IN] 产品的特征项名称。
- **mode** - [IN] QueryEx2的登录模式。
- **required** - [IN] 表示需要占用的用户数,多次调用可累加占用用户数。
- **scope** - [IN] 特征项支持小数版本，可以通过 xml 格式传入版本，也可以直接传入版本的字符串。

### mode类型

- **BIT_QUERY_DEFAULT** - 非阻塞登录，占用required个用户数，如果用户数不够将返回错误。
- **BIT_QUERY_AVAILABLE** - 尽可能的占用 required（不能为 0）个用户数，如果用户数不够将占用剩余的用户数。
- **BIT_QUERY_WAIT** - 阻塞队列登录，如果用户数不够，将加入队列阻塞等待。
- **BIT_QUERY_QUEUE** - 非阻塞队列登录，如果用户数不够，将加入队列，不会阻塞等待。
- **BIT_QUERY_TEST** - 测试特征项版本是否可用，与DEFAULT、WAIT、QUEUE搭配使用。

### 返回

输入时指针变量的值必须为0，输出时为当前Query请求的句柄。

### releaseFeatureEx2

```java
void releaseFeatureEx2 (byte[] ticket,
                        int consumed)
```

释放ticket所占用的用户数。该函数和Bit_QueryFeatureEx2一一对应。

### 参数

- **ticket** - [IN] 通过QueryFeatureEx2函数返回的上下文句柄。
- **consumed** - [IN] 需要释放的用户数，目前默认必须传0，代表释放所有用户数。

### 返回

无

### getFeatureInfo2

```java
int getFeatureInfo2 (String featureName,
                     String scope)
```

检查特征项是否存在，不会占用授权码或特征项的用户数，获取特征项的剩余有效期。

### 参数

- **featureName** - [IN] 产品的特征项名称。
- **scope** - [IN] 特征项的版本，可以通过xml格式传入版本，也可以直接传入版本的字符串。

### 返回

返回该特征项的剩余有效期，正数代表剩余有效期，负数代表过期天数，36500代表永久有效。

### getFeatureInfoEx2

```java
String getFeatureInfoEx2 (String featureName,
                          String scope)
```

获取指定feature的信息，以XML格式返回。

### 参数

- **featureName** - [IN] 特征项名称，需与比特授权云平台配置的特征项名称一致。
- **scope** - [IN] 查询范围，无需指定版本则传空串。可以通过 xml 格式传入版本，也可以直接传入版本的字符串。示例：

```xml
<scope>
   <featureVersion>1.1</featureVersion>
</scope>
<!-- 或者直接输入：'1.1' -->
```

### 返回

特征项信息（XML格式字符串），包含特征项ID、类型、有效期、数据长度等内容。

### getTicketInfo

```java
String getTicketInfo (byte[] ticket,
                      int type)
```

获取ticket信息。

### 参数

- **ticket** - [IN] 通过QueryFeatureEx2函数返回的上下文句柄。
- **type** - [IN] 获取ticket的信息类型。

### type类型

- **BIT_TICKET_TYPR_USERS** - 获取当前 ticket 占用的用户数

### 返回

ticket信息存储区地址。

### convertFeature

```java
int convertFeature (int featureId,
                    int para1,
                    int para2,
                    int para3,
                    int para4)
```

使用“算法”类型的特征项对输入参数进行变换操作，得到唯一对应的4字节结果。

### 参数

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

### 返回

变换结果。

### encryptFeature

```java
byte[] encryptFeature (int featureId,
                       byte[] pPlainBuffer)
```

使用“密钥”类型的特征项对输入的明文进行加密，返回密文结果。

### 参数

- **featureId** - [IN] 产品的特征项ID。
- **pPlainBuffer** - [IN] 数据缓存区地址，用于存储明文数据。

### 返回

数据缓存区地址，用于存储密文数据。

### decryptFeature

```java
byte[] decryptFeature (int featureId,
                       byte[] pCipherBuffer)
```

使用“密钥”类型的特征项对输入的密文进行解密，返回明文结果。

### 参数

- **featureId** - [IN] 产品的特征项ID。
- **pCipherBuffer** - [IN] 数据缓存区地址，用于存储密文数据。

### 返回

数据缓存区地址，用于存储明文数据。

### readFeature

```java
int readFeature (int featureId)
```

读取特征项的数据内容，可用于“只读”和“读写”特征类型。

### 参数

- **featureId** - [IN] 产品的特征项ID。

### 返回

特征项数据缓存区地址，用于存储读出的数据。

### writeFeature

```java
void writeFeature (int featureId,
                   int featureValue)
```

更新“读写”类型的特征项的数据内容。

### 参数

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

### 返回

无

## 配置项操作

### getDataItem

```java
byte[] getDataItem (String dataItemName)
```

读取指定的配置项数据。

### 参数

- **dataItemName** - [IN] 数据项名称，名称最大长度为128字节。

### 返回

数据项数据缓存区地址，数据最大长度为1024字节。

### setDataItem

```java
void setDataItem (String dataItemName,
                  byte[] dataItemValue)
```

创建或更新配置项。如果相同名称的配置项存在，则会更新其中的数据；否则将添加新的授权码配置项。

### 参数

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

### 返回

无

### getDataItemNum

```java
int getDataItemNum()
```

此函数用于获取可访问配置项的数量，一般用于配置项的枚举操作。

### 参数

无

### 返回

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

### getDataItemName

```java
String getDataItemName (int index)
```

根据配置项索引获取其名称，一般用于配置项的枚举操作。

### 参数

- **index** - [IN] 数据项索引。

### 返回

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

### removeDataItem

```java
void removeDataItem (String dataItemName)
```

删除指定的配置项。该操作无法删除通过控制台设置的产品配置项或模版配置项。

### 参数

- **dataItemName** - [IN] 数据项名称，名称最大长度为128字节。

### 返回

无

## 信息获取

### getSessionInfo

```java
String getSessionInfo (SessionType type)
```

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

### 参数

- **type** - [IN] 获取会话信息类型。

### type类型

- **XML_TYPE_SN_INFO** - 获取当前会话中授权码的授权信息，以XML结构表示。未作限制的授权项将不会返回
- **XML_TYPE_FEATURE_INFO** - 获取当前会话中授权码的特征项信息，以XML结构表示
- **XML_TYPE_DATA_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** - 强制认证最大离线时间（分钟）

### 返回

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

### getInfo

```java
String getInfo (String sn,
                InfoType type)
```

获取本地授权信息。

### 参数

- **sn** - [IN] 授权码（SN）字符串
- **type** - [IN] 获取信息类型。

### type类型

- **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信息数据。

### getServerInfo

```java
String getServerInfo (String url,
                      String sn,
                      String scope,
                      ServerInfoType type)
```

获取集团服务的license信息，数据以XML格式返回。调用此函数前客户端不需要执行登录操作。

### 参数

- **url** - [IN] 自定义集团服务器地址，包括端口。如未使用自定义服务器则为NULL。
- **sn** - [IN] 授权码（SN）字符串。如果为空（空串或NULL）则查询所有可用授权的license信息。
- **scope** - [IN] 查询范围，XML格式字符串，支持过滤条件；如无需过滤则传空串。
- **type** - [IN] 查询类型，详见ServerInfoType枚举，指定返回license信息的类型。类型：
  - BIT_SERVER_INFO_SN 获取集团服务的授权码列表
  - BIT_SERVER_INFO_SN_FEATURE 获取集团服务的授权码的特征项列表
  - BIT_SERVER_INFO_SN_LICENSE 获取集团服务的授权码的授权信息
  - BIT_SERVER_INFO_FEATURE_LICENSE 获取集团服务的特征项的授权信息
  - BIT_SERVER_INFO_SN_USERS 获取集团服务被占用的SN的用户信息
  - BIT_SERVER_INFO_FEATURE_USERS 获取集团服务被占用的feature的用户信息

### 返回

集团服务license信息（XML格式字符串），包含授权有效期、特征项列表、可用用户数等内容。

### getVersion

```java
int getVersion()
```

获取客户端安全库版本号。

### 参数

无

### 返回

客户端安全库版本号。

### testBitService

```java
void testBitService (String url,
                     String sn,
                     int featureId)
```

测试集团授权的特征项是否可用，不会占用授权码或特征项的用户数。

### 参数

- **url** - [IN] 自定义授权服务器地址，包括端口。如未使用自定义授权服务器则为NULL。
- **sn** - [IN] 授权码（SN）字符串。如果为空（空串或NULL）则尝试寻找所有当前本机可用的SN
- **featureId** - [IN] 登录授权所需要包含的特征项ID

### 返回

无

### getProductPath

```java
String getProductPath()
```

获取授权存储目录。

### 参数

无

### 返回

数据缓存区地址，用于存储授权目录。

### getLastError

```java
int getLastError()
```

获取上一个API调用返回的错误码。

### 参数

无

### 返回

上一个API调用的错误码（0表示成功，非0表示失败）。

### 说明

仅返回当前线程中最近一次API调用的错误码；若最近一次调用成功，则返回0。

## 属性设置

### setAttr

```java
void setAttr (int type,
              byte[] pValue)
```

设置全局配置或当前会话的配置。

### 参数

- **type** - [IN] 设置函数功能类型。

### type类型

- **ATTR_HB_RETRY_FAILED_CALLBACK** - 心跳回调函数
- **ATTR_WAIT_TIMEOUT** - 阻塞队列超时时间，最小16秒，最大24小时，默认是一直等待
- **ATTR_RETRY_COUNT** - 客户端连接服务的重试次数。最小0次，最大1024次。默认是0次
- **ATTR_RETRY_INTERVAL** - 客户端连接服务的重试间隔，最小是10秒，最大是4小时，默认是20秒
- **ATTR_CONNECT_TIMEOUT** - 网络连接超时时间，最小是1秒，最大是32秒，默认是3秒
- **ATTR_CONNECT_RETRY_COUNT** - 网络连接重试次数，最小是0次，最大是10次，默认是3次
- **pValue** - [IN] 阻塞队列超时时间或者是回调函数地址等。

### 返回

无

### setProxy

```java
void setProxy (String hostName,
               int port,
               String userId,
               String password)
```

设置代理服务的地址和端口。

### 参数

- **hostName** - [IN] 代理服务所在机器的IP地址。
- **port** - [IN] 客户端应用程序的通讯端口，默认为 8273。
- **userId** - [IN] 代理服务所在机器的用户名。
- **password** - [IN] 代理服务所在机器的密码。

### 返回

无

### setCustomInfo

```java
void setCustomInfo (int infoId,
                    String infoData)
```

设置客户端运行自定义信息，需要在程序的最开始调用。infoId定义详见CustomInfo类型。

### 参数

- **infoId** - [IN] 自定义信息ID，详见CustomInfo枚举定义。目前除了CUSTOM_OPTION均可使用该方法。
- **infoData** - [IN] 自定义信息数据，字符串格式。

### 返回

无

```java
void setCustomInfo (int infoId,
                    int infoData)
```

设置客户端运行自定义信息，需要在程序的最开始调用。infoId定义详见CustomInfo类型。

### 参数

- **infoId** - [IN] 自定义信息ID，详见CustomInfo类型。目前仅针对CUSTOM_OPTION类型使用该方法。
- **infoData** - [IN] 自定义信息数据，整型格式。CustomInfo类型：
  - CUSTOM_CLIENT_ID(1), - 自定义终端标识，配置后该自定义标识会发送给服务器并用于今后的机器指纹匹配
  - CUSTOM_ACCOUNT_LOCAL(2), - 自定义客户端用户帐号，用于集团服务标识客户端用户
  - CUSTOM_COMMENT(3), - 自定义客户端登录注释，用于集团服务管理员获取用户登录请求信息
  - CUSTOM_OPTION(4), - 选项标志位（int类型）
  - CUSTOM_SERVICE_INFO(5), - 服务信息
  - CUSTOM_PRODUCT_CODE(6), - 自定义授权目录名称
  - CUSTOM_ACCOUNT_DEVELOPER(7), - 自定义登录帐号，用于帐号授权 （既使用account登录，又设置了此选项，则直接忽略）
  - CUSTOM_VENDOR_CODE(8), - 自定义开发商信息目前仅用于自定义环境变量名称
  - CUSTOM_HTTP_HEADER(9), - 自定义HTTP头，所有联网的请求都会自带这个请求头
  - CUSTOM_GROUP_NAME(0xA); - 设置自定义分组名

### setRootPath

```java
void setRootPath (String rootPath)
```

设置授权文件的存储路径。

### 参数

- **rootPath** - [IN] 数据缓存区地址，用于存储授权文件的路径。

### 返回

无

### setLocalServer

```java
void setLocalServer (String hostName,
                     int port,
                     int timeout)
```

设置集团服务的地址和端口。

### 参数

- **hostName** - [IN] 集团服务所安装机器的IP地址。
- **port** - [IN] 客户端应用程序的通讯端口，默认为 8273。
- **timeout** - [IN] 客户端超时秒数。

### 返回

无

## 借出操作

### getBorrowRequest

```java
String getBorrowRequest (String sn,
                         int durationDay)
```

获取借出请求串，用来离线借出。

### 参数

- **sn** - [IN] 授权码（SN）字符串。如果为空（空串或NULL）则尝试寻找所有当前本机可用的SN。
- **durationDay** - [IN] 借出有效期，单位为天，需小于等于授权码允许的最大借出天数。

### 返回

离线借出请求串，用于后续离线借出操作。

### getBorrowFeatureRequest

```java
String getBorrowFeatureRequest (int durationDay,
                                String borrowScope)
```

获取借出请求串，该接口支持指定特征项借出。

### 参数

- **durationDay** - [IN] 借出有效期，单位为天，需小于等于授权码允许的最大借出天数。
- **borrowScope** - [IN] 指定借出的特征项范围，示例：

```xml
<features>
    <feature id='1' days='3'/>
    <feature id='2' days='3'/>
    …
</features>
```

### checkOutSn

```java
void checkOutSn (String url,
                 int featureId)
```

从授权服务器在线借出一个完整的授权码，以允许客户端服务器单独使用。被借出的授权码必须具有可借出属性，并在客户端成功借出后减少一个可用用户数。被借出的用户数在到期后将自动返还给服务器。

### 参数

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

### 返回

无

### checkOutSnEx

```java
void checkOutSnEx (String url,
                   int featureId,
                   String xmlScope,
                   int durationDays)
```

从授权服务器在线借出一个完整的授权码，以允许客户端服务器单独使用。被借出的授权码必须具有可借出属性，并在客户端成功借出后减少一个可用用户数。被借出的用户数在到期后将自动返还给服务器。

### 参数

- **url** - [IN] 集团授权服务器地址，包括端口。如输入NULL，则使用配置文件地址；如输入 * 号，则使用广播查找地址。
- **featureId** - [IN] 指定借出授权码需要包含的特征项ID，为 0 则寻找第一个可借出授权码。
- **xmlScope** - [IN] 用于指定借出的参数，格式：`<scope><type>ws</type><sn>xxxx</sn></scope>`，type设定为ws时表示从云授权服务器借出和归还。
- **durationDays** - [IN] 借出有效期，单位为天，需小于等于授权码允许的最大借出天数。

### 返回

无

### checkOut

```java
void checkOut (String url,
               String scope,
               String featureList,
               int durationDays)
```

从授权服务器在线借出授权码或者特征项。

### 参数

- **url** - [IN] 自定义授权服务器地址，包括端口。如未使用自定义授权服务器则为NULL。
- **scope** - [IN] 借出范围。示例：

```xml
<scope>
    <type>ws</type>
    <sn>xxx</sn>
</scope>

说明：
type：借出类型。目前仅支持ws，表示从外网借出（针对云授权和集团授权）
sn：指定借出的SN
```

- **featureList** - [IN] 特征项列表，指定借出的特征项列表，如果不传则借出整个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时，如果指定了版本，则直接大于等于借出版本的特征项，只借一个，如果没有指定版本，则该特征项的所有版本都借出一个。
```

- **durationDays** - [IN] 借出有效期，单位为天，需小于等于授权码允许的最大借出天数。

### 返回

无

### checkOutFeatures

```java
void checkOutFeatures (String url,
                       int[] featureList,
                       int durationDays)
```

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

### 参数

- **url** - [IN] 集团授权服务器地址，包括端口。如输入NULL，则使用配置文件地址；如输入 * 号，则使用广播查找地址。
- **featureList** - [IN] 特征项列表，指定借出的特征项列表，如果不传则借出整个SN。
- **durationDays** - [IN] 借出有效期，单位为天，需小于等于授权码允许的最大借出天数。

### 返回

无

### checkIn

```java
void checkIn (String url,
              int featureId)
```

提前返还从集团授权服务器借出的授权。要提前返还授权，该授权码必须具有允许提前返还属性。

### 参数

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

### 返回

无

### checkInEx

```java
void checkInEx (String url,
                int featureId,
                String xmlScope)
```

提前返还从授权服务器借出的授权。要提前返还授权，该授权码必须具有允许提前返还属性。

### 参数

- **url** - [IN] 集团授权服务器地址，包括端口。如输入NULL，则使用配置文件地址；如输入 * 号，则使用广播查找地址。
- **featureId** - [IN] 指定要返还授权码需要包含的特征项ID，为 0 则寻找第一个可返还授权码。
- **xmlScope** - [IN] 用于指定借出的参数，格式：`<scope><type>ws</type><sn>xxxx</sn></scope>`，type设定为ws时表示从云授权服务器借出和归还。

### 返回

无

### ApplyBorrowInfo

```java
void ApplyBorrowInfo (string borrowInfo)
```

客户端应用离线借出串，ApplyUpdateInfo可以兼容该接口。

### 参数

- **borrowInfo** - [IN] 离线借出请求串，通过getBorrowRequest或getBorrowFeatureRequest接口获取。

### 返回

无