# 接口说明

在xiaowei-api-sdk.aar中，包含了小微设备APP的通讯接口，在xiaowei-model.aar中，包含了小微业务的数据结构、基础工具类和全局错误码、控制指令定义。

除非特别说明，所有int返回类型的接口，其定义均参考通用错误码定义即可。

# IXWService

# 设备登录

void login(in DeviceLoginInfo loginInfo, in IOnDeviceLoginListener listener)

小微设备APP是无状态的，每当首次启动或bind断开时，都会reset到初始化状态。因此，在您的workflow中，每次初始化时都应在建立aidl绑定后调用此接口来实现login。每次使用相同的账号信息login后，设备APP会从后台拉取该账号下的好友等信息。

Login需要提供一系列登录信息，即DeviceLoginInfo:

• osPlatform: 设备平台，没有特殊定义的话，建议填写Android
• license: SN对应的签名
• serialNumber: 即SN，每台设备需要有唯一的账号，即唯一的SN
• keyVersion: license签名时使用的秘钥版本
• productId: 产品PID
• productVersion: 您自己的版本号，便于OTA升级和问题追溯
• runMode: 运行模式。0：标准模式， 1：debug模式，该模式下会打开全量日志，比较占空间。 9：测试环境debug模式，该模式会打开全量日志，并且登录和请求将路由到测试服务器。
• sysPath: 废弃，设备APP不再提供缓存路径设置接口。
• sysCapacity: 缓存空间限制，单位字节，0为不限制，至少需要为10M，输入10M以下的值将fix到10M
• appid: 在官网注册时获取的appid

同时，在Login的时候需要设置一个回调IOnDeviceLoginListener，在这个回调中有一系列基础事件，如登录成功、登录失败、网络掉线等等，详细说明下文将叙述。您需要在调用login之后关注这个回调，以便进行后续的操作。注意login接口是一个异步接口，需要等待后台返回结果，在回调之前，您不应进行其它操作，无论成功或失败，一定会有对应的回调。

# 开启小微服务

int startXiaoweiService()

在设备登录成功后，即IOnDeviceLoginListener.onLoginComplete(0)后，可以进行其它操作，一般的，您首先需要初始化小微AI语音服务，即调用此接口。非0的返回意味着严重错误。

# 获取设备联系人

DeviceBinderInfo getDeviceManager()

主动调用此接口可以获取当前设备的联系人数量，以及经过处理的联系人信息。注意当没有联系人的时候，可能会返回空指针。

# 获取SDKCore版本号

int[] getSDKVersion()

该版本号记录了小微core的版本，对话能力的迭代依赖于此版本。

# 获取设备ID

long getUin()

Uin为unique identify number。这个ID与设备APP本身无关，而是与login时填入的sn和pid有关。即以同样的账号信息登录后，总能获得相同的Uin。在您反馈问题时，Uin十分关键，它代表了设备身份，该接口需要在收到Login成功的回调之后调用。

# 获取用于蓝牙绑定的ticket

void getBindTicket(in IOnTicketRefreshListener listener)

该接口更多的是为无屏设备准备的，若您的设备无法自行入网，则需要使用小微APP或小程序来完成蓝牙配网，配网成功后，完成登录并使用该接口获取ticket，进而通过蓝牙将ticket传给APP或小程序，以完成绑定。关于蓝牙配网，请参考配网说明。

# 解除所有绑定和授权

void unBindAll()

删除所有好友以及登录态授权，在设备系统重置时建议调用。注意这个接口是一个异步接口，并且由于后台需要操作的逻辑过多，所以暂时没有成功的回调。在好友方面，可以通过好友数量变化的callback来得知是否删除成功。因此，调用此接口后，不要立即断开aidl连接或杀死设备APP。

# 刷新微信二维码

int refreshQRCodeUrl()

通常，您应该通过拉起小微的联系人界面，来完成微信扫码绑定的流程。若在您的应用中也需要展示二维码来引导用户微信扫码绑定，则可以调用此接口来主动刷新用于好友绑定的二维码，二维码会在IOnDeviceLoginListener.onQrCodeRefresh(...)中回调。需要在login成功之后调用。

