# 接口说明

Linux 的接口请以头文件为准，在头文件中有极为详细的使用说明。本文档是辅助解释作用。某些显而易见的数据结构和定义本文档没有具体解释，请参考代码。

# Device层接口

Device层接口是针对设备层面的操作接口，如登录、处理好友/绑定关系、配置日志等。在头文件中有详细的说明，本说明文档同步进行总结和解释。

• deviceCommonDef.h定义了设备层的错误码，调用device相关接口产生错误请参考这里。
• deviceStructDefine.h定义了device相关接口使用到的数据结构和回调函数。
• deviceSDK.h为Device层的接口函数。

# device层数据结构

# DEVICE_INFO

描述设备基本信息的字段，在初始化SDK时需要提供。

1. const char *os_platform，设备平台名称，在追溯问题的时候比较方便，应如实填写，一般为以下值之一：

   • "Android"
   • "Linux"
   • "Windows"
   • "IOS"
   • "Unknown"
   • 嵌入式平台的具体名称，如"A98"、"A113X"

2. const char *device_serial_number，设备序列号SN，每个设备都有自己唯一的序列号。

3. const char *device_license，设备licence，与SN一一对应，每个设备的licence都是SN经过privateKey签名的结果。

4. int product_id，设备的产品ID，每一款产品都有一个ID。

5. int key_version，生成licence时使用的privateKey的版本。

6. int user_hardware_version，设备自己的固件版本，用户自定义，建议从1开始递增，在OTA升级时小微可根据版本进行推送。

7. unsigned int run_mode，运行模式，0为默认模式，1为调试模式。在开发时建议使用调试模式，可产生大量日志，便于追溯问题。

8. const char *xiaowei_appid 小微业务ID，在小微平台注册时可以获得。

# DEVICE_BINDER_INFO

1. char username[1024]，绑定者的微信ID，这是一个很长的串，好友的操作逻辑都是使用这个字段作为标识。
2. char nickname[256]，绑定者的微信昵称。
3. char head_img[1024]，绑定者微信头像的URL地址。
4. char remark[256]，绑定者的备注，如“爸爸”，注意这个字段是设备相关的，即同一个微信用户他名下可能有多个设备，可能A设备给他的备注叫“爸爸”，B设备叫“哥哥”，这里获取的是当前这个设备对这个绑定者的备注。
5. unsigned int sex，性别，0女，1男，其它未知。
6. char export_id[1024]，内部服务间使用的字段，用户无需关心。
7. type，1为管理员

# DEVICE_NOTIFY

设备相关的回调函数结构体，在初始化设备时需要传入，不需要的回调函数可以不实现。

//示例代码：
DEVICE_NOTIFY notify = {0};
notify.on_login_complete = your_login_complete_handle_function;
notify.on_binder_list_change = your_binder_list_change_handle_function;
//在这个示例代码中，用户只关心登录成功和绑定者变化的回调，因此只设置这两个

1. void (*on_net_status_changed)(int status)，网络状态变化回调，一般应关注这个回调，当设备掉线后，就不要使用小微的功能了，同时可以播放一些提示，如“网络已断开”。

• status：0：在线，1：离线

2. void (*on_login_complete)(int error_code)，设备登录成功回调，必须实现，若设备登录不成功，各项服务都无法使用。注意产生这个回调并不意味着上线成功，而是通知上线的结果，需要根据errCode进行判断。

   • error_code：0：上线成功。-1：账号信息有问题。其它错误请联系我们处理。

3. void (*on_logout_complete)(int error_code)，退出登录成功，一般用户不需要，除非您需要在程序中反初始化小微，然后以另一套账号信息(SN、licence等)重新登录。

   • error_code：0：退出登录成功。目前不会有其它结论。

4. void (*on_nickname_update)(int error_code, const char *nickname, int nickname_length)，设备自己的昵称被更改的通知，这个更改可能来自SDK，也可能来自app、小程序、甚至后台等，当设备昵称产生变化后，如果是有屏设备，可以更新一下UI显示。设备的默认昵称为厂商在小微后台注册时留下的昵称。

   • error_code：尝试更新昵称失败的原因，除非有特殊配置，或者断网，不然不会失败，如果获得了非0值，请联系我们处理。
   • nickname：新的昵称。
   • nickname_length：昵称长度。

5. void (*on_avatar_update)(int error_code, const char *avatar_url, int url_length)，设备头像被更改的通知，类似昵称被更改。

   • error_code：尝试更新头像失败的原因。
   • avatar_url：新头像的URL地址
   • url_length：URL地址长度。

6. void (*on_binder_list_change)(int error_code, DEVICE_BINDER_INFO *pBinderList, int nCount)，绑定者列表产生变化的通知，每当绑定者信息变化，或者设备初始化成功时，都会产生这个回调。每次回调携带全部的绑定者信息。

   • error_code：无法获取绑定者的原因，若收到了非0值，请联系我们处理。
   • pBinderList：绑定者信息指针，这个信息由SDK维护，回调函数返回后资源被释放。
   • nCount：绑定者数量，即*pBinderList数组的大小。

7. void (*on_binder_verify)(DEVICE_BINDER_INFO info)，当某个微信用户通过扫码想绑定设备时，会收到这个回调，收到后可通过SDK提供的处理接口来同意或拒绝。同时在APP和小程序端也会收到这个推送，任意一端都可以处理这个请求。

   • info：欲绑定设备的微信用户信息。

8. void(*on_qr_code_refresh)(int errCode, const char *qr_code_url, unsigned int expireTime)当动态二维码刷新或失效时，通过此接口回调。

# DEVICE_INIT_PATH

设备初始化路径，在初始化SDK时需要提供，请确保小微SDK具有该路径的读写权限。小微SDK会在该路径下存储一些临时文件和日志。

1. const char *system_path，初始化路径，如"./xiaowie"。小微会在这个路径下写临时数据和日志。
2. unsigned long long system_path_capacity，给小微使用的存储空间最大值，单位字节，传入0不限制。小微会自动清理空间以保证临时文件和日志不大小超过这个值。目前小微SDK暂未实现，而是使用定期清理的策略，保留7天日志。

# 日志回调函数

typedef int(*device_log_func)(int level, const char *tag, const char *filename, int line, const char *funcname, const char *data);

用户自定义的日志回调函数，在初始化SDK前通过接口设置。一旦设置了自定义回调函数，则小微SDK产生的所有日志将通过这个函数传递给用户。参数如下：

1. level：日志等级

   • 0：verbose
   • 1：debug
   • 2：info
   • 3：warn
   • 4：error
   • 5：fatal

2. tag：日志标签

3. filename：产生日志的cc文件名称

4. line:产生日志的位置

5. funcname：日志产生的函数名

6. data：日志数据

该回调函数具有int返回类型，返回0什么都不做，返回1的话SDK会将本条日志写到本地log文件中（如果设置日志时打开了localWrite），小微后台可以通过命令来拉取本日志以分析问题。建议当日志级别为warn或者error的时候返回1，这样便于分析问题。SDK将在每次init的时候自动检查日志的size并清理旧日志，确保它在设置阈值以下。

# Device层接口函数

为了保持接口统一，除了特别说明外，接口返回值都为int类型，表示接口调用是否成功，参考device_error_code来找到对应的错误原因。

