系统模块

以下描述了如何使用灵云系统模块。

1. 初始化/终止

在使用灵云各项能力之前，都必须使用 hci_init() 函数进行灵云系统的初始化。使用完毕， 需要使用 hci_release() 进行释放。

// 初始化灵云系统
char * pszConfig = 
        "developerKey=01234567890,appKey=1234abcd"
        "cloudUrl=http://api.hcicloud.com:9999,autoCloudAuth=no,"
        "authPath=document,"
        "logFileSize=500,logLevel=5,logFilePath=document/log/,logFileCount=10";

errCode = hci_init(pszConfig);

// 正常使用灵云各项功能
...

// 最后终止灵云系统
errCode = hci_release();

hci_init() 初始化时候，如下一些配置项比较关键：

1. developerKey, appKey
   这两项标识了具体的开发者和应用程序信息，灵云系统会根据这些项给予应用不同服务访问权限。 使用时必须替换为由捷通分配给开发者的应用账号信息。
   
   
2. cloudUrl
   表示云端授权地址。即使只使用本地的端能力，我们也需要这个地址去获取授权文件。 因此，这里也必须替换为捷通分配给开发者的授权地址。
   
   
3. authPath
   表示授权文件所在路径，灵云会将从云端下载下来的授权文件缓存在这里，因此，此路径必须有可写的权限。

其它参数的含义请查看 hci_init() 函数说明。

2. 获取授权文件

第一次使用时，必须使用 hci_check_auth() 从云端获取授权文件。授权文件中规定了此应用可以使用的灵云能力， 以及到期的时间。在随后使用灵云能力时，系统都会检查此授权文件，如果没有相应的授权，或者过期时间（加上宽限期）已到， 将无法使用。

授权文件会缓存在 hci_init() 时所提供的 authPath 路径下。在过期前，系统会直接使用此文件，不需要再到云端下载。 但一定要保证在过期之后及时到云端更新授权文件。具体的更新方法请参见 更新授权文件。

如果是终端数量授权的方式，在某个终端第一次获取授权时候，后台会检查已经注册的终端数量， 如果已经超过允许的值，本函数将会失败，也即新的终端将无法获得有效授权，因此无法使用灵云能力。

如果合同约定了合同期限，当合同期限到期后，也将获取不到有效的终端授权文件。

终端唯一标识和终端类型相关，此项由灵云系统根据设备情况自动获取，一旦获得也会缓存下来。 因此同一个终端多次获取授权，不会认为是多个终端。但如果缓存被删除，或者应用重装， 当系统重新获得时有极小的可能得到不同的标识。

授权文件和终端唯一标识是绑定的，因而无法直接在另外的终端上使用。

开发者可以使用 hci_get_auth_expire_time() 获取当前授权过期时间，当此函数返回错误或者授权过期时间已经到了的时候， 再调用 hci_check_auth()函数到云端下载授权文件。

为了防止用户在授权到期时正好无法联网更新授权，灵云设置了一周的宽限期，在授权文件到期后一周，仍然可以访问授权的能力。 但超出宽限期，将无法使用。应用需要在这一周宽限期内，更新到最新的授权文件。

3. 获取可用能力列表

开发者可以通过 hci_get_capability_list() 函数，获得当前授权文件中可用的能力列表，以及每种能力的一些属性。 注意，这里只返回系统中可用的能力，如果授权文件已经过期而不能使用，这里将不会返回相应的能力。

CAPABILITY_LIST capList;

errCode = hci_get_capability_list(NULL, &capList);

// 循环获取能力列表
for ( int nItemIndex = 0; nItemIndex < capList.uiItemCount; nItemIndex ++ ) {
        //　capkey
        strCapkey= capList.pItemList[nItemIndex].pszCapKey;
}

hci_free_capability_list(&capList);

以上示例获取了所有的能力。也可以通过下述方式得到某一类或者某几类能力列表。

errCode = hci_get_capability_list("tts", &capList);
errCode = hci_get_capability_list("tts;asr", &capList);

通过这些函数，开发者可以确认下载的授权文件是否正确。或者，在有些情况下，可以得到所有可用的能力让用户选择。

4. 上传用户历史数据

当采用本地识别能力时，灵云SDK会将用户的请求数据（包括用户的确认结果）缓存在本地， 开发者可以将这些数据发送到云端，来帮助灵云学习用户的声音习惯，以便建立针对此用户的个性化模型。

上传用户历史数据的方式在PC等联网条件不受限的情况下会工作得很好， 但对于移动终端应用等对网络条件和流量比较敏感的情况来说， 最好由开发者自行决定上传的时机， 这样可控性更强，例如可以在WiFi打开的时候才进行用户数据上传等等。

本地缓存的用户数据有一个大小的上限，当超过这个上限时，更老的数据将被清除。因此即使一直不上传声音数据， 缓存的用户数据也不会无限增长。