Bit_BatchBegin

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

BIT_STATUS Bit_BatchEnd(
    BIT_HANDLE       handle,
    BIT_UINT32       *pResultList,
    BIT_UINT32       *pResultListSize)

批量提交Query请求。

参数

handle - [IN] 通过Login函数返回的上下文句柄。
pResultList - [OUT] 按顺序返回每个接口的错误码，0表示成功，非0表示失败，传NULL表示清理添加的批量数据。
pResultListSize - [OUT] 返回调用接口的数量。

示例

// 开启批次
Bit_BatchBegin(handle, BIT_BATCH_MODE_CONTINUE); 
BIT_UINT32 result[3] = { 0 };
BIT_UINT32 resultNum = 0;
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

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时，释放占用的用户数。

示例

BIT_UINT32 featureId = 1;
BIT_UINT32 capacity = 0;
BIT_STATUS status = Bit_QueryFeature(handle, featured, &capacity);
if (status == BIT_SUCCESS) {
    // 特征项1有效
}

Bit_ReleaseFeature

BIT_STATUS Bit_ReleaseFeature (
    BIT_HANDLE      handle,
    BIT_UINT32      featureId,
    BIT_UINT32      *pCapacity)

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

参数

handle - [IN] 通过Login函数返回的上下文句柄。
featureId - [IN] 特征项ID。
pCapacity - [OUT] 当不为NULL时，获取特征项当前可用用户数。

示例

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

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\| BIT_QUERY_TEST）

required - [IN] 请求的用户数，该接口可以调用多次，实际的占用的用户数为，每次调用的最大值。

示例：

第一次：required了10个。

第二次：required了8个，此时总共占用10个。

第三次：required了15个，此时总共占用15个。

pCapacity - [OUT] 当不为NULL时，获取特征项当前可用用户数。
xmlScope - [IN] 可以传入特征项版本。示例“1.0”，“2.0”，如果为空，则匹配任意版本的特征项。

示例

// 占用特征项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

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的输入的版本一致，才可以释放。

示例

// 释放占用特征项ID为8的2个用户数：

BIT_UINT32 capacity = 0;
BIT_STATUS status = Bit_ReleaseFeatureEx (
                                handle,
                                8,
                                2,
                                &capacity,
                                NULL)
if (status == BIT_SUCCESS) {
    // 用户数释放成功
}

Bit_QueryFeatureEx2

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(0x0)	非阻塞占用required个用户数，如果用户数不够将返回错误
BIT_QUERY_AVAILABLE(0x01)	尽可能的占用required个用户数，如果用户数不够将占用剩余用户数。例如：Feature剩余10个用户数。Required需要占用20个，则返回成功，并占用10个用户数。
BIT_QUERY_WAIT(0x03)	加入等待队列，可以设置超时，超时后，将自动返回
BIT_QUERY_QUEUE(0x04)	加入队列，通过Bit_GetTicketInfo可以查看队列状态
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。

required - [IN] 请求的用户数。
xmlScope - [IN] 可以传入特征项版本。示例：“1.0”，“2.1”。
pTicket - [OUT]

示例

// 占用特征项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

BIT_STATUS Bit_ReleaseFeatureEx2 (
    BIT_TICKET      ticket,
    BIT_UINT32      consumed)

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

参数

ticket - [IN] 通过QueryFeatureEx2返回的句柄。
consumed - [IN] 保留值，必须是0。

示例

BIT_STATUS status = Bit_ReleaseFeatureEx2 (ticket, 0);
if (status == BIT_SUCCESS) {
    // 释放ticket占用的用户数
}

特征项Query相关接口比较

函数	特征项ID	特征项名称	特征项版本	一次Query多个用户数	队列	用户数递增/递减
Bit_QueryFeature	支持
Bit_QueryFeatureEx	支持		支持	支持		支持
Bit_QueryFeatureEx2		支持	支持	支持	支持

Bit_GetFeatureInfo2

BIT_STATUS Bit_GetFeatureInfo2 (
    BIT_HANDLE     handle,
    BIT_PCSTR      featureName,
    BIT_PCSTR      xmlScope,
    BIT_INT32      *pExpired)

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

参数

handle - [IN] 通过Login函数返回的上下文句柄。
featureName - [IN] 产品的特征项名称。
xmlScope - [IN] 查找范围，可以通过 xml 格式传入版本，也可以直接传入版本的字符串。

<scope>
   <featureVersion>1.1</featureVersion>
</scope>

或者直接输入："1.1"

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

Bit_GetFeatureInfoEx2

BIT_STATUS BIT 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 格式传入版本，也可以直接传入版本的字符串。

<scope>
   <featureVersion>1.1</featureVersion>
</scope>

或者直接输入："1.1"

pFeatureInfo - [OUT] feature信息存储区地址。
pFeatureInfoSize - [IN/OUT] 会话存储区大小。

Bit_GetTicketInfo

BIT_STATUS BIT_CALLCONV 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信息如下

<?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>4HAYJUOA7I******</sn>             // 占用的是那个sn下的feature
            <controlType>Local/group</controlType>      // 占用的feature类型
        <snInfo/>
        <occFversion>1.0</occFversion>                 // 占用feature的版本
        <occUserNumber>3</occUserNumber>           // 占用feature的点数 
    </occupationInfo>
    <occupationInfo>
        <snInfo>
            <sn>4HAYJUOA7IAADUAB</sn>             // 占用的是那个sn下的feature
            <controlType>Local/group</controlType>      // 占用的feature类型
        <snInfo/>
        <occFversion>2.0</occFversion>                 // 占用feature的版本
        <occUserNumber>7</occUserNumber>           // 占用feature的点数 
    </occupationInfo>
    </occupationInfos>
</ticketInfo>

Bit_ConvertFeature

BIT_STATUS BIT_CALLCONV 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] 变换结果。

示例

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

BIT_STATUS BIT_CALLCONV 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字节。

示例

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

BIT_STATUS BIT_CALLCONV 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字节。

示例

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

BIT_STATUS BIT_CALLCONV Bit_ReadFeature(
    BIT_HANDLE      handle,
    BIT_UINT32      featureId,
    BIT_UINT32      *pFeatureValue);

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

参数

handle - [IN] 通过Login函数返回的上下文句柄。
featureId - [IN] 产品的特征项ID。
pFeatureValue - [OUT] 特征项数据缓存区地址，用于存储读出的数据。

Bit_WriteFeature

BIT_STATUS BIT_CALLCONV Bit_WriteFeature(
    BIT_HANDLE      handle,
    BIT_UINT32      featureId,
    BIT_UINT32      featureValue);

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

参数

handle - [IN] 通过Login函数返回的上下文句柄。
featureId - [IN] 产品的特征项ID。
featureValue - [IN] 特征项数据值。