# 获取设备APP的版本号

String getAppVersion()

设备APP的版本号对应着其接口定义，我们的升级会采用向下兼容方式。

# 获取语音请求实例

IAIAudio getAudioApi()

在这个实例中发起语音/文本请求，并设置回调监听。

# 获取资源管理器实例

ICommon getCommonApi()

在这个实例中上报您的设备播放状态、管理从小微获得的媒体资源列表，同时进行一些通用的请求。

# 获得技能管理器实例

IXWSkill getSkillApi()

在这个实例中，您可以拉起voip，管理闹钟、视频等本地/第三方技能。

# 获取腾讯视频APPAgent实例

ITencentVideo getTencentApi()

如果您想使用小微来控制腾讯视频，需要初始化该实例。

# 获取设备profile

DeviceProfile getDeviceProfile()

获取设备自身的一些信息，如设备名。

# audio.IAIAudio

这个接口封装了小微的语音/文本请求及回调，这是小微APP的核心。

小微的所有请求（即调用request(...)方法）均为异步请求，request(...)接口的返回值请求的ID，您需要从异步回调的ID中与之对应。即通过setAudioRequestListener(...)接口来设置一个监听。注意小微后台有可能会主动产生推送，例如小程序端给设备端点播了一首歌，此时IAudioRequestListener接收到的响应内的ID是由后台产生的随机值。

# 语音和文本请求

String request(int type, byte[] requestData, XWRequestInfo param)

此接口用于发起语音、文本或唤醒校验请求。该接口的返回值为请求ID，即voiceID，空的ID表明请求失败。

• int type，请求类型。通过这个参数来区分请求类型，其中type定义在了XWCommonDef.java中的RequestType。
• byte[] requestData，请求数据。在不同请求类型下，有着不同的定义。语音、唤醒校验请求时为单通道、16位、16KHz的pcm音频数据，大小介于64和6400之间。在文本和TTS合成请求时，为请求文本。
• XWRequestInfo param，请求参数和上下文。

# XWRequestInfo的解释如下

• contextId 上下文ID，用于多轮对话，在请求和响应中均能获得，每次请求都需要携带。首次请求时应将其置为空，每次拿到response时，若其中的contextId不为空，则代表进入了多轮对话，下次请求时携带此ID即可进入多轮对话。
• speakTimeout 等待用户说话的超时时间(单位:ms)，语音请求有效，若超过这个时间后台仍然未检测到说话，即onSpeak事件未触发，则会触发超时，返回errcode并结束对话。这个值可以根据您的产品定义自行设置，推荐5000，最大值为30000。在多轮对话时，response中也会有一个speakTimeout，代表后台基于当前对话场景下的推荐值，一般您应该使用这个推荐值。
• silentTimeout 用户说话的断句时间(单位:ms)。当检测到开始说话后，持续该值时间内没有新的有效文本识别出来，就会触发断句，即触发onSilent事件。推荐值500，最低要求400。
• voiceRequestBegin 声音请求的首包标志，首包时必须为true，非首包时必须为fasle。
• voiceRequestEnd 当使用本地VAD时，声音尾包置成true。
• profileType 音频识别引擎近场或远场，参考com.tencent.xiaowei.def.XWCommonDef.PROFILE_TYPE
• voiceWakeupType 唤醒类型，参考com.tencent.xiaowei.def.XWCommonDef.WAKEUP_TYPE。此处比较复杂，下面详细说明。
• voiceWakeupText 唤醒词文本，UTF-8格式，下面详细说明。
• requestParam 请求时的一些额外参数，位定义，参考com.tencent.xiaowei.def.XWCommonDef.REQUEST_PARAM。

# 语音请求中的唤醒模式

即XWRequestInfo中的voiceWakeupType，目前一共支持3种唤醒模式，分别是：