除了设置日志回调和查看SDK初始化状态以外，所有的接口都需要在初始化SDK成功后调用。

# 设备初始化接口

int device_init(DEVICE_INFO *info, DEVICE_NOTIFY *notify, DEVICE_INIT_PATH *init_path);

• info：设备本身的信息，必须提供。
• notify：设备通知回调，只需要实现自己需要的即可。
• init_path：SDK初始化路径，必须提供。

示例代码

void TESTFUN::login()
{
    /* test param */
    DEVICE_INFO device_info = {0};
    DEVICE_INIT_PATH path = {0};
    DEVICE_NOTIFY notify = {0};
    
    device_info.device_license = (char*)"Your Licence";
    device_info.device_serial_number = (char*)"your SN";
    device_info.product_id = 3;
    device_info.key_version = 1;
    device_info.run_mode = 0;
    //notify
    notify.on_login_complete = TESTCALLBACK::loginComplete;
    notify.on_binder_list_change = TESTCALLBACK::onBinderListChange;
    //contact test
    notify.on_binder_verify = TESTCALLBACK::autoAcceptContactRequest;
    
    //path
    path.system_path = (char *)"./";
    path.system_path_capacity = 1024*1024;
    /* test param end */
    int result = device_init(&device_info, &notify, &path);
    printf("init device result = %d \n", result);
}

# 检查当前设备SDK初始化状态

int device_check_status(void);

这个函数的返回值代表当前SDK状态：

• 0：未初始化
• 1：初始化过程中
• 2：初始化失败
• 3：初始化成功

通常您无需调用这个函数，因为SDK初始化过程很快。

# 检查当前设备登录状态

int device_get_account_status(void);

这个函数的返回值代表当前登录状态：

• 0：未登录
• 1：登录中
• 2：登录成功
• 3：未注册

# 获取SDK版本

int device_get_sdk_version(unsigned int *main_ver, unsigned int *sub_ver, unsigned int *fix_ver, unsigned int *build_no);

这个函数通过指针的形式返回SDK版本

//示例代码
unsigned int main_ver;
unsigned int sub_ver;
unsigned int fix_ver;
unsigned int build_no;
device_get_sdk_version(&main_ver, &sub_ver, &fix_ver, &build_no);
printf("\ndevice sdk ver = %d.%d.%d.%d\n",main_ver,sub_ver,fix_ver,build_no);

# 退出SDK

device_uninit(void);

当初始化失败，或者您需要在您的程序里主动退出SDK后再次重新初始化时，调用这个接口来清理SDK占用的资源，重置SDK状态。

# 获取设备UIN

unsigned long long device_get_uin(void);

UIN可以唯一的标识一个设备，这对于后期排查问题很有帮助，在提交问题时需要告诉我们设备UIN。调用这个接口的返回值即为设备UIN，返回0说明未能获取UIN，一般是因为初始化SDK尚未成功。

# 设置日志回调函数

int device_set_log_func(device_log_func log_func, int log_level, bool log_print, bool local_write);

• log_func：您自己日志函数
• log_level：您需要的日志等级，大于等于这个等级的日志才会回调给您即打印
• log_print：是否需要小微SDK在console中打印日志，true打印，false不打印。
• local_write：是否需要小微SDK本地写日志文件，如果本地写了文件，那么小微后台可以自动拉取它以分析问题。（如果设置了日志回调，那么仅当回调函数返回1时才会写）

如果您不想使用SDK自带的日志系统，则需要设置您自己的日志回调函数。如果您彻底不需要日志，将log_level设置为-1。

注意：这个函数需要在初始化SDK前调用。

# 主动获取设备绑定者列表

int device_get_binder_list(DEVICE_BINDER_INFO *pBinderList, int *nCount);

• pBinderList：存储绑定者信息的数组指针，这也意味着这个数组是由您来维护的。
• nCount：调用这个接口时，传入您构造的绑定者列表大小，返回时这个值将变成实际的绑定者数量。

//示例代码，在这个示例中，首先创建了一个大小为5的绑定者实例，如果不够则重新根据实际情况创建，这里采用在堆上创建实例，主要考虑可能处理绑定者信息的往往是另一个线程，例如需要更新UI之类的。

DEVICE_BINDER_INFO *pBinderList = new DEVICE_BINDER_INFO[5];
int nCount = 5;
if (pBinderList) {
    memset(pBinderList, 0, nCount * sizeof(DEVICE_BINDER_INFO));
    int err = device_get_binder_list(pBinderList, &nCount);
    if (error_null == err) {
        //todo, refresh your device list, maybe in another thread
    }
    else if (error_memory_not_enough == err) {
        DEVICE_BINDER_INFO *pBinderListBiger = new DEVICE_BINDER_INFO[nCount];
        if (pBinderListBiger) {
            memset(pBinderListBiger, 0, nCount * sizeof(DEVICE_BINDER_INFO));
            int err = device_get_binder_list(pBinderListBiger, &nCount);
            if (error_null == err) {
                //todo, refresh your device list, maybe in another thread
            }
        }
        delete[] pBinderListBiger; //maybe delete in another thread
            
    }
    delete[] pBinderList; //maybe delete in another thread
}

事实上，一般来说您无需主动获取，在设备初始化成功后或绑定者发生变化之后，SDK都会主动回调on_binder_list_change来通知您。

# 设备注销

int device_erase_all_binders(void);

在恢复出厂设置的时候可以使用，注意删除所有绑定者是需要走后台逻辑的，因此调用完这个接口后返回0并不是表示操作成功，而是告诉您接口调用成功。当绑定者被清空后，您会收到绑定者变化的回调，当然此时绑定者数量就是0了。

# 删除指定的绑定者

int device_erase_binders(const char *binderName);

• 绑定者的username

删除某一个绑定者，类似删除所有绑定者，从绑定者变化回调中获取结论。

# 主动拉取所有未处理的绑定请求

int device_get_all_unverify_bind_request(DEVICE_BINDER_INFO *pBinderListVerifyList, int *nCount);

• pBinderListVerifyList：好友请求列表指针，这个接口用法和1.2.9拉取绑定者极为相似，这里不再赘述
• nCount：数组大小

调用这个接口主要是可能在设备离线时，有人想加好友，这时候设备无法即时处理，所以可以在设备上线后拉一次。如果设备已经在线，则会有notify回调来通知新增的好友请求。

# 处理好友请求

int device_handle_binder_verify_request(const char *username, bool isAccept);

• username：要处理的微信用户username。
• isAccept：true同意，fasle拒绝。

# 设置绑定者备注

int device_update_binder_alias(const char *username, const char *alias);

• username：要设置的绑定者的username。
• alias：备注，不能有特殊字符。

# 更改设备自己的名称

int device_update_device_nickname(const char *nickname);

• nickname：想改成的名字，不能有特殊字符。

# 更改设备的头像

int device_update_device_avatar(const char *jpgFilePath);

• jpgFilePath：设备头像的本地存储路径，jpg格式，正方形图片，512x512或256x256。

# 刷新动态二维码

int device_refresh_dynamic_qr_code();

主动调用该接口来刷新绑定所需的动态二维码，结果会在on_qr_code_refresh中获得。无屏设备不应调用此接口，需调用下面的device_get_bind_ticket来获取一个ticket，注意这两个接口有互斥关系，ticket和二维码本质上是同一个东西，一旦刷新了ticket，二维码便过期，反之亦然。获取到ticket后通过蓝牙传递给APP或小程序，以完成绑定操作。

