如何使用灵云SDK

SDK发布包中有示例代码工程，开发者可直接导入工程以了解每种能力。 此处我们以HWR为例描述灵云SDK的基本调用流程。

1. 初始化灵云系统

首先，我们需要初始化整个灵云SDK的SYS模块。无论我们使用什么具体的能力，这一步都是必须的。

HCI_ERR_CODE errCode;

char * pszConfig = 
        "developerKey=01234567890,appKey=1234abcd,"
        "cloudUrl=http://api.hcicloud.com:9999"
        "authPath=document,"
        "logFileSize=500,logLevel=5,logFilePath=document/log/,logFileCount=10";

errCode = hci_init(pszConfig);
if (errCode != HCI_ERR_NONE)
{
        // 失败了
}

在使用时，需要将 developerKey, appKey, cloudUrl 这几项替换为由捷通分配给开发者的应用账号信息及云服务地址。 另外，需要确认authPath, logFilePath所指定的路径存在并且具有写权限。

如果 hci_init() 函数返回 HCI_ERR_NONE，表示成功，否则表示失败。返回值不是 HCI_ERR_NONE 一般都表示失败， 可以根据具体返回值以及日志文件排查错误。

2. 获取授权

在灵云系统初始化成功后，第一次使用各项能力之前，我们还需要使用 hci_check_auth() 函数去云端获取授权。一般我们可以先判断当前的授权的过期时间来进行授权获取。

//获取过期时间
int64 expire_time;
int64 current_time = (int64)time( NULL );
HCI_ERR_CODE err_code = hci_get_auth_expire_time( &expire_time );
if( err_code == HCI_ERR_NONE )
{
    //获取成功则判断是否过期
    if( expire_time > current_time )
    {
        //没有过期
        printf( "auth can use continue\n" );
        return true;
    }
}
//获取过期时间失败或已经过期
//手动调用更新授权
err_code = hci_check_auth();
if( err_code == HCI_ERR_NONE )
{
    //更新成功
    printf( "check auth success \n" );
    return true;
}
else
{
    //更新失败
    printf( "check auth return (%d:%s)\n", err_code ,hci_get_error_info(err_code));
    return false;
}

从云端拿到的授权文件会缓存在 hci_init() 时所提供的 authPath 路径下。以后使用会直接使用此文件， 不需要再到云端下载。但授权文件都有一个过期时间，一旦过期了，在一周的宽限期内，仍可以继续使用相应能力， 但超出宽限期，将无法再使用相应的能力。因此在过期时间到了之后必须及时到云端更新授权文件。

3. 设置当前用户

在获取授权文件之后就可以设置当前用户,可选。

hci_set_current_userid("userid");

设置了当前用户，就可以让每次请求和具体用户相关，这样在不同的设备上就可以考虑共享用户。关于用户相关接口参见 用户模块

4. 初始化HWR能力

如果使用手写识别能力，我们还需要初始化HWR能力引擎

char * pszHwrInitConfig = "dataPath=document/hwr,initCapKeys=hwr.local.freestylus";
errCode = hci_hwr_init(pszHwrInitConfig);

如果我们使用的是本地能力，需要用 initCapKeys 配置项指定在后面将会使用哪种本地能力。另外，还需要使用 dataPath 配置项指定本地资源（模型库文件）所在的路径。 这样系统会检查一下所用到的本地能力的资源是否完整可用。

如果使用的是云端能力，这里的配置串可以为空。

5. 开启HWR识别会话

在HWR能力初始化之后，需要通过开启识别会话来启用一种具体的能力，如下所示：

int nSessionId = 0;
char * pszSessionConfig = "capKey=hwr.local.freestylus";
errCode = hci_hwr_session_start(pszSessionConfig, &nSessionId);

示例中使用 capKey配置项指定了所要使用的能力为本地的连写识别引擎。 返回的 nSessionId 标识了此次会话，将来会使用此Id进行识别。

备注：多线程调用过程中需要不同的线程使用不同的会话ID来进行识别，在session层次上多线程安全。

6. 识别

short g_StrokeData[]=
{
        103 ,283 ,105 ,283 ,107 ,283 ,113 ,283 ,120 ,283,
        129 ,283 ,138 ,283 ,146 ,283 ,156 ,283 ,162 ,283,
        ...
        -1 ,0 , -1, -1
};

char * strRecogConfig = "";
HWR_RECOG_RESULT hwrRecogResult;
errCode = hci_hwr_recog( nSessionId, g_StrokeData, sizeof(g_StrokeData), pszRecogConfig, &hwrRecogResult );

识别时，nSessionId 为上一步 hci_hwr_session_start() 所返回的会话标识，g_StrokeData是笔迹数据, 由于没有特殊的识别配置项，pszRecogConfig这里设为空，识别后的返回结果将放在 hwrRecogResult 结构体中。

随后，我们打印结果：

for( int i = 0; i < hwrRecogResult.uiResultItemCount; ++i )
{
        HWR_RECOG_RESULT_ITEM& item = hwrRecogResult.phwrRecogResultItemList[i];
        printf("result[%d]: %s\n", i, item.pszResult);
}

这里我们打印出了一次识别结果的多个候选内容。注意，我们的输出字符串内容都统一为 UTF8编码，因此在某些平台下输出可能需要转码操作，这里不做展示。

最后我们释放识别结果所占用的内存：

errCode = hci_hwr_free_recog_result(&hwrRecogResult);

这样，就完成了一次识别操作。在一个识别会话中，可以重复进行多次识别操作。

7. 关闭HWR识别会话

不再需要使用某个识别会话后，需要关闭识别会话。

errCode = hci_hwr_session_stop(nSessionId);

8. 终止HWR能力

如果所有的识别会话都已关闭，而且不需要再使用HWR能力了，我们可以终止HWR能力

errCode = hci_hwr_release();

9. 终止灵云系统

最后，我们终止灵云系统。

errCode = hci_release();