• WAKEUP_TYPE_DEFAULT 不使用唤醒模式，纯本地唤醒模块唤醒或者是按键唤醒。这种模式下voiceWakeupText无效，您上传的音频数据不得包含唤醒词部分，即这种模式要求您本地能够完全正确地分割唤醒词。
• WAKEUP_TYPE_LOCAL_WITH_TEXT 纯本地唤醒但是需要云端过滤掉唤醒词。这种模式下，voiceWakeupText即为您的唤醒词。您上传的音频数据需要完整包含唤醒词部分，云端会将唤醒词部分去掉。若在音频输入结束后，仍然未能检测到唤醒词部分，将返回错误码并结束本轮请求，表明唤醒失败。因此，若使用此模式，在onRequest方法中拿到最终响应时，应该首先判断唤醒结果，即wakeupFlag，当值为1时表示唤醒失败，请求结束；值为2已经废弃；值为3表示请求正式结束，可以处理最终响应；值为4表示唤醒成功，检测到了唤醒词，此时可以做一些UI展示，请求继续。
• WAKEUP_TYPE_LOCAL_WITH_FREE 全双工模式。这种模式下，语音请求将一直持续，直到设备主动退出或后台下发退出指令。在这个过程中，您会收到多次响应（每次响应的voiceId均不同），最终Idle事件产生时，回调的voiceId为最初请求的voiceId。

# One-Shot模式

当您使用WAKEUP_TYPE_LOCAL_WITH_TEXT模式时，小微支持One-Shot，即用户可以连续说话，也可以在说完唤醒词之后停顿，并在后续说出请求。

# 1. VOICE，语音请求

每轮语音请求，需要多次调用此接口，首次调用时param.voiceRequestBegin应为true，即此字段为true标记着一轮新的请求。小微每次只能同时处理一个对话，因此当新的一轮请求到来时，若上一轮请求尚未结束，则会直接结束上一轮请求。

一般的，您有一个独立的线程去录音，并将录音保存至buffer中，另一个消费线程定时从buffer中取出一定的数据来调用此接口，直到您收到了onSilent事件（云端检测到说话结束）或者您主动停止。若您需要主动停止上传音频，则需要在最后额外调用一次该接口，并将param.voiceRequestEnd置为true，本次接口调用无需传入音频数据。

注意：

• 除了主动停止外，每次音频数据的长度需要介于64和6400之间。
• 主动停止或收到onSilent事件后，再次调用此接口是无效的，会直接返回errcode。

# 2. TEXT，文本请求

此时requestData即为请求文本，UTF-8编码，不得出现emoji、火星文、特殊字符等。在这个模式下，每轮请求只需要调用一次此接口，此时param.voiceRequestBegin应为true。一般的，在文本请求模式下，您不应该响应或进行多轮对话，因为这样的用户体验会很差。

注意：

• 如上文所述，小微每次只能处理一个对话，文本请求也算是一个对话。

# 取消请求

int requestCancel(String voiceId)

若参数为空，则取消当前所有的请求，否则取消对应的voiceID的请求。由于是异步操作，即便您取消了请求，也有可能收到来自后台的推送，这时候您无视即可。

# 设置请求监听

void setAudioRequestListener(in IAudioRequestListener listener)

所有的异步请求以及后台、小程序、APP发起的主动控制，都将从这个listener中回调，这里面只有一个方法，就是boolean onRequest(String voiceId, int event, in XWResponseInfo rspData, in byte[] extendData)。这是一个同步回调接口，回调函数return前后续的回调均会被阻塞，在这个回调中，建议您保存响应数据，并切换线程来具体处理。

关于这个回调的具体内容，请参考接入说明中语音请求部分的发起请求说明。四个参数分别代表：

• voiceId 请求时的voiceId，应该根据这个Id来匹配当初的请求。如果这个voiceId并不在您的请求记录中，则说明本次回调可能是来自后台的直接推送或者小程序端的控制。
• event 响应中的事件，如开始说话，说话结束，最终结果。注意在唤醒模式下，最终结果需要先判断唤醒结果。
• rspData 响应数据。
• extendData 额外的二进制响应数据，在某些特殊情况下或用户定时时会存在，一般是json。

# ICommon

在这个接口中，包含了小微的通用请求，如资源获取、状态上报等。由于历史原因，有一些旧接口，它们仍然可以调用，但本文档不再做解释。

# 上报状态

int reportPlayState(in XWPlayStateInfo stateInfo)