# 获取绑定ticket

int device_get_bind_ticket(bind_ticket_callback callback);

获取一个ticket，在回调中拿到。用于蓝牙和声波配网绑定设备。请参考蓝牙配网流程。简单来说就是配网成功后设备先登录，登录成功后调用此接口获取ticket，然后通过蓝牙将ticket传给小程序/APP完成绑定。

# 上传声波配网ticket和token

int device_upload_voice_link_result(const char *token, const char *ticket);

声波配网流程中，将获得的token和ticket上传到后台以完成绑定，具体参考声波配网。

# 获取设备ID

const char * device_get_id();

DeviceId为string类型。这个ID与设备APP本身无关，而是与login时填入的sn和pid有关。即以同样的账号信息登录后，总能获得相同的DeviceId。该接口需要在收到Login成功的回 调之后调用。

# 获取云端ticket

int xiaowei_get_cloud_ticket(void *context,
                                        XIAOWEI_CLOUD_TICKET_CALLBACK callback);

调用这个方法，从XIAOWEI_CLOUD_TICKET_CALLBACK回调中拿到ticket

void (*XIAOWEI_CLOUD_TICKET_CALLBACK)(void *context, const char *ticket,
                                              int len, int expire_seconds);

使用这个ticket可以调取所有资源类相关的接口。比如音乐。

# 小微业务层接口

# 小微业务层数据结构

小微业务层的数据结构全部位于xiaoweiAudioType.h中，下面对其进行详解。

# xiaowei_error_code

小微业务层错误码，所有xiaowei开头的接口，以及小微的响应错误码定义在这里。

# skill_id

小微支持的每个技能都有一个唯一的ID，小微原生支持的技能请参考这里的定义。用第三方技能的ID不在这里定义。

# XIAOWEI_EVENT

在小微发起请求后产生的回调on_request_callback中的事件定义，不同的事件下您需要有对应的处理逻辑。

1. xiaowei_event_on_idle，空闲。在语音和文本请求中，一次请求全流程结束后会产生这个事件，无论是请求正常结束还是产生错误，都会触发这个事件。一旦空闲产生后，则小微不再维护跟本次请求相关的信息。
2. xiaowei_event_on_request_start，请求开始。在语音和文本请求中，首次请求包被SDK接收后会触发这个事件。
3. xiaowei_event_on_speak，检测到开始说话。这个事件只会在语音请求中产生。
4. xiaowei_event_on_silent，检测到静音。这个事件只会在使用云端静音检测时产生，如果您使用本地静音检测，就不会触发这个事件(一般push to talk的时候使用本地静音检测，用户松开按钮即结束请求）。在触发这个事件后，您传给SDK的语音数据将被抛弃，您应该停止录音。
5. xiaowei_event_on_recognize，ASR的实时文本返回，只会在语音请求中触发。在一轮语音请求中，您一般会多次收到这个事件，每当ASR结果产生变化时都会推送这个事件给您，如果是有屏设备可以显示实时文本。
6. xiaowei_event_on_response，小微产生最终响应。任何请求都会触发这个事件，这也是小微最为关键的事件，在这个事件下，会返回您NLP识别结论和资源。来自服务器、app或小程序的主动推送也会触发这个事件(例如在app上为设备点播一首音乐)。
7. xiaowei_event_on_tts，TTS推送事件，目前废弃。
8. xiaowei_event_on_response_intermediate，中间结果响应。在某些情况下，由于后台需要进行一些耗时的操作，因此可能产生中间结果推送给SDK。它的处理方式和xiaowei_event_on_response一致即可。

# XIAOWEI_PARAM_PROPERTY

这个参数是在发起语音和文本请求时必须携带的，用来描述设备在本次对话中的基本属性。即XIAOWEI_PARAM_CONTEXT中的request_param。这是一个位定义参数，每一位代表一个属性。

• xiaowei_param_local_vad：在语音请求中使用本地静音检测，不使用云端静音检测，这种情况下您需要手动发送静音尾包。
• xiaowei_param_gps：设备使用GPS定位。当小微需要设备位置时会回调GPS接口来获取GPS信息，否则小微将基于IP地址来确定设备位置。
• xiaowei_param_no_tts：设备不需要TTS。通常对话中，小微返回的第一个资源就是答案文本对应的TTS，如果您确实不需要，可以使能此位来屏蔽TTS。
• xiaowei_param_local_tts：使用本地TTS包。小微可以为您提供离线TTS包，里面包含一些常用话术，如“好的”、“我在”等。若enable此位，小微在返回TTS资源时，会优先选择您本地支持的TTS语料，此时TTS资源的内容为您本地TTS包的索引。注意，若使用此功能，在发起请求时需要携带本地TTS包版本信息。
• xiaowei_param_only_vad：只做云端静音检测。这种情况下小微不会分析您的语音请求，只是返回检测到静音。使用场景是：发送一句语音留言给好友，此时设备开始录音，使用此功能来检测到说完，然后将缓存的语音数据打包发送。

//示例代码，本设备使用本地静音检测，并且无需云端TTS
XIAOWEI_PARAM_CONTEXT context = {0};
XIAOWEI_PARAM_PROPERTY property = xiaowei_param_local_vad | xiaowei_param_no_tts;
context. request_param = property;

# XIAOWEI_PARAM_AVAILABILITY

这个字段在设备状态上报时需要携带，用来表示设备目前的可用性，也是一个按位定义的参数。例如您的设备自定义了一个独立工作模式，则可以使用disable_remote_control位来告诉小微不想被app或小程序控制。

• xiaowei_availability_default：默认的正常模式。
• xiaowei_availability_mic_not_available：设备麦克风不可用，即无法语音控制设备，无法唤醒小微(可以发起文本请求，即手动按某些按钮)。
• xiaowei_availability_speaker_not_available：设备音频输出不可用(有可能是硬件层面上的静音，或者被其它应用占用，如语音通话)，小微的TTS、音乐资源等无法被播放。
• xiaowei_availability_initiative_speak：勿扰模式，该模式下，小微不会主动发起闲聊。
• xiaowei_availability_disable_remote_control：不得通过app/小程序来push控制指令。

# XIAOWEI_RESOURCE_FORMAT

小微下发的资源有若干种格式，每种类型的资源的内容格式都不一样，在处理资源时首先应该判断它的类型。

• xiaowei_resource_url：URL类型的资源，这也是最主要的类型，如音乐、FM等都是这个类型。您的播放器需要支持MP3、aac(m4a)、flac和m3u8类型的URL资源播放。
• xiaowei_resource_text：文本类型的资源，顾名思义就是纯text(比如文本新闻、小说)，有屏设备可以直接显示，也可以通过SDK的文本转TTS接口来获取可播放的TTS。
• xiaowei_resource_tts_id：一种即将被废弃的TTS类型。这种类型的TTS资源只是一个ID，同时SDK会异步通过xiaowei_event_on_tts来推送音频流，推送的音频流有ID和序号，您需要将他们关联起来播放。
• xiaowei_resource_tts_url：URL类型的TTS资源，pcm格式，单通道，16KHz，16位。
• xiaowei_resource_location：位置类型的资源，预定义，暂未使用。
• xiaowei_resource_command：命令类型的资源，已废弃。
• xiaowei_resource_intent：意图类型的资源，与定制有关。
• xiaowei_resource_remind：提醒类资源，预定义，暂未使用。
• xiaowei_resource_local：本地类型资源，如上文所述的本地TTS包。

# XIAOWEI_PLAYLIST_ACTION

资源列表操作定义。通常，当您与小微对话后，会获得一些资源，即XIAOWEI_PARAM_RESPONSE中的resource_groups。最简单的闲聊您会获得一个TTS资源，而当命中音乐skill时您还会获得歌曲的URL等。

自然的，默认情况下当您获得资源后，应该按顺序将其播放/展示，而原来的资源被废弃。例如原来设备处于播放FM状态，设备有一个FM资源列表，此时通过语音请求命中音乐，则此时应该停止FM播放，开始音乐播放。因此资源列表默认的操作为“中断当前播放，替换换来的列表”。然而除此之外，还有一些别的场景，例如拉取更多歌曲资源、插歌等，因此您应该根据这个XIAOWEI_PLAYLIST_ACTION的具体值来选择如何处理新的资源和旧的资源。

• xiaowei_playlist_replace_all：默认操作，中断当前播放，替换列表。
• xiaowei_playlist_enqueue_front：拼接到列表队头。
• xiaowei_playlist_enqueue_back：拼接到列表队尾。
• xiaowei_playlist_replace_enqueue：不中断当前播放的资源，替换列表的详情。
• xiaowei_playlist_no_action：不中断播放，只是更新列表中某些播放资源的url和quality字段信息。
• xiaowei_playlist_remove：从播放列表中移除这些资源。

# XIAOWEI_PLAYLIST_TYPE

要操作哪个播放列表，有历史列表和当前列表，这个具体解释清参考列表说明。

# XIAOWEI_CHAT_TYPE

对话请求类型。为了简化接口，语音、文本、意图、tts、唤醒校验请求都使用同一个接口，即xiaowei_request，在调用这个接口时，需要选择类型。在不同的类型下，chat_data的含义是不同的。

• xiaowei_chat_via_voice：语音请求。这种请求类型下，chat_data为单通道，16位，16KHz的pcm音频数据，长度必须为64~6400。
• xiaowei_chat_via_text：文本请求。这种类型下，chat_data即为请求文本，如"我要听歌"。
• xiaowei_chat_only_tts：TTS请求。这种类型下，chat_data即为需要转化的文本。
• xiaowei_chat_via_intent：意图请求。暂未开放。
• xiaowei_chat_via_wakeup_check：云端唤醒校验。数据和语音请求一样，过程比较复杂，请单独参考下面的具体说明。

# XIAOWEI_WAKEUP_FLAG

云端唤醒校验是针对某些设备本地唤醒模块性能较差，容易误唤醒而提供的一种校验服务。当使用云端唤醒校验请求时，小微会在响应中返回这个flag字段，根据flag的不同，您需要做出如下处理：

• xiaowei_wakeup_flag_no：这个请求不是云端唤醒请求，无需处理。
• xiaowei_wakeup_flag_fail：唤醒失败，唤醒校验结束，就当什么都没发生。
• xiaowei_wakeup_flag_suc：唤醒成功，唤醒校验结束。这时候您需要重新发起一轮正常的语音请求(而不是唤醒校验请求)，即唤醒和后续的语音请求毫无关系。
• xiaowei_wakeup_flag_suc_rsp：唤醒成功，并且直接理解了用户的需求。这种情况是用户在唤醒校验时就连续说了需求，例如“小微小微今天几点了”，中间无停顿。这种情况下直接当做一次语音请求结果处理即可。
• xiaowei_wakeup_flag_suc_continue：唤醒成功，并且用户还在继续说话，不知道用户说完没有。这是上面那种情况的升级版，用户在唤醒校验时连续说了需求，并且需求很长。这时候您应该持续录音不要停。例如用户说“小微小微我要买一张...”，说到这里就会返回这个flag。

# XIAOWEI_WAKEUP_TYPE

设备的唤醒方式，需要携带在语音请求的context中。注意不要和请求类型冲突，例如您发起了云端唤醒校验，但是这里的唤醒方式却是本地唤醒，就会产生错误。

• xiaowei_wakeup_type_local：本地唤醒，整个唤醒逻辑和SDK完全无关。
• xiaowei_wakeup_type_cloud：云端唤醒校验。
• xiaowei_wakeup_type_local_with_text：本地唤醒带唤醒词。某些时候您的本地唤醒模块无法在音频中拆离唤醒词部分，所以您可以把唤醒语音和后续的语音全部一起发送给小微，同时在context里携带唤醒词文本，小微会在NLP时帮您去掉唤醒词部分。如果您使用小微官方唤醒词“小微小微”、“嗨小微”和“你好小微”，则小微天生支持此功能，无需额外声明。
• xiaowei_wakeup_type_local_with_free：本地自动唤醒。在该模式下，小微会认为您的设备一直处于唤醒状态，当然您也需要一直录音并传给小微。一般情况下不要使用这个功能，因为他会大量占用网络资源。在该模式下，语音请求不会产生静音超时。典型的使用场景是闹钟响起，此时等待用户说“停”、“5分钟后再叫我”等。

# XIAOWEI_WAKEUP_PROFILE

远场唤醒或近场唤醒二选一，1米以下为近场。小微会根据这个距离来优化识别算法。

# XIAOWEI_DEVICE_CMD

控制指令。控制逻辑比较复杂，请单独参考控制指令。

# XIAOWEI_PARAM_RES_GROUP

小微提供的资源，请单独参考资源说明。

# XIAOWEI_PARAM_CONTEXT

语音/文本请求的上下文。每次请求都需要携带(包括第一次请求)。

• id：上下文ID，在多轮会话中需要使用。首轮请求请置空。例如第一轮请求问小微“刘德华多少岁？”，小微如实回答，并在response里携带了上下文ID，此时问“那张学友呢？”，则需要带上这个ID，否则小微无法理解你在问什么。
• speak_timeout：等待用户说话超时时间，单位ms，语音和唤醒校验请求有效。如果超过这个时间小微仍然没有检测到有效的语音输入，即没有触发on_speak，则对话结束，建议设置为5000。没有有效的语音输入是指规定帧数的数据内ASR识别只有噪声，没有结果(例如当timeout为5000时，就是小微收到5*16KHz数据后)。
• silent_timeout：尾部静音时间，即静音检测的阈值，使用云端静音检测时有效。当最后的有效ASR结果产生后的阈值时间内，若没有新的ASR结果产生，则触发on_silent事件。这就意味着用户说完了，不必再录音了，建议设置为500。
• voice_request_begin：请求开始，一轮对话中首次调用request接口时设置为true，其它时候均为false。当这个字段为true时，标志着新的一轮对话开始，上一轮对话会强制停止。显而易见，文本请求只需要调用一次request接口，因此它总是为true。
• voice_request_end：请求结束，在一轮请求中除了最后主动发送尾包时为true，其它时候均应为false。当这个字段为true时，小微收音结束。使用云端静音检测时无需发送静音尾包。
• wakeup_profile：远场或近场唤醒，参考上面说明。
• wakeup_type：唤醒类型，参考上面说明。
• wakeup_word：唤醒词，参考上面说明。
• request_param：请求参数，即XIAOWEI_PARAM_PROPERTY。
• local_tts_version：本地TTS包的版本，如果请求参数中使用本地TTS包，则需要申明版本。
• skill_id：技能ID，一般为空。当您只想命中某个技能时，携带这个ID。例如您确信用户本次语音请求就是要点歌，则携带音乐的skillID，用户如果说的是“今天天气怎么样”，也不会命中天气，而是会尝试寻找“今天天气怎么样”这首歌。

# XIAOWEI_PARAM_RESPONSE

请参考主页中的详细说明

# XIAOWEI_PARAM_STATE

设备状态的描述。某些设备可能同时处于多个skill下，这里需要上报的是当前活动的skill。

• skill_info：必填字段，如果为空则表示设备目前什么也没干。
• play_state：播放状态，暂停、播放中等等，参考XIAOWEI_PLAY_STATE。
• availability：设备可用状态，参考XIAOWEI_AVAILABILITY。
• play_id：当前正在播放或者处于暂停/停止状态的资源ID。
• play_content：这个资源对应的内容，例如URL资源就是那个URL。
• play_offset：目前播放的位置，单位ms。
• play_mode：播放模式，如顺序，循环等。
• resource_type：资源类型，如URL。
• resource_name：资源名称，如“青花瓷”，可选字段。
• performer：表演者，如“周杰伦”，可选字段。
• collection：专辑，可选字段。
• cover_url：封面URL，可选字段。

# XIAOWEI_GPS_INFO

GPS信息，正常填写即可，如果GPS信息不可用，则将is_gps_available置为fasle即可。

# XIAOWEI_PARAM_LOG_REPORT

当您使用小微出现严重问题时，为了快速追查，可以调用上报接口来说明问题。正常情况不要调用，小微自己有全链路日志系统。

• voice_id：出现问题时的voiceID。
• log_data：问题出现时的数据，可以是日志、堆栈等。
• event：用户自己定义当前的event。
• time_stamp_ms：问题发生的时间。

# 请求回调

bool (*on_request_callback)(const char *voice_id, XIAOWEI_EVENT event, const char *state_info, const char *extend_info, unsigned int extend_info_len);

小微所有的请求，都从这个接口中返回。

• voice_id：请求时的voice_id，注意这个请求可能并非来自设备本身，有可能来自APP、小程序或后台的推送。
• event：请参考上文的event详细描述。
• state_info：除了xiaowei_event_on_tts以外，请将其强转为XIAOWEI_PARAM_RESPONSE。
• extend_info：额外的信息，这和skill、厂商定制等有关。
• extend_info_len：由于某些情况下extend_info可能是二进制数据，所以有个长度。

# GPS需求回调

当您的请求context里面设备属性配置为支持GPS，并且通过xiaowei_set_gps_callback设置了非空回调时。小微会在需要GPS的时候触发这个回调。注意：由于这是一个同步操作，此函数执行一定不能阻塞，建议用户设置一个buffer存储GPS信息。

# 小微业务层接口函数

# 启动小微服务

int xiaowei_service_start(XIAOWEI_CALLBACK *callback, XIAOWEI_NOTIFY *notify);

如主页的介绍所说，小微core业务可以在小微device初始化成功后单独启动，也可在初始化device时配置自动启动。若手动启动，则调用此接口。

# 请求接口

int xiaowei_request(char *voice_id, XIAOWEI_CHAT_TYPE type, const char *chat_data, unsigned int char_data_len, XIAOWEI_PARAM_CONTEXT *context);

小微对话类请求的公共接口，根据type的不同，使用方式不同。当使用语音类(语音请求和唤醒校验)请求时，需要连续多次调用这个接口，每次调用时传入一定量的语音数据(64~6400，建议3200，即在16K的采样率下，每秒调用5次)。其它类型，如文本请求，调用一次这个接口即可。

注意，voice_id是小微SDK生成的，并不是由您提供的，您需要申请一个33字节大小的空间让SDK来填写，接口返回时即可获取。每一轮请求的voice_id是相同的，即语音请求时，您可能需要调用数十次xiaowei_request接口，每次获取的voice_id都是一样的。

//示例代码，这是一次文本请求
 char voice_id[33] = {0};
 XIAOWEI_PARAM_CONTEXT context = {0};
 context.silent_timeout = 500;
 context.speak_timeout = 5000;
 context.voice_request_begin = true;
 context.voice_request_end = false;
 const char *text = "我要听林俊杰的歌";
 xiaowei_request(voice_id, xiaowei_chat_via_text, text, (uint32_t)strlen(text), &context);

//示例代码，这是一次语音请求
 char buf[1024] = your voice data;
 //第一包
 char voice_id[33] = {0};
 XIAOWEI_PARAM_CONTEXT context = {0};
 context.silent_timeout = 500;
 context.speak_timeout = 5000;
 context.voice_request_begin = true;
 context.voice_request_end = false;
 //本地静音检测，要主动发送end包，如果云端静音检测，就当收到onsilent回调之后停止发送请求
 XIAOWEI_PARAM_PROPERTY property = xiaowei_param_local_vad;
 context.request_param = property;
 xiaowei_request(voice_id, xiaowei_chat_via_voice, buf, sizeof(buf), &context);

 //第N包，从第2包开始
 context.voice_request_begin = false;
 buf更新，
 xiaowei_request(voice_id, xiaowei_chat_via_voice, buf, sizeof(buf), &context);
 
 /* 中间还有若干包 */
 
 //最后一包
 context.voice_request_end = true;
 buf更新(最后一包buf长度可以为0)
 xiaowei_request(voice_id, xiaowei_chat_via_voice, buf, sizeof(buf), &context);

# 主动停止小微服务

int xiaowei_service_stop();

停止之后可以重新start，例如您想改一下回调函数地址等。

# 强行取消某次请求

int xiaowei_request_cancel(const char *voice_id);

强行取消某次请求，voiceID填空会取消所有请求。一般的使用场景为，用户push to talk的时候，主动cancel，不想说了，这时候需要调用一下，不然小微可能会返回“没听懂你在说什么”。在一轮请求中，如果直接重新发起一轮语音/文本请求(request_begin = true)会自动取消上一次未完成的请求。

# 上报播放状态

int xiaowei_report_state(XIAOWEI_PARAM_STATE *state);

设备应该在状态变化之后及时上报，只需要上报大资源，即打断后能够恢复的资源，例如音乐，FM。无需上报小资源，例如TTS播放。这里列举一下常用场景的上报：

 1. 切歌：报2次，首先第一首歌stoped(offset为stop前一瞬间的位置)、然后第二首歌playing(offset = 0)。
 2. 播放过程中唤醒了开始语音请求(这时候正常音乐是要暂停的)：上报paused
 3. 操作2点了一首新歌，并且要准备播放了：先报刚才那首暂停的歌stoped，再报新歌playing
 4. 操作2问了一下天气或者闲聊：首先无需任何上报，音箱播放天气或者闲聊的TTS，对话结束之后正常逻辑应该恢复播放音乐，然后这时候上报刚才那个歌playing。
 5. 该播放的东西播完了，无事可做：上报idle

# 通用请求

int xiaowei_request_cmd(char* voice_id, const char* cmd, const char* sub_cmd,  const char* param, XIAOWEI_ON_REQUEST_CMD_CALLBACK callback);

您可以通过通用请求接口来获取资源或触发事件，通过这个接口的请求会有单独的response callback，需要在每次调用时传入，param为命令参数的json。如果传入的callback为null，则会在通用的on_request_callback中回调。下面对于支持的命令作说明：

为了便于说明，这里抛出XIAOWEI_ON_REQUEST_CMD_CALLBACK里面的jsonData通用结构，它的结构和XIAOWEI_PARAM_RESPONSE很相似，或者说是它的json展现。

//通用响应json结构
voiceId: XXX
error: 0
json: 
     {
         "context": {
             "id": "",
             "silent_timeout": 500,
             "speak_timeout": 0
         },
         "skill_info": {
             "id": "xx",
             "name": "音乐",
             "type": 0
         },
         "control_id": 0,
         "control_value": "",
         "has_history_playlist": false,
         "has_more_playlist": false,
         "play_behavior": 1,
         "resource_list_type": 0,
         "response_data":"data",
         "resource_groups": [{
             "resources": [{
                 "content": "url",
                 "extend_buffer": "info",
                 "format": 0,
                 "id": "id",
                 "offset": 0,
                 "play_count": -1
             }],
             "resources_size": 1
         }]
     }
     

除非特别说明，否则下面的响应均指上面这个json中的response_data字段。

# 预拉取

用于获取更多播放资源（音乐、FM、新闻），一般在当前资源快要播放完毕的时候调用此接口获取更多。此接口也可用于拉取历史列表。（列表第一首向上拉就是拉历史）

Request

cmd: "PLAY_RESOURCE"
subCmd: get_more
params: 
{
     "skill_info": {
         "id": "例如：音乐的skillid",
         "name": "例如：音乐"
     },
     "play_id": "xxx",
     "is_up": false
}
	

Response格式参照[通用响应结构]。

# 查资源详情

一般就是查询音乐的歌词。

Request

cmd: PLAY_RESOURCE
subCmd: get_detail
params:
{
     "skill_info": {
         "id": "例如：音乐的skillid",
         "name": "例如：音乐"
     },
     "play_ids": ["id0", "id1"]
}
	

Response格式参照[通用响应结构]。

# 刷新播放资源

用于切换音乐品质或 url 过期需要刷新时调用，QQ音乐下发的URL只确保4小时有效，如果超过4小时，建议刷新一下。

Request

cmd: PLAY_RESOURCE
subCmd: refresh
params:
{
     "skill_info": {
         "id": "例如：音乐的skillid",
         "name": "例如：音乐"
     },
     "play_ids": ["id0", "id1"]
}
	

Response格式参照[通用响应结构]。

# 获取收藏列表

Request

cmd: PLAY_RESOURCE
subCmd: get_favorite_list
params:
{
     "skill_info": {
         "id": "...",
         "name": "例如：音乐"
     }
}
	

Response格式参照[通用响应结构]。

# 收藏及取消收藏

Request

cmd: PLAY_RESOURCE
subCmd: set_favorite
params:
{
     "skill_info": {
         "id": "...",
         "name": "例如：音乐"
     },
	  "favorite":/*bool, false表示取消收藏，true表示收藏*/,
	  "play_id":"string id"
}
	

Response格式参照[通用响应结构]，可能会有一句“收藏成功”的notify TTS。

# 设置及查询资源品质

目前只支持音乐，设置后一直有效，下次请求或者刷新URL就会是新的品质。

Request

cmd: PLAY_RESOURCE
subCmd: quality_config
params:
{
    "skill_info": {
        "id": "8dab4796-fa37-4114-0011-7637fa2b0001",
        "name": "音乐"
    },
    "quality_config": {
        "type": 0, // 0,set; 1,get
        "quality": 3 // 0流畅，1标准，2高品质，3无损
    }
}

Response

{"quality":3}

# 查询QQ音乐会员信息

Request

cmd: QQMUSIC
subCmd: get_vip_info
params: 无

Response

{
	"head_url": "http:\/\/thirdqq.qlogo.cn\/g?b=sdk\u0026k=MoaNSg02cT8FGBMNxdEa3w\u0026s=140\u0026t=1556610006",//用户头像，Unicode编码（原始头像，绿钻未镶嵌在头像中）
	"nickname": "Yuan",//用户昵称
	"is_green_vip": true,//是否绿钻
	"is_super_green_vip": true,//是否豪华绿钻
	"green_vip_start_time": "2018-12-13 13:01:57",//绿钻开始时间
	"green_vip_end_time": "2020-03-22 13:01:57",//绿钻结束时间
	"super_green_vip_start_time": "2018-12-13 13:01:57",//豪华绿钻开始时间
	"super_green_vip_end_time": "2020-03-22 13:01:57",//豪华绿钻结束时间
	"is_eight_pay_package": true,//是否8元付费包（正常开绿钻送8元音乐包，但是也可以单独买）
	"eight_start_time": "2018-11-19 16:43:31",//8元付费包开始时间
	"eight_end_time": "2020-05-30 16:43:31"//8元付费包结束时间
}

# 获取QQ音乐授权二维码

支持获取用于QQ音乐APP、QQAPP和微信APP扫的二维码，在有屏设备上，可以通过扫码的方式完成QQ音乐登录态授权。其中QQ音乐APP的二维码获取的同时会拿到一个session，通过该session轮询授权结果。QQ和微信通过扫码后捕获web跳转的方式获得对应的token。具体可参考我们提供的QQ音乐授权demo。

设备端拿到登录态后，需要调用SDK接口来设置登录态。（即下面的设置登录态命令）

Request

cmd: QQMUSIC
subCmd: get_qr_code
params: 
{
	"type":1 // 0: QQMusic, 1:WX, 2:QQ
}

Response

• QQ音乐客户端（type 0）

{
	"sdk_qr_code": "qqmusic://qq.com/other/openid?p=%7B%22appId%22%3A%2235%22%2C%22cmd%22%3A%22qrcode%22%2C%22code%22%3A%221SYvikaMBW4aan8Gva1o7Ra5nkn%22%7D",
	"session": "005c517ac51bac9e5daf0dff"
}

• QQ/微信客户端（type 1和2）

  获得的URL里面就包含了redirect_uri。具体可参考我们提供的QQ音乐授权demo。

{
	"qr_code_url":"https:\/\/open.weixin.qq.com\/connect\/qrconnect?appid=wx48db31d50e334801\u0026scope=snsapi_login\u0026scope=snsapi_login\u0026redirect_uri=http:\/\/y.qq.com\/tv\/login_success.html"
}

# 利用session查询QQ音乐二维码状态

Request

cmd: QQMUSIC
subCmd: get_session_status
params: 
{
	"session": "your session from get_session_status"
}

Response

{
	"state": 0, //0 等待，1成功，2失败，3取消
	"state_msg": "waiting"
}
	

# 取消QQ音乐扫码授权

Request

cmd: QQMUSIC
subCmd: un_auth
params: 无

Response

{
	"code": 0, //0 成功，其它失败
	"msg": "ok"
}    

# 设置QQ音乐登录态

Request

cmd: QQMUSIC
subCmd: set_login_status
params: 
//如果是第三方授权的登录态
{
    "access_token_info": {
    "access_token": "9194f0a18705101e116785e44f88710ca5e952769389c0e20bd1ad7bd7bcf527",
    "app_id": "35",
    "open_id": "17274107831921500691"
    }
}

//如果是设置微信的登录态
{
    "wx_code": "06197biH1Lmic1042LhH1kA9iH197bis" // 通过页面跳转捕获到的token
}

//如果是设置QQ的登录态
{
    "qq_code": "06197biH1Lmic1042LhH1kA9iH197bis" // 通过页面跳转捕获到的token
}

Response

{
	"code": 0, //0 成功，其它失败
	"msg": "ok"
}    

# 获取微信客户端扫描的QQ音乐授权二维码

使用微信授权QQ音乐，只能使用QQ音乐提供的二维码，自行在开放平台申请的appid无法打通账号。所以，提供了接口获取二维码。

cmd: QQMUSIC
subCmd: get_wx_qr_code
params: 无

Response

{
	"qr_code_url":"https://open.weixin.qq.com/connect/qrconnect?appid=wx48db31d50e334801\u0026scope=snsapi_login\u0026scope=snsapi_login\u0026redirect_uri=http://y.qq.com/tv/login_success.html"
}

拿到url后，需要打开这个url，然后再登录网页跳转的回调中拦截到wxCode，对此，我们提供了sample code，请参考android demo的LoginView.java

# 查询闹钟

Request

cmd: ALARM
subCmd: get_list
params:
{
    "disable":true //字段为空默认为false，此时仅会返回已设置并且已开启的闹>钟，传true代表获取所有已设置的闹钟
}

Response

{
    "clock_info": [{
         "clock_id": "282091",
         "clock_type": 0,
         "event": "喝水",
         "disable":false,//字段为false，代表已设置并且已开启的闹钟，true代表已设
置但未开启的闹钟
         "repeat_interval":"1",
         "repeat_type": 0,
         "service_type": 0,
         "trig_time": "1527924451"
     }],
    "server_time": 1527924451
}

# 修改闹钟

Request

cmd: ALARM
subCmd: set_alarm
params: 
{ "opt":1 // 操作类型，1代表增加，2修改闹钟，3代表删除单个闹钟， 4代表删除全部闹钟,
	"clock_info": { 
		"clock_id": 1 ,//闹钟id 唯一标识一个闹钟,添加和删除全部闹钟可不携带此信息 
		"event": "eat" ,//事件，为空表示没有事件
		"clock_type": 1, //1.一次性闹钟 2.重复闹钟
		"trig_time": 2333333 ,//触发时间，为unix时间
		"repeat_type" : 1,//闹钟重复类型，0表示只响一次、1表示每天一次、2表示每周一次、3表示每月一次
		"repeat_interval": string ,//闹钟重复类型的字符串，例如，"1111111"代表一周七天
		"service_type": 0, //0:本地，1：定时播放， 2：定时关闭skill，默认本地
		"service_data": , //定时播放的信息，由后端生成
	}
}

Response

{
    "clock_info": [{
         "clock_id": "282091",
         "clock_type": 0,
         "event": "喝水",
         "disable":false,//字段为false，代表已设置并且已开启的闹钟，true代表已设
置但未开启的闹钟
         "opt":1,
         "repeat_interval":"1",
         "repeat_type": 0,
         "service_type": 0,
         "trig_time": "1527924451"
     }],
    "server_time": 1527924451
}

# 触发闹钟

注：当闹钟响起时，无屏设备唤醒或触碰任意按键即结束闹铃，有屏设备唤醒或触碰按钮即结束闹铃。

Request

cmd: ALARM
subCmd: get_timing_task
params: 
{
	"clock_id":233333//闹钟的clock_id
}

Response

{
    "clock_info": [{
         "clock_id": "282091",
         "clock_type": 0,
         "event": "喝水",
         "repeat_interval":"0000000",
         "repeat_type": 0,
         "service_type": 0,
         "trig_time": "1527924451"
     }]
}

# 请求合成TTS

注意这个接口需要经过黄反过滤，如果失败则无法拿到TTS。

Request

cmd: TTS
subCmd: 无
params: "想合成的文本"

Response

{
	"TTSUrl":"https:\/\/cloudim.weixin.qq.com\/cloudim\/cloudxw-bin\/xwttsplay?tts_id=TTS02BKQIWLPGEITKDLYZWZJILWTECMHTPRVA202006191137561612278",
	"voiceID":"BKQIWLPGEITKDLYZWZJILWTECMHTPRVA"
}

# 获取IOT设备列表

Request

cmd: GET_IOT_DEVICE
subCmd: 无
params: 无

Response

{
	\"code\":0,
	\"data\":{\"category_list\":{},\"device_list\":[]},
	\"msg\":\"获取用户设备成功\"
}

# IOT相关汇总

IOT相关的其它一些通用控制，有一个固定的模式：

• cmd为IOT skill的skill ID，即"8dab4796-fa37-4114-ffff-000000000000"

• sub_cmd的定义如下：

  ub_cmd取值	功能	其他
  1	获取设备列表
  100	本地组网设备回传控制结果
  101	本地组网设备上传状态
  102	本地组网主动上报全部的设备
  103	与小程序互通的一些接口

• params有一个基本的结构：

请求结构：
{
  "params": {         // 上传的参数
  },
  "comm_type": 1  // 接口类型，参考下面的接口类型定义
}
 
返回结构：
{
  "code": 0,  // 参考每个接口的code定义
  "msg": "获取成功",
  "data": {            // 接口返回的数据
  },
  "debug_data": [  // 接口调试的数据
  ]
}

# 详细说明

# 1、请求设备列表

请求参数：

{
 "params": {
   "category_id": -1
 },
 "comm_type": 1
}

返回结果：

{
"code": 0,
"msg": "获取成功",
"data": {
 // 设备被删除（只有推送才有这个字段）
 "delete_device_list" : [],
 // 设备被更新（只有推送才有这个字段）
 "modify_device_list" : [],
 // 设备被新增 （只有推送才有这个字段）
 "add_device_list" : [],
 // 类别
 "category_list":[],
 // 下面数据为主动获取时才会有
 "device_list": [
   {
     "device_id": "1234566",
     "device_alias_names": [
       "电灯"，"白色的灯"
     ],
     "device_icon": "",
     "device_is_online": 1,
     "device_is_authorize": 1
     //SDK额外需要的字段
	"device_name":"量子灯"
	"device_type_id":"设备类型"
	"device_type_name":"设备类型名"
	"device_type_nickname":"设备类型别名"
	"category_id":"2"
   }
 ]
}
}

device定义：

# 2、本地组网设备回传控制结果

# 3、本地组网设备上传状态

​ 参考云端协议文档。

# 4、本地组网主动上报全部的设备

​ 参考云端协议文档。

# 5、与小程序互通的一些接口的返回值

# (5.1) 添加房间

请求参数

{
"params": {
 "category_name": "卧室1"
},
"comm_type": 3
}

参数说明：

返回值

{
 "code": 0,
 "data": {
     "category_id": 1
 },
 "msg": "添加分类(房间)成功"
}

# (5.2) 修改房间

{
"params": {   
 "category_id": 1,
 "category_name": "房间33"
},
"comm_type": 5 
}

参数说明：

返回值

{
 "code": 0,
 "data": {},
 "msg": "修改分类成功!"
}

# (5.3) 删除房间

{
"params": {   
 "category_id": 1,
   "category_id": 0
 },
 "comm_type": 4 
}

参数说明：

返回值

{
 "code": 0,
 "data": {},
 "msg": "对不起,您没有此分类"
}

# (5.4) 绑定房间与设备

{
"params": {
 "device_id": "1234",
 "category_id": 12
},
"comm_type": 13
}

参数说明：

返回值

{
"code": 0,
"msg": "修改成功",
"data": {
}
}

# (5.5) 修改备注名

{
"params": {
 "device_id": "uniqueLightDeviceId1",
 "name_list": [
   "台灯",
   "电灯"
 ]
},
"comm_type": 10
}

参数说明：

返回值

{
 "code": 0,
 "data": {},
 "msg": "对不起,您没有此分类"
}

# 微信互动资源解密

xiaoweiDecoder.h
/**
 * @brief Create a decoder with key.
 * @return The decoder
 */
DEVICE_API void *xiaowei_decoder_create(const char *key, int key_len);

/**
 * @brief Decode data
 * @param data This is the input, also out put.
 * @param size size of data
 * @param offset offset of the data.
 */
DEVICE_API void xiaowei_decoder_decode(void *decoder, char *data, size_t size,
                                       size_t offset);

/**
 * @brief Destroy the decode with created by xiaowei_decoder_create(...)
 */
DEVICE_API void xiaowei_decoder_destroy(void *decoder);

使用流程：创建decoder，使用读取文件流进行解密，解密结果需要自行保存。解密全部完成后销毁decoder。

详见xiaoweiDecoder.h中Example code

# 小微SDK自定义技能协议

厂商在技能平台上配置好对话机器人，在用户query对应指令时，sdk会从on_request_callback透传由服务器发来的的技能、意图以及槽位信息。

"response_data" : "{
  "intentName": "intentName",  //意图名称
  "slots"[		//槽位信息
    {
      "norm": "norm",  
      "slot_value": "slot_value",
      "slot_name": "slot_name"
    },
  "tts_text":"什么运动模式"  //tts文本
  ]
}",
"response_type" : 25,
"skill_info" : 
{
	"id" : "",
	"name" : “skillname”
}