如前文所述，设备状态上报十分关键，状态上报及厂商约束。当您的设备状态发生变化后需要及时调用，无论这个变化来自小微的控制还是用户过自己的控制或是来自设备自己的控制逻辑（如音乐播放完毕自动播放下一首）。

# XWPlayStateInfo

需要上报的状态解释如下：

• appInfo 场景信息，十分关键，不同的场景下小微的NLP会有不同的识别结果。例如您在音乐场景下说播放收藏，即播放音乐收藏，而在FM场景下，则会播放FM收藏。
• state 状态，如暂停、播放，参考XWCommonDef.PlayState。
• availability 设备的可用状态，位或的标志位，参考XWCommonDef.DeviceAvailability。
• playID 播放资源的ID，如果不是在播放url资源，则无需上报。
• playContent 播放资源的内容。
• playOffset 播放偏移量，单位毫秒，为您上报状态前一瞬间的值，例如一首歌总共3分钟，在自动播放完时，上报stop，此时offset为180000。
• playMode 播放模式，顺序播放、随机播放等，XWCommonDef.PlayMode。
• resourceType 资源类型，XWCommonDef.ReportPlayResourceType。
• volume 音量，0~100。
• brightness 亮度，0~100，有屏设备使用。

# 通用请求

String request(String cmd, String subCmd, String params, in IOnRspListener listener)

除了语音\文本请求外，其它通用的资源类请求都通过这个接口进行，这个接口虽然会返回voiceID，但是并不会从IAudioRequestListener.onRequest(...)中回调结果，而是直接从本接口中设置的listener中返回，更加便于管理。通用请求可以同时并发进行，和语音请求不冲突。

在通用请求中，通过cmd和subCmd来区分具体的请求，params是json形式，不同的请求有不同定义。为了便于说明，这里抛出IOnRspListener.onRsp(...)里面的jsonData通用结构，它的结构和XWResponseInfo很相似，或者说是它的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": "对不起,您没有此分类"
}

# 微信互动资源解密

int setDecIamge(String input_path,String key,String output_path);

参数说明：

input_path：需要解密的目标文件路径（需要位于公共目录，既小微设备App有权限访问的文件路径，例如/sdcard/xxx/xxx）

key：资源内容推送中包含的秘钥enckey

output_path：解密后的目标文件路径，解密完成后的文件会写入此路径

需要注意，此方法为同步调用。实际目标文件的大小会影响解密速度，既此方法调用会有耗时过长情况出现，请不要在主线程调用此方法。

# 微信听书

微信听书使用通用请求。功能包括加载更多列表、刷新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），设备修改完倍速后需要上报下当前播放状态

例如：
{
    "appInfo":{
        "ID":"8dab4796-fa37-4114-0051-7637fa2b0001",
        "name":"微信听书",
        "type":0
    },
    "availability":0,
    "brightness":0,
    "playContent":"",
    "playID":"TRA_3103003743_500828",
    "playMode":1,
    "playOffset":0,
    "playSpeed":0, //倍速
    "resourceType":0,
    "state":11,
    "volume":6
}

# 可见可说

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

使用此功能时，首先需要设置词表，调用int setWordslist(int type, in String[] words_list)。words_list为词表数组，UTF-8格式，不得包含emoji、火星文、特殊字符等。

int enableV2A(boolean enable)接口用于打开或关闭可见可说，打开后长期有效，不使用时应该主动关闭。打开后每次请求就会携带setWordslist接口set的词表。

# 上传本地词表

若您的设备支持拨打本地电话（非小微提供的voip），或是打开本地APP等功能，则需要上传本地词表。使用int uploadDatalist(int type, in String[] words_list)，关于每种词表的类型以及各式，请参考代码中的说明。

词表上传之后长期有效，不必每次上传，每当词表变化之后，需要重新全量上传，不支持增量更新。

# 上报自定义日志

void reportUserLog(in XWEventLogInfo log)

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

# IAudioRequestListener

这个接口只有一个回调方法，即:

boolean onRequest(String voiceId, int event, in XWResponseInfo rspData, in byte[] extendData);

当您调用IAIAudio.request(...)、ICommon.{废弃的接口}或直接收到来自小微后台的push后，就会触发这个回调。在这个回调里您需要处理相关的结果，这在后文将详细说明。