# 微信听书

微信听书使用通用请求。功能包括加载更多列表、刷新url、获取历史列表、收藏和取消收藏。 微信听书支持倍速播放，设备上报状态时，倍速值也要上报。 注：播放链接有实效，如果失效或播放链接为空，请刷新url

# 加载更多

加载更多会加载15条数据，但仅有前3条有播放URL，其余资源播放时，请刷新url获取播放链接

Request

cmd: "PLAY_RESOURCE"
subCmd: get_more
params: 
{
     "skill_info": {
         "id": "微信听书的skillid",
         "name": "微信听书"
     },
     "play_id": "xxx",
     "is_up": false  //true：向上加载；false：向下加载
}
	
Response格式参照[通用响应结构]。

extendInfo:{
"album":"鬼谷子（白话全译）",  //专辑名字
"artist":"鲸鱼有声",   //作者
"cover":"https://weread-1258476243.file.myqcloud.com/listen/cover/3103003743/s_3103003743.jpg", //封面
"duration":324,  //时长，单位s
"favorite":true,  //是否收藏
"name":"鬼谷子教你使诈：强者为何给他人留足面子（上【19】", //章节名字
"playId":"TRA_3103003743_500863", //playID
"playable":true,  //是否可用
"quality":0,  //质量
"skillName":"",  //技能名称
"unplayableCode":0, //不能播放的code
"unplayableMsg":""  //不能播放说明
}