# IOnDeviceLoginListener

这个接口的回调都很关键，您需要在Login时set这个Listener并处理这里的事件。

# 设备登录成功

onLoginComplete(int errorCode)

登录成功或失败，errorCode为0则成功，非0您一般需要检查您的登录参数。登录成功后才能使用小微的其它接口。在返回非0的errCode之后，可能会再次产生回调，因为可能由于网络等原因登录失败，直到登录成功。

# 设备退出登录

onLogoutComplete(int errorCode)

退出登录成功，这个接口正常不会回调，因为回调此接口时，您的AIDL应该已经断开了。

# 网络状态变化

onNetStatusChange(int newStatus)

这里的网络状态是指小微和小微后台的心跳情况，和您本地的网络状态没有必然联系。注意将这个回调和登录成功区分开，一般来说，这个接口会在首次登录时回调上线，然后根据网络状态不定期回调。

• newStatus:0离线，1在线。当处于离线时，您的请求可能无法到达，但是这并不绝对，因为离线状态下发起任何请求，会强制触发一次上线尝试，若上线成功，则请求可以正确送达。

# 设备好友变化

当设备好友信息发生变化后，您会收到通知，无论是好友数量、昵称、或是备注，任何信息的改变都将收到onBinderListChange回调。每次初始化设备APP时，如果设备存在好友，都会收到这个回调。

• hasBindToManager(boolean isBinded)这个回调会在设备管理员从无到有和从有到无时触发。
• onBinderListChange(in List<DeviceBinderInfo> binderList)设备绑定列表发生变化后此接口会返回新的绑定列表。每次均是全量好友。

# 二维码刷新

onQrCodeRefresh(in Uri uri)

这个二维码是用于微信或小程序扫码绑定的。当您主动调用IXWService.refreshQRCodeUrl()或当前的二维码过期后，小微会自动刷新二维码，并通过此回调反馈给您。这里返回的是二维码图片，可能为空，空即代表刷新失败。

# IXWSkill

这个接口用于管理技能和拉起设备APP的内置界面，包括联系人、voip、IoT设备管理等。

# 打开联系人界面

void openVoipContactsList()

这个接口用于拉起小微设备APP的联系人界面，在这个界面中，您可以管理联系人，如添加备注、删除联系人、新增联系人、给某个联系人拨打voip等。

# 获取设备IoT列表

void getDeviceIotList()

通过这个接口，拉取设备管理员名下的所有IoT设备列表，渠道定制功能。

# 打开添加好友界面

void bindDeviceContacts()

打开好友添加界面以添加好友。

# voip事件监听

void setVoipEventCallBack(IVoipCallEventListener callEventListener)

当开始voip时，一般的，client端应该停止录音，释放焦点，暂停当前播放的音乐、视频等。当voip结束后自动恢复。这个接口用于设置voip事件监听。

在IVoipCallEventListener中有onVoipStar()和onVoipEnd()事件。您应该根据回调来处理设备状态。

# voip外部控制

在voip通话过程中和通话前，可以通过下面的接口来进行管理和查看状态。

• void startVoipRecord() voip开始录音，这时候小微设备APP会调用android原生的录音接口，此时您应该保证录音通道可用。一般在voip开始后，您释放完所有的录音线程后调用此接口。
• void stopVoipRecord() 暂停/停止voip录音，这个功能相当于通话过程中mute，调用后小微会释放录音占用，此时您可以进行其它的录音操作。
• boolean isVoipMicClosed() 判断当前小微是否在录音。
• boolean isDeviceHasCamera() 小微是否有检测到摄像头，若没有摄像头，将无法进行视频通话。

# ITencentVideo

# 腾讯视频agent控制

小微集成了腾讯视频agent控制能力，若您的设备装有腾讯视频APP和agent，则小微可以通过这个proxy接口来控制腾讯视频APP。这个过程完全由小微设备APP来自动完成，您只需要打开此功能即可。

• void initVideoAgent(IDeviceVideoServiceAidl videoService) 初始化视频中间件，确保您的设备安装了最新版本的腾讯视频APP和agent后调用。