# 加载历史列表

Request

cmd: "PLAY_RESOURCE"
subCmd: get_histroy
params: 
{
     "skill_info": {
         "id": “微信听书的skillid",
         "name": "微信听书"
     },
     "play_id": "xxx",
     "is_up": //bool,向上或者向下拉取
}
	
Response格式参照[通用响应结构]。
extendInfo:{
"album":"鬼谷子（白话全译）",  //专辑名字
"artist":"鲸鱼有声",   //作者
"cover":"https://weread-1258476243.file.myqcloud.com/listen/cover/3103003743/s_3103003743.jpg", //封面
"duration":324,  //时长，单位s
"favorite":true,  //是否收藏
"name":"鬼谷子教你使诈：强者为何给他人留足面子（上【19】", //章节名字
"playId":"TRA_3103003743_500863", //playID
"playable":true,  //是否可用
"quality":0,  //质量
"skillName":"",  //技能名称
"unplayableCode":0, //不能播放的code
"unplayableMsg":""  //不能播放说明
}

# 刷新url

Request

cmd: PLAY_RESOURCE
subCmd: refresh
params:
{
     "skill_info": {
         "id": “微信听书的skillid",
         "name": "微信听书"
     },
     "play_ids": ["id0", "id1"]
}
	
Response格式参照[通用响应结构]。

# 收藏、取消收藏

Request

cmd: PLAY_RESOURCE
subCmd: set_favorite
params:
{
     "skill_info": {
         "id": “微信听书的skillid",
         "name": "微信听书"
     },
	  "favorite":/*bool, false表示取消收藏，true表示收藏*/,
	  "play_id":"string id"
}
	
Response格式参照[通用响应结构]。

# 倍速播放

倍速设置通过播放状态上报的形式设置播放倍速。也可以通过语音设置倍速，或小程序等其他方式，通过播控来控制设备修改倍速（‘xiaowei_cmd_set_play_speed’ = 1000030），设备修改完倍速后需要上报下当前播放状态

上报参数
‘XIAOWEI_PARAM_STATE.play_speed’

# 可见可说

可见可说模式用于定向识别某些文本，并且具有模糊匹配能力（用于人名、地名等）。例如目前您的设备处于某个界面下，界面上有“爸爸”、“张三”和“取消”三个选项，您期望用户使用语音进行三选一。这时候便需要使用可见可说功能。

使用此功能时，首先需要设置词表，调用xiaowei_set_wordslist(...)来设置词表，words_list为词表数组，UTF-8格式，不得包含emoji、火星文、特殊字符等。

int xiaowei_enable_v2a(bool enable);接口用于打开或关闭可见可说，打开后长期有效，不使用时应该主动关闭。

# 上传本地词表

若您的设备支持拨打本地电话（非小微提供的voip），或是打开本地APP等功能，则需要上传本地词表。使用int xiaowei_upload_data(...);，关于每种词表的类型以及各式，请参考代码中的说明。词表上传之后长期有效，不必每次上传，每当词表变化之后，需要重新全量上传，不支持单独更新。

对于有屏设备，如果用户主动点击按键来收藏或者取消收藏资源，则可以调用此接口。注意这是一个异步接口，需要后台同步QQ音乐数据库。在收藏成功后，会推送一个控制指令用于确认，此时可以进行UI展示。

# 上报自定义日志

int xiaowei_user_report(XIAOWEI_PARAM_LOG_REPORT *log);

这个接口用于上报您的自定义日志，如错误信息，crash堆栈等，可以便于我们分析问题。一般情况下不要调用此接口。在XIAOWEI_PARAM_LOG_REPORT中定义了4个参数，均仅供参考。