火山引擎-云手机为您提供对接云手机服务的客户端 SDK，支持 Android，iOS，Web/H5 和 Windows 终端接入。本文档描述了云手机 Windows 客户端 SDK 的使用说明，帮助开发者快速接入。 # SDK 接口概览 ## [云渲染引擎实例相关接口](../6394/1156707#云渲染引擎实例相关接口) | **接口名称** | **接口描述** | | --- | --- | | [CreateVeCloudRenderX](../6394/1156707#createvecloudrenderx) | 获取云渲染引擎实例 | | [DestroyVeCloudRenderX](../6394/1156707#destroyvecloudrenderx) | 销毁云渲染引擎实例，回收资源 | ## [云渲染引擎相关接口](../6394/1156707#云渲染引擎相关接口-2) | **接口名称** | **接口描述** | | --- | --- | | [prepare](../6394/1156707#prepare) | 准备 VeCloudRender Engine，初始化云渲染引擎 | | [createPhoneSession](../6394/1156707#createphonesession) | 创建一次云渲染会话，获取 Session 对象 | | [setDebug](../6394/1156707#setdebug) | 是否启用 Debug 调试模式 | | [getDeviceId](../6394/1156707#getdeviceid) | 获取 SDK 生成的设备 ID | | [getSDKVersion](../6394/1156707#getsdkversion) | 获取 SDK 版本信息 | | [updateExpireTimeOneStep](#updateexpiretimeonestep) | 更新拉流 Token 有效期 | | [setExpireTimeListener](#setexpiretimelistener) | 设置更新拉流 Token 有效期的监听器 | ## [云手机场景会话相关接口](../6394/1156707#云手机场景会话相关接口-2) | **接口名称** | **接口描述** | | --- | --- | | [start](../6394/1156707#start) | 启动云手机，开始拉流播放 | | [stop](../6394/1156707#stop) | 停止云手机音视频拉流渲染 | | [getSessionId](../6394/1156707#getsessionid) | 获取会话 ID | | [getSessionStatus](../6394/1156707#getsessionstatus) | 获取会话状态 | | [setListener](../6394/1156707#setlistener) | 设置监听回调 | | [volumeUp](../6394/1156707#volumeup) | 增大云机设备音量 | | [volumeDown](../6394/1156707#volumedown) | 减小云机设备音量 | | [setAudioMute](../6394/1156707#setaudiomute) | 媒体流静音开关 | | [isAudioMuted](../6394/1156707#isaudiomuted) | 检查当前是否处在静音状态 | | [setVideoMute](../6394/1156707#setvideomute) | 媒体流视频开关 | | [isVideoMuted](../6394/1156707#isvideomuted) | 检查当前视频流是否处在停止播放状态 | | [setAutoRecycleTime](../6394/1156707#setautorecycletime) | 设置无操作推流服务回收时长 | | [getAutoRecycleTime](../6394/1156707#getautorecycletime) | 获取已设置的无操作推流服务回收时长 | | [setIdleTime](../6394/1156707#setidletime) | 设置客户端切后台之后，云机服务的保活时间 | | [getIdleTime](#getidletime) | 查询云手机服务的保活时间 | | [switchVideoStreamProfile](../6394/1156707#switchvideostreamprofile) | 切换从云机拉流的清晰度 | | [updateCanvas](../6394/1156707#updatecanvas) | 更新本地渲染画布 | | [startSendVideoStream](../6394/1156707#startsendvideostream) | 开始发送摄像头采集视频流 | | [stopSendVideoStream](../6394/1156707#stopsendvideostream) | 停止发送摄像头采集视频流 | | [switchCamera](../6394/1156707#switchcamera) | 切换摄像头 | | [sendKeyCode](../6394/1156707#sendkeycode) | 发送键盘按键事件（发送一次完整的 DOWN+UP 事件） | | [sendKeyCode](../6394/1156707#sendkeycode-2) | 发送键盘按键事件（可选择发送单状态事件） | | [sendMouseKey](../6394/1156707#sendmousekey) | 发送鼠标按键事件 | | [sendMouseMove](../6394/1156707#sendmousemove) | 发送鼠标移动事件 | | [sendMouseWheelArm](../6394/1156707#sendmousewheelarm) | 发送鼠标滚轮事件（ARM） | | [sendMulitTouch](../6394/1156707#sendmulittouch) | 发送多点触控事件 | | [sendImeComposition](../6394/1156707#sendimecomposition) | 发送输入法事件 | | [sendEditTextInput](../6394/1156707#sendedittextinput) | 发送文本替换云机输入框内容 | | [sendClipBoardMessage](../6394/1156707#sendclipboardmessage) | 发送客户端本地剪贴板数据到云机实例 | | [setKeyboardEnable](../6394/1156707#setkeyboardenable) | 是否启用用户键盘 | | [setLocalKeyboardEnable](../6394/1156707#setlocalkeyboardenable) | 开启本地键盘输入能力 | | [setMouseWheelEnable](../6394/1156707#setmousewheelenable) | 打开或关闭鼠标滚轮 | | [switchBackground](../6394/1156707#switchbackground) | 客户端切换前后台状态 | | [setRemoteForeground](../6394/1156707#setremoteforeground) | 将指定云机应用切换到前台 | | [setNavBarStatus](../6394/1156707#setnavbarstatus) | 设置导航栏开关 | | [getNavBarStatus](../6394/1156707#getnavbarstatus) | 获取导航栏开关状态 | | [rotateScreen](../6394/1156707#rotatescreen) | 屏幕 UI 方向旋转 | | [screenShot](../6394/1156707#screenshot) | 云手机画面截图 | | [setExternalSink](../6394/1156707#setexternalsink) | 设置外部渲染器 | | [sendShakeEventToRemote](../6394/1156707#sendshakeeventtoremote) | 发送"摇一摇"指令到云机实例 | | [sendAudioInjectionEventToRemote](../6394/1156707#sendaudioinjectioneventtoremote) | 发送音频注入的指令到云机实例 | | [setKeyboardType](#setkeyboardtype) | 切换键盘类型 | | [getKeyboardType](#getkeyboardtype) | 查询键盘类型 | | [enableControl](#enablecontrol) | 设置指定用户是否具有云手机操控权 | | [hasControl](#hascontrol) | 查询单个用户是否具有云手机操控权 | | [getAllControls](#getallcontrols) | 查询全部用户的操控权详情 | | [sendChannelMessage](#sendchannelmessage) | 向云手机应用发送文本消息 | | [startRecording](#startrecording) | 发起对云手机画面录屏的请求 | | [stopRecording](#stoprecording) | 停止对云手机画面进行录屏 | | [launchApp](#launchapp) | 启动云手机应用 | | [closeApp](#closeapp) | 关闭云手机应用 | | [setVideoStreamProfileId](#setvideostreamprofileid) | 设置视频流清晰度档位 | | [getVideoStreamProfileId](#getvideostreamprofileid) | 设置当前视频流清晰度档位 | ## [SDK 回调接口](../6394/1156707#sdk-回调接口-2) | **接口名称** | **接口描述** | | --- | --- | | [onStartSuccess](../6394/1156707#onstartsuccess) | 调用 `start()` 启动云手机实例后，播放成功回调，云手机启动成功 | | [onStop](../6394/1156707#onstop) | 云手机实例正常停止推流回调 | | [onFirstAudioFrame](../6394/1156707#onfirstaudioframe) | 启动云手机实例，订阅到音频流后的音频首帧回调 | | [onFirstVideoFrame](../6394/1156707#onfirstvideoframe) | 启动云手机实例，订阅到视频流后的视频首帧回调 | | [onStreamConnectionStateChanged](../6394/1156707#onstreamconnectionstatechanged) | 视频流连接状态切换回调 | | [onRemoteAudioStartRequest](../6394/1156707#onremoteaudiostartrequest) | 收到云机实例请求开始发送音频数据事件 | | [onRemoteAudioStopRequest](../6394/1156707#onremoteaudiostoprequest) | 收到云机实例请求停止发送音频数据事件 | | [onRemoteVideoStartRequest](../6394/1156707#onremotevideostartrequest) | 收到云机实例请求开始发送摄像头数据事件 | | [onRemoteVideoStopRequest](../6394/1156707#onremotevideostoprequest) | 收到云机实例请求停止发送摄像头数据事件 | | [onAudioStats](../6394/1156707#onaudiostats) | 音频流统计信息回调 | | [onVideoStats](../6394/1156707#onvideostats) | 视频流统计信息回调 | | [onVideoSizeChanged](../6394/1156707#onvideosizechanged) | 视频帧修改信息回调 | | [onVideoStreamProfileChange](../6394/1156707#onvideostreamprofilechange) | 调用切换清晰度档位切换回调 | | [onGetAutoRecycleTimeResult](../6394/1156707#ongetautorecycletimeresult) | 获取已设置的无操作推流服务回收时长结果回调 | | [onNetworkQuality](../6394/1156707#onnetworkquality) | 当前网络状态回调 | | [onClipBoardMessageReceived](../6394/1156707#onclipboardmessagereceived) | 收到云机实例返回的剪贴板数据回调 | | [onKeyboardEnable](../6394/1156707#onkeyboardenable) | 是否启用本地键盘回调 | | [onNavBarStatus](../6394/1156707#onnavbarstatus) | 云手机当前导航栏开关状态变化回调 | | [onBackgroundSwitched](../6394/1156707#onbackgroundswitched) | 云机收到本地用户状态后的回调(通过switchBackground设置)| | [onRemoteRotation](../6394/1156707#onremoterotation) | 云机实例屏幕旋转回调 | | [onLocalScreenRotate](../6394/1156707#onlocalscreenrotate) | 本地容器旋转回调 | | [onEditExchanged](../6394/1156707#oneditexchanged) | 云机输入框更新 | | [onScreenShot](../6394/1156707#onscreenshot) | 云手机画面截图结果回调 | | [onKeyboardTypeChanged](#onkeyboardtypechanged) | 键盘类型改变的回调 | | [onGetKeyboardTypeResult](#ongetkeyboardtyperesult) | 查询键盘类型结果回调 | | [onControlStateChanged](#oncontrolstatechanged) | 设置操控权并且成功的结果回调 | | [onEnableControlResult](#onenablecontrolresult) | 设置操控权的结果回调 | | [onHasControlResult](#onhascontrolresult) | 查询某个用户操控权的结果回调 | | [onAllControlsResult](#onallcontrolsresult) | 查询所有用户操控权的结果回调 | | [onWarning](../6394/1156707#onwarning) | SDK 内部产生的警告回调 | | [onError](../6394/1156707#____onerror) | SDK 内部产生的错误回调，产生错误会调用`stop()`停止从云机拉流 | # 接口详细说明 ## 云渲染引擎实例相关接口 ### CreateVeCloudRenderX 描述：获取云渲染引擎实例。语法： ```cpp VeCloudRenderX* CreateVeCloudRenderX(); ``` 参考示例： ```cpp VeCloudRenderX* veCloudRenderX = vecommon::CreateVeCloudRenderX(); ``` ### DestroyVeCloudRenderX 描述：销毁云渲染引擎实例，释放资源。语法： ```cpp void DestroyVeCloudRenderX(); ``` 参考示例： ```cpp vecommon::DestroyVeCloudRenderX(); ``` ## 云渲染引擎相关接口 ### prepare 描述：初始化云渲染引擎（VeCloudRenderX Engine）。使用云手机 Windows SDK 能力之前，必须调用此接口进行初始化。语法： ```cpp bool prepare(); ``` ### createPhoneSession 描述：创建一次云渲染会话，获取 Session 对象。语法： ```cpp PhoneSession* createPhoneSession( const PhoneSessionConfig& config, ISessionListener* listener); ``` | **参数** | **说明** | | --- | --- | | config | 创建会话配置信息，具体配置参数见 [PhoneSessionConfig](../6394/1156707#phonesessionconfig-structure) 结构说明 | | listener | 创建会话相关回调，回调类接口函数见 [SDK 回调接口](../6394/1156707#sdk-回调接口-2) | ### setDebug 描述：是否启用 Debug 调试模式。开启调试模式下可调用其他调试相关接口，打印更详细的日志。语法： ```cpp void setDebug(bool debug, const char* logDir); ``` | **参数** | **描述** | | --- | --- | | debug | 是否启用调试模式： |\ |||\ || - true（启用） |\ || |\ || - false（关闭） | | logDir | 调试日志保存路径 | ### getDeviceId 描述：获取 SDK 生成的设备 ID，用于后台查询 SDK 日志，进行调试和问题排查。语法： ```cpp const char* getDeviceId(); ``` ### getSDKVersion 描述：获取 SDK 版本信息。语法： ```cpp const char* getSDKVersion(); ``` ### updateExpireTimeOneStep 描述：拉流过程中动态更新 Token 过期时间。若启动拉流时限定了拉流 Token 有效期，Token 到期前 30s 时会收 21034001 警告码，提示拉流即将过期，期间可调用本接口更新 Token 到期时间，延长拉流时间。若未更新，则到期后将自动断开与云手机实例的连接。语法： ```cpp virtual int updateExpireTimeOneStep( const ExpireTimeConfig& config, IExpireTimeListener* listener ) = 0; ``` | **参数** | **描述** | | --- | --- | | config | 配置信息，参看 [ExpireTimeConfig](#expiretimeconfig-structure)。| | listener | 更新过期时间的监听器。参看 [IExpireTimeListener](#iexpiretimelistener)。 | ### setExpireTimeListener 描述：设置更新拉流 Token 有效期的监听器。语法： ```cpp virtual void setExpireTimeListener(IExpireTimeListener* listener) = 0; ``` | **参数** | **描述** | | --- | --- | | listener | 更新 Token 过期时间的监听器。参看 [IExpireTimeListener](#iexpiretimelistener)。 | ## 云手机场景会话相关接口 ### start 描述：初始化云渲染引擎成功后，调用 `start()`，启动云手机。语法： ```cpp // 不使用 OpenAPI BatchPodStart 请求，使用不带参数的 start 接口 void start(); // 使用 OpenAPI BatchPodStart 请求，则使用带参数的 start 接口。 // podInfoJson 为 OpenAPI BatchPodStart 请求获得的 JSON 字符串。 // JSON 字符串形如： //{ // "PodId": "734768***3002796", // "ServerSessionId": "res_73512958***69228", // "MediaList": [ // { // "PodUserId": "734768***873002796_0-0", // "RoomId": "cros_01_73476893***02796_grb2shx32x", // "Token": "00165e537b51593a40***bPCn4Vn82wgTI0OjuULYM=", // "Width": 720, // "Height": 1280, // "Rotation": 0, // "RotationMode": "portrait", // "VideoStreamProfileId": 9501 // } // ], // "PodStatus": 100, // "SKey": "Yzc1MGY5ZTI5Z***lOGY0OQ==", // "ExpectedRtcIdc": "boe-tjjnsx-2b0c61ac", // "StreamProvider": "bytertc", // "MediaAppId": "65e537b5***a4016b106178" // } void start(const char* podInfo); ``` ### stop 描述：停止云手机。语法： ```cpp void stop(); ``` ### getSessionId 描述：获取云手机会话 ID。语法： ```cpp const char* getSessionId(); ``` ### getSessionStatus 描述：获取云手机会话状态，状态定义参考 [getSessionStatus](../6394/1156707#sessionstatus-enum) 的具体枚举值。语法： ```cpp vecommon::SessionStatus getSessionStatus(); ``` ### setListener 描述：设置监听回调。建议在调用 `start` 启动云手机会话之前设置监听。语法： ```cpp void setListener(ISessionListener* listener); ``` ### volumeUp 描述：增大云机设备音量。语法： ```cpp void volumeUp() = 0; ``` ### volumeDown 描述：减小云机设备音量。语法： ```cpp void volumeDown() = 0; ``` ### setAudioMute 描述：静音开关，是否停止拉取云机音频流。语法： ```cpp void setAudioMute(bool mute) = 0; ``` | **参数** | **描述** | | --- | --- | | mute | 是否静音： |\ |||\ || - true（静音） |\ || |\ || - false（开音，默认） | ### isAudioMuted 描述：检查当前是否处在静音状态，返回：true: 静音； false：开音。返回值：Booblean，返回当前是否处在静音状态（true：静音；false：开音）。语法： ```cpp bool isAudioMuted() = 0; ``` ### setVideoMute 描述：媒体流视频开关。语法： ```cpp void setVideoMute(bool mute) = 0; ``` | **参数** | **描述** | | --- | --- | | mute | 是否停止播放视频流： |\ |||\ || - true（停止） |\ || |\ || - false（播放，默认） | ### isVideoMuted 描述：检查媒体流视频播放状态。返回值：Booblean，返回当前视频流是否处在暂停播放状态（true：停止；false：播放）。语法： ```cpp bool isVideoMuted() = 0; ``` ### setAutoRecycleTime 描述：在云手机运行过程中动态设置无操作回收服务时长。若该时长内客户端没有任何操作，云手机实例将停止推流并自动退出。该接口需在 `start` 调用成功、且收到 `onFirstVideoFrame` 回调之后调用。设置结果通过 [`onAutoRecycleTimeChanged`](#onautorecycletimechanged) 回调返回。语法： ```cpp int setAutoRecycleTime(int time); ``` | **参数** | **描述** | | --- | --- | | seconds | 无操作服务回收时长，单位：秒。支持最大设置 86400 秒，即 24 小时。若不设置或设置为 0，则使用默认时长 300 秒。超时后，客户端会收到云手机实例退出事件。 | 返回值 - `0`：调用成功 - `<0`：调用失败 ### getAutoRecycleTime 描述：获取已设置的无操作回收服务时长，结果通过 [`onGetAutoRecycleTimeResult`](#ongetautorecycletimeresult) 回调返回。语法： ```cpp int getAutoRecycleTime(); ``` ### setIdleTime 描述：在云手机运行过程中，您可使用此接口动态设置客户端切换到后台时，云手机服务的保活时长。说明： 1. 请先将 [switchBackground](../6394/1156707#switchbackground) 的 `state` 设置为 `true`，再使用 [setIdleTime](../6394/1156707#setidletime) 接口设置保活时间。 2. 设置结果通过 [`onIdleTimeChanged`](#onidletimechanged) 回调返回。语法： ```cpp int setIdleTime(int time); ``` | **参数** | **描述** | | --- | --- | | time | 切换到后台后，云机服务的保活时长，默认值为 300，取值范围为 (0,7200]，单位为秒。 | ### getIdleTime 描述：获取云手机服务的保活时长。查询结果通过 [`onGetIdleTimeResult`](#ongetidletimeresult) 回调返回。语法： ```cpp int getIdleTime() = 0; ``` ### switchVideoStreamProfile 描述：在云手机运行过程中，通过指定清晰度档位 ID，切换视频流的清晰度。设置成功后会调用`ISessionListener::onVideoSizeChanged` 回调。语法： ```cpp void switchVideoStreamProfile(int profileId) = 0; ``` | **参数** | **说明** | | --- | --- | | profileId | 云手机视频流清晰度配置；可选清晰度档位 ID 和对应的清晰度配置，参考 [云手机清晰度档位说明](../6394/155915)。| ### updateCanvas 描述：更新本地渲染画布。语法： ```cpp void updateCanvas(void* canvas) = 0; ``` | **参数** | **说明** | | --- | --- | | canvas | 需要更新的本地渲染画布 | ### startSendVideoStream 描述：开始发送本地摄像头数据。语法： ```cpp void startSendVideoStream() = 0; ``` ### stopSendVideoStream 描述：停止发送本地摄像头数据。语法： ```cpp void stopSendVideoStream() = 0; ``` ### switchCamera 描述：切换摄像头（默认为前置摄像头 `#CameraId::Front`）。语法： ```cpp void switchCamera(CameraId id) = 0; ``` | **参数** | **描述** | | --- | --- | | CameraId | 切换摄像头 ID | ### sendKeyCode 描述：发送键盘按键事件指令到云机实例。此接口是发送一次完整的 DOWN+UP 事件，如需模拟 Home键、返回键、菜单键等系统功能键，推荐使用。有关 Android 系统支持的键盘事件和键值，参考：[https://developer.android.com/reference/android/view/KeyEvent](https://developer.android.com/reference/android/view/KeyEvent)。语法： ```cpp void sendKeyCode(const int keyCode) = 0; ``` | **参数** | **描述** | | --- | --- | | keyCode | 事件的键值，当前支持以下键盘事件： |\ |||\ || - 3（`HOME`，Home键） |\ || |\ || - 4（`BACK`，返回键） |\ || |\ || - 82（`MENU`，菜单键） |\ || |\ || - 187（`APP_SWITCH`，最近任务列表） | ### sendKeyCode 描述：发送键盘按键事件指令到云机实例。此接口可以选择发送单状态（DOWN 或 UP 事件），如需模拟一些状态要求较高的按键事件，如 DELETE 等，推荐使用。有关 Android 系统支持的键盘事件和键值，参考：[https://developer.android.com/reference/android/view/KeyEvent](https://developer.android.com/reference/android/view/KeyEvent)。语法： ```cpp void sendKeyCode(const int keyCode, bool down) = 0; ``` | **参数** | **描述** | | --- | --- | | keyCode | 事件的键值，当前支持以下键盘事件： |\ |||\ || - 3（`HOME`，Home键） |\ || |\ || - 4（`BACK`，返回键） |\ || |\ || - 82（`MENU`，菜单键） |\ || |\ || - 187（`APP_SWITCH`，最近任务列表） | | down | 按键状态： |\ |||\ || - true：DOWN 状态 |\ || |\ || - false：UP 状态 | ### sendMouseKey 描述：发送鼠标按键事件。语法： ```cpp void sendMouseKey(const MouseKeyData& data) = 0; ``` | **参数** | **描述** | | --- | --- | | data | 参考 [MouseKeyData](../6394/1156707#mousekeydata-structure) 结构说明 | ### sendMouseMove 描述：发送鼠标移动事件。语法： ```cpp void sendMouseMove(const MouseMoveData& data) = 0; ``` | **参数** | **描述** | | --- | --- | | data | 参考 [MouseMoveData](../6394/1156707#mousemovedata-structure) 结构说明 | ### sendMouseWheelArm 描述：发送鼠标滚轮事件（ARM）。语法： ```cpp void sendMouseWheelArm(const MouseWheelDataArm& data) = 0; ``` | **参数** | **描述** | | --- | --- | | data | 参考 [MouseWheelDataArm](../6394/1156707#mousewheeldataarm-structure) 结构说明 | ### sendMulitTouch 描述：通过该接口可以发送多点触控事件，如果您需要进行单点鼠标操作，请使用 [sendMouseKey](../6394/1156707#sendmousekey) 接口。说明：在使用 [sendMulitTouch](../6394/1156707#sendmulittouch) 接口时，需要确保触摸点的 `pointId` 按照从 0 开始升序的规则进行标识。当存在多个触摸点时，`pointId` 需要遵循补位前序规则，例如，当前有 3 个触控点，序号分别为 0、1、2，如果 1 号点位释放，新增的触控点会使用被释放序号 1。SDK最多支持同时生效的触摸点数量为5个。语法： ```cpp void sendMulitTouch(const vecommon::MulitTouchData& data) = 0; ``` | **参数** | **描述** | | --- | --- | | data | 发送多点触控事件的相关信息。详情请参考 [MulitTouchData](../6394/1156707#mulittouchdata-structure) 结构说明。 | ### sendImeComposition 描述：发送输入法事件。语法： ```cpp void sendImeComposition(const ImeCompositionData& data) = 0; ``` | **参数** | **描述** | | --- | --- | | data | 参考 [ImeCompositionData](../6394/1156707#imecompositiondata-structure) 结构说明 | ### sendEditTextInput 描述：发送文本替换云机输入框内容（当云机输入框在焦点上才会生效）。语法： ```cpp void sendEditTextInput(const char* txt) = 0; ``` | **参数** | **描述** | | --- | --- | | text | 发送的文本内容，必须为 UTF-8 编码 | ### sendClipBoardMessage 描述：发送客户端本地剪贴板数据到云机，支持发送文本数据。语法： ```cpp void sendClipBoardMessage(const char* clipText) = 0; ``` | **参数** | **描述** | | --- | --- | | clipText | 发送的剪贴板数据，必须为 UTF-8 编码 | ### setKeyboardEnable 描述：开启使用云机键盘能力。语法： ```cpp void setKeyboardEnable(bool enable) = 0; ``` | **参数** | **描述** | | --- | --- | | enable | 是否开启云机键盘输入能力： |\ |||\ || - true（开启） |\ || |\ || - false（关闭） | ### setLocalKeyboardEnable 描述：开启本地键盘输入能力。语法： ```cpp void setLocalKeyboardEnable(bool enable) = 0; ``` | **参数** | **描述** | | --- | --- | | enable | 是否启用用户本地键盘： |\ |||\ || - true（开启） |\ || |\ || - false（关闭） | ### setMouseWheelEnable 描述：打开或关闭鼠标滚轮。语法： ```cpp void setMouseWheelEnable(bool enable) = 0; ``` | **参数** | **描述** | | --- | --- | | enable | 是否开启本地鼠标滑轮滚动映射 | ### switchBackground 描述：设置客户端的前后台状态，并将状态同步到云机。您可以使用该方法通知云机，获取当前客户端的使用状态。说明：如果您要设置客户端在切换到后台后服务端服务的保活时间，请先将 [switchBackground](../6394/1156707#switchbackground) 的 `state` 设置为 `true`，再使用 [setIdleTime](../6394/1156707#setidletime) 接口设置保活时间。语法： ```cpp void switchBackground(bool state) = 0; ``` | **参数** | **描述** | | --- | --- | | state | 客户端的前后台状态：\ ||- ture：客户端切换到后台 \ ||- false：客户端切换到前台 | ### setRemoteForeground 描述：将指定云机应用切换到前台。语法： ```cpp void setRemoteForeground(const char* pkgName) = 0; ``` | **参数** | **描述** | | --- | --- | | pkgName | 切换前台的云机应用包名 | ### setNavBarStatus 描述：设置云手机当前导航栏开关状态（打开/隐藏）。语法： ```cpp void setNavBarStatus(int status) = 0; ``` | **参数** | **描述** | | --- | --- | | status | 设置导航栏开关状态，枚举值如下： |\ |||\ || - 1（打开导航栏，launcher和非全面屏应用会显示导航栏；全面屏应用的导航栏自动隐藏） |\ || |\ || - 0（隐藏导航栏） | ### getNavBarStatus 描述：获取云手机当前导航栏开关状态（通过 `onNavBarStatus(int status, int reason)` 回调）。语法： ```cpp void getNavBarStatus() = 0; ``` ### rotateScreen 描述：屏幕 UI 方向旋转（顺时针方向）。语法： ```cpp void rotateScreen(const vecommon::RotateDegree degree, bool podAutoRotation) = 0; ``` | **参数** | **描述** | | --- | --- | | degree | 设置本地容器旋转的角度： |\ |||\ || - 0：竖屏显示 |\ || |\ || - 90：横屏显示 |\ || |\ || - 180：画面翻转竖屏显示 |\ || |\ || - 270：画面翻横竖屏显示 | | podAutoRotation | 本地渲染旋转的同时云机是否同步旋转（云机旋转支持角度 0、90、270）: |\ |||\ || - true：本地容器 UI 屏幕方向旋转，且云机屏幕同步进行旋转 |\ || |\ || - false：本地容器 UI 屏幕方向旋转，但云机屏幕不旋转 | ### screenShot 描述：对当前云手机画面进行截图，并获取在云手机实例中保存截图文件的路径以及下载截图文件的地址。语法： ```cpp void screenShot(bool saveOnPod) = 0; ``` | **参数** | **描述** | | --- | --- | | saveOnPod | 是否保存截图文件在云手机实例： |\ |||\ || - true（上传截图文件到火山引擎对象存储，并保存截图文件在云手机实例中） |\ || |\ || - false（上传截图文件到火山引擎对象存储，上传完成后，删除保存在云手机实例中的文件，默认） |\ || |\ |||\ || 截图文件保存和清理逻辑如下： |\ |||\ || - 当保存截图文件在云手机实例时，截图达到1000张时会清理之前保存的截图文件； |\ || |\ || - 当上传截图文件到对象存储时，截图上传到对象存储成功后再清理云手机实例中的截图文件； |\ || |\ || - 当云手机存储空间小于600MB时，如指定 `saveOnPod=true`，则不可执行截图操作；如指定 `saveOnPod=false`，可执行截图操作。 | ### setExternalSink 描述：如果您要通过外部渲染方式获取并处理每帧数据，或者进行自渲染，建议您使用此接口。说明：在使用外部渲染器时，请将 [SessionConfig](../6394/1156707#sessionconfig-structure) 中的 `canvas`参数设置为 `nullptr`。语法： ```cpp void setExternalSink(VeExternalSink* externalSink) = 0; ``` | **参数** | **描述** | | --- | --- | | externalSink | 外部渲染器回调，具体请参考 [VeExternalSink](../6394/1156707#veexternalsink) 定义。 | ### sendShakeEventToRemote 描述：该方法用于向云机实例发送“摇一摇”指令，云机实例会使用传感器来模拟“摇一摇”的操作。返回值 - `>0`：调用成功 - `<0`：调用失败说明：调用此接口，会触发 [`onShakeResponse`](#onshakeresponse) 回调。语法： ```cpp int sendShakeEventToRemote(int duration) = 0; ``` | **参数** | **描述** | | --- | --- | | duration | “摇一摇”时长，单位：毫秒，取值范围：[1800, 30000]。 | ### sendAudioInjectionEventToRemote 描述：该方法用于发送指令将预置音频注入云机实例，以实现例如模拟吹气等效果。返回值 - `>0`：调用成功 - `<0`：调用失败说明：调用此接口，会触发 [`onAudioInjectionResponse`](#onaudioinjectionresponse) 回调。语法： ```cpp int sendAudioInjectionEventToRemote(const vecommon::AudioInjectionCmd cmd, const char* filePath) = 0； ``` | **参数** | **描述** | | --- | --- | | cmd | 音频注入命令 1: 开始注入 0: 停止注入, 参考{vecommon::AudioInjectionCmd}摇一摇时长，单位：毫秒，取值范围：[1800, 30000]。 | | filePath | 云机实例的音频文件所在目录，只有开始注入时才需要该目录，停止注入时可以传入 `nullptr`。 | ### setAudioInjectionState 描述：设置云机实例的音频注入状态 | **参数** | **描述** | | --- | --- | | state | 音频注入状态

true：开启

false：关闭

| 返回值 - `0`：调用成功 - `<0`：调用失败语法： ```cpp int setAudioInjectionState(bool state) = 0; ``` ### getAudioInjectionState 描述：查询云机实例的音频注入状态。返回值 - `0`：调用成功 - `<0`：调用失败语法： ```cpp int getAudioInjectionState() = 0; ``` ### setVideoInjectionState 描述：设置云机实例的视频注入状态。 | **参数** | **描述** | | --- | --- | | state | 视频注入状态

true：开启

false：关闭

| 返回值 - `0`：调用成功 - `<0`：调用失败语法： ```cpp int setVideoInjectionState(bool state) = 0; ``` ### getVideoInjectionState 描述：查询云机实例的视频注入状态。返回值 - `0`：调用成功 - `<0`：调用失败语法： ```cpp int getVideoInjectionState() = 0; ``` ### setKeyboardType 描述：切换本地/云机键盘。切换结果会通过 [`onKeyboardTypeChanged`](#onkeyboardtypechanged) 返回。语法： ```cpp int setKeyboardType(const vecommon::KeyboardType type) = 0; ``` | **参数** | **描述** | | --- | --- | | type | 键盘类型，参看 [`KeyboardType`](#keyboardtype) | 返回值 - `0`：调用成功 - `<0`：调用失败说明：需要在云手机属性 persist.sys.native_ime 设置为 true 的前提下，该接口才能生效；详细说明，参考 [System Properties 属性列表](671880#system-properties-属性列表) ### getKeyboardType 描述：获取当前使用的键盘类型。查询结果会通过 [`onGetKeyboardTypeResult`](#ongetkeyboardtyperesult) 返回。语法： ```cpp int getKeyboardType() = 0; ``` 返回值 - `0`：调用成功 - `<0`：调用失败 ### enableControl 描述：设置指定用户是否具有云手机操控权。当多个用户通过不同客户端连接到同一云手机实例时，支持通过本接口开启或关闭某用户对云手机的操控权。请结合具体业务场景，按需分配云手机的操控权。语法： ```cpp int enableControl(const std::string& userId, bool enable) = 0; ``` | **参数** | **描述** | | --- | --- | | userId | 指定用户 ID。 | | enable | 开启或关闭该用户对云手机的操控权。

true：开启，默认设置，即每个新用户连接云手机时默认具备操控权；

false：关闭。

| 返回值 - `0`：调用成功 - `<0`：调用失败说明：成功设置操控权后，调用者会收到 [`onEnableControlResult`](#onenablecontrolresult) 回调；房间内所有用户会收到 [`onControlStateChanged`](#oncontrolstatechanged) 回调。 ### hasControl 描述：查询单个用户是否具有云手机操控权。查询全部用户的操控权详情可使用 [`getAllControls`](#getallcontrols) 接口。查询结果将通过 [`onHasControlResult`](#onhascontrolresult) 回调返回。语法： ```cpp int hasControl(const std::string& userId) = 0; ``` | **参数** | **描述** | | --- | --- | | userId | 需要查询的用户 ID。 | 返回值 - `0`：调用成功 - `<0`：调用失败 ### getAllControls 描述：查询全部用户的操控权详情。查询单个用户是否具有云手机操控权可使用 [`hasControl`](#hascontrol) 接口。查询结果将通过 [`onAllControlsResult`](#onallcontrolsresult) 回调返回。语法： ```cpp int getAllControls() = 0; ``` 返回值 - `0`：调用成功 - `<0`：调用失败 ### sendChannelMessage 描述：向云手机应用发送文本消息。消息收发类接口需结合 Message Channel SDK 使用，Message Channel SDK 使用方法参考 [Message Channel SDK 接入说明](https://www.volcengine.com/docs/6394/95333)。语法： ```cpp vecommon::ChannelMessage sendChannelMessage(const std::string& payload, bool needAck, const std::string& destChannelUid); ``` | **参数** | **描述** | | --- | --- | | payload | 文本消息内容，不超过 60KB。 | | needAck | 是否需要消息接收回执。

true：是（默认值）；

false：否。 | | destChannelUid | 当云手机端有多个应用注册消息通道时，可以使用本参数指定目标应用的消息通道 ID。 | 返回值：[`ChannelMessage`](#channelmessage-structure) 消息实体。 ### startRecording 描述：对当前云手机画面进行录屏。录制结果通过 [`onRecordingStatus`](#onrecordingstatus) 回调。调用 [`stopRecording`](#stoprecording) 可停止屏幕录制。语法： ```cpp int startRecording(int duration, bool saveOnPod); ``` | **参数** | **描述** | | --- | --- | | duration | 录制时长，单位为秒，支持设置的最大值为 14400 ，即 4 小时。 | | saveOnPod | 录屏文件将自动上传至火山引擎对象存储，您可以使用本参数设置是否同时将录屏文件保留在云手机实例中。

true：上传录屏文件到火山引擎对象存储的同时，保留云手机实例中的录屏文件；

false：（默认）上传录屏文件到火山引擎对象存储后，删除保存在云手机实例中的录屏文件。

录屏文件保存和清理逻辑如下：

若选择保留录屏文件在云手机实例，当 /sdcard/Pictures/Recordings/ 路径下的录屏文件超过 500 个时，会自动清理之前保存的录屏文件；

录屏文件在火山引擎对象存储中保存的时间为 24 小时。

| 返回值 - `0`：调用成功 - `<0`：调用失败 ### stopRecording 描述：停止对当前云手机画面进行录屏。语法： ```cpp int stopRecording(); ``` 返回值 - `0`：调用成功 - `<0`：调用失败 ### launchApp 描述：启动云手机应用。调用 [`closeApp`](#closeapp) 可关闭应用。语法： ```cpp int launchApp(const std::string& pkgName); ``` | **参数** | **描述** | | --- | --- | | pkgName | 启动的应用包名。 | 返回值 - `0`：调用成功 - `<0`：调用失败 ### closeApp 描述：关闭云手机应用。语法： ```cpp int closeApp(const std::string& pkgName); ``` | **参数** | **描述** | | --- | --- | | pkgName | 关闭的应用包名。 | 返回值 - `0`：调用成功 - `<0`：调用失败 ### setVideoStreamProfileId 描述：设置当前视频流清晰度档位。语法： ```cpp int setVideoStreamProfileId(int profileId); ``` | **参数** | **描述** | | --- | --- | | profileId | 清晰度档位 ID，可选值和清晰度配置说明参看[云手机清晰度档位说明](https://www.volcengine.com/docs/6394/155915)。 | 返回值 - `0`：调用成功 - `<0`：调用失败 ### getVideoStreamProfileId 描述：查询当前视频流清晰度档位。查询结果通过 [`onGetVideoStreamProfileIdResult`](#ongetvideostreamprofileidresult) 回调。语法： ```cpp int getVideoStreamProfileId(); ``` 返回值 - `0`：调用成功 - `<0`：调用失败 ## SDK 回调接口 ### onStartSuccess 描述：调用 `start()` 启动云手机后，播放成功回调，云手机启动成功。语法： ```cpp void onStartSuccess(int video_stream_profile, const char* round_id, const char* target_id, const char* plan_id) { (void)video_stream_profile; (void)round_id; (void)target_id; (void)plan_id; }; ``` | **参数** | **说明** | | --- | --- | | video\_stream\_profile | 当前云手机画面的清晰度 | | round\_id | 当次启动的生命周期标识符 | | target\_id | 云手机实例 ID | | plan\_id | 云手机实例套餐 ID | ### onStop 描述：云手机正常停止推流回调。语法： ```cpp void onStop(); ``` ### onFirstAudioFrame 描述：启动云手机开始拉流后的音频首帧回调。语法： ```cpp void onFirstAudioFrame(); ``` ### onFirstVideoFrame 描述：启动云手机开始拉流后的视频首帧回调。语法： ```cpp void onFirstVideoFrame(const vecommon::VideoFrameInfo& info) { (void)info; }; ``` | **参数** | **说明** | | --- | --- | | info | 拉流收到的视频帧信息，参考 [VideoFrameInfo](../6394/1156707#videoframeinfo-structure) 结构说明 | ### onStreamConnectionStateChanged 描述：视频流连接状态改变回调。语法： ```cpp void onStreamConnectionStateChanged(vecommon::StreamConnectionState state) { (void)state; } ``` | **参数** | **说明** | | --- | --- | | state | 视频流连接状态切换后的状态，具体状态值和描述如下： |\ |||\ || - 1（连接断开，断网 12s 触发，内部自动重连） |\ || |\ || - 2（首次请求建立连接，正在连接中） |\ || |\ || - 3（首次连接成功） |\ || |\ || - 4（首次连接时，10秒连接不成功；或连接成功后，断连 10 秒，自动重连中） |\ || |\ || - 5（连接断开后重连成功） |\ || |\ || - 6（网络连接断开超过 10 秒，且期间重连未成功） |\ || |\ || - 7（服务端异常状态导致失败，不会自动重试，可联系技术支持） | ### onRemoteAudioStartRequest 描述：收到云机实例请求开始发送音频数据事件。语法： ```cpp void onRemoteAudioStartRequest(); ``` ### onRemoteAudioStopRequest 描述：收到云机实例请求停止发送音频数据事件。语法： ```cpp void onRemoteAudioStopRequest(); ``` ### onRemoteVideoStartRequest 描述：收到云机实例请求开始发送摄像头数据事件。语法： ```cpp void onRemoteVideoStartRequest(); ``` ### onRemoteVideoStopRequest 描述：收到云机实例请求停止发送摄像头数据事件。语法： ```cpp void onRemoteVideoStopRequest(); ``` ### onAudioStats 描述：音频流统计信息回调，统计周期为 2 秒。语法： ```cpp void onAudioStats(const vecommon::AudioStats& stats) { (void)stats; } ``` | **参数** | **说明** | | --- | --- | | stats | 云机音频流统计信息，具体说明，见 [AudioStats structure](../6394/1156707#audiostats-structure) | ### onVideoStats 描述：视频流统计信息回调，统计周期为 2 秒。语法： ```cpp void onVideoStats(const vecommon::VideoStats& stats) { (void)stats; } ``` | **参数** | **说明** | | --- | --- | | stats | 云机视频流统计信息，具体说明，见 [VideoStats structure](../6394/1156707#videostats-structure) | ### onVideoSizeChanged 描述：云机视频帧修改信息回调。语法： ```cpp void onVideoSizeChanged(const vecommon::VideoFrameInfo& info) { (void)info; } ``` | **参数** | **说明** | | --- | --- | | info | 云机视频帧信息，具体说明，见 [VideoFrameInfo structure](../6394/1156707#videoframeinfo-structure) | ### onVideoStreamProfileChange 描述：调用切换清晰度档位切换回调。语法： ```cpp void onVideoStreamProfileChange(bool result, int from, int to) { (void)result; (void)from; (void)to; } ``` | **参数** | **描述** | | --- | --- | | result | 清晰度档位是否切换结果 | | from | 切换前的清晰度档位 ID | | to | 切换后的清晰度档位 ID | ### onAutoRecycleTimeChanged 描述：无操作回收时长发生改变的回调。语法： ```cpp virtual void onAutoRecycleTimeChanged(const std::string& callUserId, int code, int time) { (void)callUserId; (void)code; (void)time; } ``` | **参数** | **描述** | | --- | --- | | callUserId | 改变无操作回收时长的用户 ID。 | | code | 操作结果。

0：成功；

<0：失败。

| | time | 无操作回收时长。 | ### onGetAutoRecycleTimeResult 描述：获取无操作回收时长的结果回调。语法： ```cpp virtual void onGetAutoRecycleTimeResult(int code, int time) { (void)code; (void)time; } ``` | **参数** | **描述** | | --- | --- | | code | 查询结果。

0：成功；

<0：失败。

| | time | 无操作回收时长。 | ### onNetworkQuality 描述：当前网络状态回调，2 秒回调一次。语法： ```cpp void onNetworkQuality(vecommon::NetworkQualityState state) { (void)state; } ``` | **参数** | **描述** | | --- | --- | | state | 网络质量状态： |\ || 1：Excellent（表示当前网络状况极佳，能够高质量承载当前业务） |\ || 2：Good（表示当前网络状况良好，能够较好地承载当前业务） |\ || 3：Poor（表示当前网络状况有轻微劣化，但不影响正常使用） |\ || 4：Bad（表示当前网络质量欠佳，会影响当前业务的主观体验） |\ || 5：VeryBad（表示当前网络已经无法承载当前业务的媒体流，需要采取相应策略，比如降低媒体流的码率或者更换网络） |\ || 6：Down（表示当前网络完全无法正常通信） | ### onClipBoardMessageReceived 描述：客户端收到收到云机返回的剪贴板数据回调。语法： ```cpp void onClipBoardMessageReceived( const char* str ); ``` | **参数** | **描述** | | --- | --- | | str | 接收到的消息内容，为字符串 | ### onKeyboardEnable 描述：是否启用本地键盘回调。语法： ```cpp void onKeyboardEnable(bool enable) { (void)enable; } ``` | **参数** | **描述** | | --- | --- | | enable | 是否启用用户本地键盘 | ### onNavBarStatus 描述：云手机当前导航栏开关状态变化回调。语法： ```cpp void onNavBarStatus(int status, int reason) { (void)status; (void)reason; } ``` | **参数** | **描述** | | --- | --- | | status | 状态： |\ |||\ || - 0：导航栏隐藏 |\ || |\ || - 1：非全面屏应用显示导航栏 |\ || |\ || - \-1：参数错误 | | reason | 导航栏开关状态变化原因： |\ |||\ || - 0（服务端切换操作的回调） |\ || |\ || - 1（SDK调用，getNavBarStatus 方法返回结果） |\ || |\ || - 2（SDK调用，setNavBarStatus 方法返回结果） |\ || |\ || - \-1（SDK 查询错误） | ### onBackgroundSwitched 描述：在云机接收到本地用户状态后的回调。语法： ```cpp void onBackgroundSwitched(bool state) { (void)state; } ``` | **参数** | **描述** | | --- | --- | | state | 用户切换后的状态：\ ||- true：处于后台状态 |\ || |\ || - false：处于前台状态 | ### onRemoteRotation 描述：云机实例屏幕旋转回调。调用 `rotateScreen(vecommon::RotateDegree degree)` 成功后会回调，此时拉流渲染方向已经改变，可以通过此回调对容器布局、大小、方向等进行改变。语法： ```cpp void onRemoteRotation(int rotation) { (void)rotation; } ``` | **参数** | **描述** | | --- | --- | | rotation | - 0 或 180：竖屏 |\ || |\ || - 90 或 270：横屏 | ### onLocalScreenRotate 描述：本地容器旋转回调。调用 `rotateScreen(vecommon::RotateDegree degree)` 成功后会回调，此时拉流渲染方向已经改变，可以通过此回调对容器布局、大小、方向等进行改变。语法： ```cpp void onLocalScreenRotate(vecommon::RotateDegree degree) { (void)degree; } ``` | **参数** | **描述** | | --- | --- | | degree | 旋转角度 | ### onEditExchanged 描述：云机输入框发生变化时的回调。语法： ```cpp void onEditExchanged(bool show, const char* text, int start, int stop) { (void)show; (void)text; (void)start; (void)stop; } ``` | **参数** | **描述** | | --- | --- | | show | 输入框的显示状态：\ ||- true：显示输入框 |\ || |\ || - false：隐藏输入框 | | text | 当前输入框中的内容 | | start | 表示输入框内容变化的起始位置的索引。例如，如果在输入框的第一个位置插入文本，则 `start` 的值为 0；如果在第三个位置插入文本，则 `start` 的值为 2，当输入框中没有文本时，`start` 的取值为 0。 | | stop | 表示输入框内容变化的结束位置的索引。例如，如果在输入框的第一个位置插入文本，则 `stop` 的值为插入文本的长度；如果在第三个位置插入文本，则 `stop` 的值为插入文本的长度加上 2，输入框中没有文本时，`stop` 的取值为 0。 | ### onScreenShot 描述：云手机画面截图结果回调。语法： ```cpp void onScreenShot(int result, const char* savePath, const char* downloadUrl) { (void)result; (void)savePath; (void)downloadUrl; } ``` | **参数** | **描述** | | --- | --- | | result | 截图结果： |\ |||\ || - 0：截图成功 |\ || |\ || - \-1：存储空间不足，截图失败 |\ || |\ || - \-2：未知原因，截图失败 |\ || |\ || - \-3：截图失败，可能原因为当前页面受安全保护不允许截图，可修改 AOSP 的 `persist.sys.allow_capture_secure` 属性值为 `true` 后重试 | | savePath | 在云手机实例中保存截图文件的路径，例如：`/sdcard/Pictures/vephone_sdk_screenshot_[时间戳].jpg` | | downloadUrl | 截图成功时返回截图文件的下载链接，链接有效期 8 小时 | ### onShakeResponse 描述：“摇一摇”结果回调。语法： ```cpp void onShakeResponse(int result, const char* msg) { (void)result; (void)msg; } ``` | **参数** | **说明** | | --- | --- | | result | “摇一摇”结果。0：异常，请重试或联系技术支持；1：完成；2：进行中。 | | msg | “摇一摇”结果详细信息。 | ### onAudioInjectionResponse 描述：音频注入结果回调。语法： ```cpp void onAudioInjectionResponse(int result, const char* msg) { (void)result; (void)msg; } ``` | **参数** | **说明** | | --- | --- | | result | 音频注入结果。1：成功；<=0：失败。 | | msg | 音频注入结果的详细信息。 | ### onAudioInjectionStateChanged 描述：音频注入状态改变的回调。 | **参数** | **说明** | | --- | --- | | callUserId | 改变音频注入状态的用户ID | | state | 音频注入状态 true：开启 false：关闭 | | code | 错误码 0：成功 <0：失败 | | msg | 错误信息 | 语法： ```cpp void onAudioInjectionStateChanged(const char* callUserId, bool state, int code, const char* msg) { (void)callUserId; (void)state; (void)code; (void)msg; } ``` ### onGetAudioInjectionState 描述：查询音频注入状态的结果回调。 | **参数** | **说明** | | --- | --- | | state | 音频注入状态 true：开启 false：关闭 | | code | 错误码 0：成功 <0：失败 | | msg | 错误信息 | 语法： ```cpp void onGetAudioInjectionState(bool state, int code, const char* msg) { (void)state; (void)code; (void)msg; } ``` ### onVideoInjectionStateChanged 描述：视频注入状态改变的回调。 | **参数** | **说明** | | --- | --- | | callUserId | 改变视频注入状态的用户ID | | state | 视频注入状态 true：开启 false：关闭 | | code | 错误码 0：成功 <0：失败 | | msg | 错误信息 | 语法： ```cpp void onVideoInjectionStateChanged(const char* callUserId, bool state, int code, const char* msg) { (void)callUserId; (void)state; (void)code; (void)msg; } ``` ### onGetVideoInjectionState 描述：查询视频注入状态结果回调 | **参数** | **说明** | | --- | --- | | state | 视频注入状态 true：开启 false：关闭 | | code | 错误码 0：成功 <0：失败 | | msg | 错误信息 | 语法： ```cpp void onGetVideoInjectionState(bool state, int code, const char* msg) { (void)state; (void)code; (void)msg; } ``` ### onKeyboardTypeChanged 描述：键盘类型改变的回调，调用 [`setKeyboardType`](#setkeyboardtype) 接口切换键盘类型后返回。语法： ```cpp void onKeyboardTypeChanged(int code, vecommon::KeyboardType type) { (void)code; (void)type; } ``` | **参数** | **说明** | | --- | --- | | code | 错误码 0：成功 <0：失败 1000：不允许设置 | | type | 当前使用的键盘类型。参看 [KeyboardType](#keyboardtype) | ### onGetKeyboardTypeResult 描述：查询键盘类型的结果回调，通过 [`getKeyboardType`](#getkeyboardtype) 接口触发。语法： ```cpp void onGetKeyboardTypeResult(int code, vecommon::KeyboardType type) { (void)code; (void)type; } ``` | **参数** | **说明** | | --- | --- | | code | 错误码 0：成功 <0：失败 1000 | | type | 当前使用的键盘类型。参看 [KeyboardType](#keyboardtype) | ### onControlStateChanged 描述：设置操控权并且成功的结果回调。调用 [`enableControl`](#enablecontrol) 设置操控权成功后，房间内的所有用户都会收到本回调通知。语法： ```cpp void onControlStateChanged(const vecommon::ControlState& state) { (void)state; } ``` | **参数** | **说明** | | --- | --- | | state | 操控权状态相关信息，参看 [`ControlState`](#controlstate-structure) 结构体说明。| ### onEnableControlResult 描述：设置操控权的结果回调。调用 [`enableControl`](#enablecontrol) 设置操控权成功后，接口调用者会收到本回调通知。语法： ```cpp void onEnableControlResult(int code, const vecommon::ControlState& state, const std::string& msg) { (void)code; (void)state; (void)msg; } ``` | **参数** | **说明** | | --- | --- | | code | 错误码。

0：成功；

<0：失败。

| | state | 操控权状态。参看 [`ControlState`](#controlstate-structure) 结构体说明。| | msg | 错误信息。 | ### onHasControlResult 描述：查询某个用户操控权的结果回调。调用 [`hasControl`](#hascontrol) 成功后，查询结果将通过本回调返回。语法： ```cpp void onHasControlResult(int code, const vecommon::ControlState& state, const std::string& msg) { (void)code; (void)state; (void)msg; } ``` | **参数** | **说明** | | --- | --- | | code | 错误码。

0：成功；

<0：失败。

| | state | 操控权状态。参看 [`ControlState`](#controlstate-structure) 结构体说明。| | msg | 错误信息。 | ### onAllControlsResult 描述：查询所有用户操控权的结果回调。调用 [`getAllControls`](#getallcontrols) 成功后，查询结果将通过本回调返回。语法： ```cpp void onAllControlsResult(int code, const std::vector& states, const std::string& msg) { (void)code; (void)states; (void)msg; } ``` | **参数** | **说明** | | --- | --- | | code | 错误码。

0：成功；

<0：失败。

| | states | 操控权状态列表。参看 [`ControlState`](#controlstate-structure) 结构体说明。| | msg | 错误信息。 | ### onReceiveChannelMessage 描述：接收到通道消息的回调。语法： ```cpp virtual void onReceiveChannelMessage(const vecommon::ChannelMessage message) { (void)message; } ``` | **参数** | **说明** | | --- | --- | | message | 消息实体，参看 [`ChannelMessage`](#channelmessage-structure) 说明。 | ### onSendChannelMessageResult 描述：发送通道消息的结果回调。语法： ```cpp virtual void onSendChannelMessageResult(bool success, const std::string& msgId) { (void)success; (void)msgId; } ``` | **参数** | **说明** | | --- | --- | | success | 消息发送结果。

true：成功；

false：失败。

| | msgId | 消息 ID。 | ### onMessageChannelStateChanged 描述：消息通道状态改变时的回调。语法： ```cpp virtual void onMessageChannelStateChanged(const std::string& remoteUid, const vecommon::MessageChannelState state) { (void)remoteUid; (void)state; } ``` | **参数** | **说明** | | --- | --- | | remoteUid | 发生状态改变的通道 ID。 | | state | 通道状态，参看 [`MessageChannelState`](#messagechannelstate-enum) 说明。 | ### onMessageChannelError 描述：消息通道发生错误时的回调。语法： ```cpp virtual void onMessageChannelError(int code, const std::string& msg) { (void)code; (void)msg; } ``` | **参数** | **说明** | | --- | --- | | code | 错误码。 | | msg | 错误信息。 | ### onRecordingStatus 描述：屏幕录制结果回调。语法： ```cpp virtual void onRecordingStatus(int status, const std::string& savePath, const std::string& downloadUrl, const std::string& msg) { (void)status; (void)savePath; (void)downloadUrl; (void)msg; } ``` | **参数** | **说明** | | --- | --- | | status | 录屏任务状态，包含以下取值：

0：录制成功，正常结束，上传录屏文件到对象存储成功，返回录像文件保存路；

1：录制成功，正常结束，录屏文件成功保存至云手机本地；

2：开始录制成功；

3：开始录制失败，重复请求开始录制；

4：结束录制失败，没有正在录制中的任务；

5：录制失败，云手机存储空间不足，已占用存储空间总量的 80%；

6：录制结束，达到录制时限，返回录像文件保存路径；

7：开始录制失败，录制时长超过上限。

| | savePath | 录屏文件在云手机实例中的保存路径。调用 [`startRecording`](#startrecording) 设置 `saveOnPod` 为 `true`，且 `status` 为 0、1、2 时返回。默认保存路径为 /sdcard/Pictures/Recordings/recording_yymmdd_[秒级时间戳].mp4。 | | downloadUrl | 录屏文件的下载链接，`status` 为 0 时返回。 | | msg | 提示信息。 | ### onVideoStreamProfileIdChanged 描述：清晰度档位发生改变的回调。清晰度档位详情参看[云手机清晰度档位说明](https://www.volcengine.com/docs/6394/155915)。语法： ```cpp virtual void onVideoStreamProfileIdChanged(const std::string& callUserId, bool success, int from, int current) { (void)callUserId; (void)success; (void)from; (void)current; } ``` | **参数** | **说明** | | --- | --- | | callUserId | 设置视频流清晰度档位的用户 ID。 | | success | 设置结果。

true：成功；

false：失败。

| | from | 变化前的清晰度档位。 | | current | 变化后当前的清晰度档位。 | ### onGetVideoStreamProfileIdResult 描述：查询清晰度档位的结果回调。清晰度档位详情参看[云手机清晰度档位说明](https://www.volcengine.com/docs/6394/155915)。语法： ```cpp virtual void onGetVideoStreamProfileIdResult(bool success, int current) { (void)success; (void)current; } ``` | **参数** | **说明** | | --- | --- | | success | 查询结果。

true：成功；

false：失败。

| | current | 当前的清晰度档位。 | ### onIdleTimeChanged 描述：保活时长发生改变的回调。语法： ```cpp virtual void onIdleTimeChanged(const std::string& callUserId, int code, int time) { (void)callUserId; (void)code; (void)time; } ``` | **参数** | **说明** | | --- | --- | | callUserId | 改变保活时长的用户 ID。 | | code | 操作结果。

0：成功；

<0：失败。

| | time | 保活时长。 | ### onGetIdleTimeResult 描述：获取保活时长的结果回调。语法： ```cpp virtual void onGetIdleTimeResult(int code, int time) { (void)code; (void)time; } ``` | **参数** | **说明** | | --- | --- | | code | 查询结果。

0：成功；

<0：失败。

| | time | 保活时长。 | ### IExpireTimeListener 描述：更新拉流 token 过期时间的监听器。 ```cpp class vecommon::IExpireTimeListener ``` #### 成员函数 **onUpdateExpireTimeOneStepResult** 描述：更新拉流 Token 过期时间的结果回调。语法： ```cpp virtual void onUpdateExpireTimeOneStepResult(int result, std::vector& failureList) { (void)result; (void)failureList; } ``` | **参数** | **说明** | | --- | --- | | result | 结果。

0：成功；

<0：失败。

| | failureList | 更新失败的实例列表。参看 [ExpireTimeFailure](#expiretimefailure-structure) | ### onWarning 描述：SDK 内部产生警告信息回调。语法： ```cpp void onWarning(int code) { (void)code; } ``` | **参数** | **说明** | | --- | --- | | code | SDK 内部产生的警告信息，具体错误码，见 [警告码说明](../6394/1156707#警告码) | | msg | 返回 code 的对应描述信息 | ### onError 描述：SDK 内部产生错误信息回调，产生错误会调用 `stop()` 停止从云机拉流。语法： ```cpp void onError(int code, const std::string msg) { (void)code; (void)msg; } ``` | **参数** | **说明** | | --- | --- | | code | SDK 内部产生的错误码，具体错误码，见 [错误码说明](../6394/1156707#错误码) | | msg | 返回 code 的对应描述信息 | # 类型详情 ## 生命周期相关类型 ### SessionConfig structure 描述：启动云渲染会话时传入的配置参数结构。语法： ```cpp typedef struct _SessionConfig { const char * ak; const char * sk; const char * token; const char * userId; const char * accountId; const char * userTag; void * canvas; int32_t autoRecycleTime; int32_t videoStreamProfileId; const char * configurationCode; const char * dc; const char * debugConfig; const char * extra; bool externalRender{false}; FrameFormat externalRenderFormat; } SessionConfig; ``` |

参数

是否必填

说明

| | --- | --- | --- | | ak | 是 | 用于用户鉴权的临时 Access Key，通过调用服务端 STSToken 接口获取，参考 [STS Token](../6394/75752) 接口说明。 |\ ||| | sk | 是 | 用于用户鉴权的临时 Secret Key，通过调用服务端 STSToken 接口获取，参考 [STS Token](../6394/75752) 接口说明。 |\ ||| | token | 是 | 用于用户鉴权的临时 Token，通过调用服务端 STSToken 接口获取，参考 [STS Token](../6394/75752) 接口说明。 |\ || | userId | 是 | 自定义客户端用户 ID，命名规则如下： |\ ||||\ ||| - 最大长度为64位的非空字符串，支持的字符集范围为: |\ ||| |\ ||| - 大写字母 A ~ Z |\ ||| |\ ||| - 小写字母 a ~ z |\ ||| |\ ||| - 数字 0 ~ 9 |\ ||| |\ ||| - 下划线 "\_", 减号 "-" | | accountId | 是 | 注册的火山引擎用户账号，可通过火山引擎官网页面右上角 **用户 > 账号管理 > 主账号信息** 获取 | | canvas | 是 | 拉流后显示画面的画布（Windows 平台下传窗口句柄） | | userTag | 否 | 用户标签，由业务方指定 | | autoRecycleTime | 否 | 设置用户无操作自动回收时长 | | videoStreamProfileId | 否 | 清晰度档位 ID，可选枚举值和对应的清晰度配置，参考 [云手机清晰度档位说明](../6394/155915) | | configurationCode | 否 | 实例资源套餐 ID | | dc | 否 | 机房 ID | | debugConfig | 否 | debug 配置 | | extra | 否 | 根据业务需要，自定义的扩展参数 | | externalRender | 否 | 是否需要外部渲染： |\ |||- true：需要外部渲染\ |||- false：不需要外部渲染 | externalRenderFormat | 否 | 外部渲染视频帧格式，具体枚举值请参考 [FrameFormat](../6394/1156707#frameformat-enum)。 | ### PhoneSessionConfig structure 描述：启动云手机场景会话时传入的配置参数结构。语法： ```cpp typedef struct _PhoneSessionConfig { SessionConfig basicConfig = {0}; const char * productId; const char * podId; const char * appId; const char * planId; bool enableScreenLock; bool enableLocalKeyboard; bool reset; float latitude; float longitude; int waitTime; VideoRenderMode renderMode; } PhoneSessionConfig; ``` |

参数

是否必填

说明

| | --- | --- | --- | | productId | 是 | 云手机业务 ID，可通过火山引擎云手机控制台『业务管理』页面获取 |\ || | podId | 是 | 实例 ID，可通过火山引擎云手机控制台『实例管理』页面获取 | | appId | 否 | 需要启动的应用 ID（**推流时直接打开应用**），可通过火山引擎云手机控制台『应用管理』页面获取 |\ || | plan\_id | 否 | 火山侧套餐 ID | | enableScreenLock | 否 | 是否锁定屏幕横竖屏显示: |\ ||||\ ||| - true：锁定屏幕开启 |\ ||| |\ ||| - false：锁定屏幕关闭 | | enableLocalKeyboard | 否 | 是否开启本地键盘输入： |\ ||||\ ||| - true：仅开启本地键盘 |\ ||| |\ ||| - false：开启云机键盘 | | reset | 否 | 退出后，是否重置设备环境： |\ ||||\ ||| - true: 重置 |\ ||| |\ ||| - false: 不重置（默认） | | latitude | 否 | 模拟定位纬度 | | logitude | 否 | 模拟定位经度 | | waitTime | 否 | 云手机实例进房后，等待客户端加入房间的最大允许时长。当云手机处于房间中而没有客户端加入，或者所有客户端都已离开房间后，云手机将在到达此参数设置的时长后自动退出房间。
单位为 s，默认值为 10，取值范围为 [10, 259200]，传入非法参数时自动调整为默认值即 10s。
请根据实际需求合理设置此参数，以确保云手机在没有客户端活动时能够及时释放资源 | | renderMode | 否 | 视频的渲染模式，参看 [VideoRenderMode](#videorendermode) 数据结构 | | expireTime | 否 | 拉流 Token 有效期，单位为秒，取值范围 [0,172800]，即 2 天。若不设置本参数，Token 有效期会始终在后台自动更新；若设置本参数，Token 有效期则本参数中的设置为准。 | ## 回调使用相关类型 ### AudioStats structure 描述：音频流统计信息结构。语法： ```cpp typedef struct tagAudioStats { float audio_loss_rate; int received_kbitrate; int stall_count; int stall_duration; long e2e_delay; int playout_sample_rate; int stats_interval; int rtt; int total_rtt; int quality; int jitter_buffer_delay; int num_channels; int received_sample_rate; int frozen_rate; int concealed_samples; int concealment_event; int dec_sample_rate; int dec_duration; int jitter; } AudioStats; ``` | **参数** | **描述** | | --- | --- | | audio\_loss\_rate | 音频丢包率；统计周期内的音频下行丢包率，取值范围为 \[0, 1\] | | received\_kbitrate | 接收码率；统计周期内的音频接收码率，单位为 kbps | | stall\_count | 音频卡顿次数；统计周期内的卡顿次数 | | stall\_duration | 音频卡顿时长；统计周期内的卡顿时长，单位为 ms | | e2e\_delay | 用户体验级别的端到端延时；从发送端采集完成编码开始到接收端解码完成渲染开始的延时，单位为 ms | | playout\_sample\_rate | 播放采样率；统计周期内的音频播放采样率信息，单位为 Hz | | stats\_interval | 统计间隔；此次统计周期的间隔，单位为 ms | | rtt | 客户端到服务端数据传输的往返时延，单位为 ms | | total\_rtt | 发送端 --> 服务端 --> 接收端全链路数据传输往返时延，单位为 ms | | quality | 云机用户发送的音频流质量 | | jitter\_buffer\_delay | 因引入 jitter buffer 机制导致的延时 | | num\_channels | 音频声道数 | | received\_sample\_rate | 音频接收采样率；统计周期内接收到的云机音频采样率信息，单位为 Hz | | frozen\_rate | 云机用户在加入房间后发生音频卡顿的累计时长占音频总有效时长的百分比；音频有效时长是指云机用户进房发布音频流后，除停止发送音频流和禁用音频模块之外的音频时长 | | concealed\_samples | 音频丢包补偿（PLC）样点总个数 | | concealment\_event | 音频丢包补偿（PLC）累计次数 | | dec\_sample\_rate | 音频解码采样率；统计周期内的音频解码采样率信息，单位为 Hz | | dec\_duration | 解码时长；对此次统计周期内接收的云机音频流进行解码的总耗时，单位为 s | | jitter | 音频下行网络抖动，单位为 ms | ### VideoStats structure 描述：视频流统计信息结构。语法： ```cpp typedef struct tagVideoStats { uint8_t clarity; int32_t width; int32_t height; float video_loss_rate; int32_t received_kbitrate; int32_t decoder_output_frame_rate; int32_t renderer_output_frame_rate; int32_t stall_count; int32_t stall_duration; int64_t e2e_delay; bool is_screen; int32_t stats_interval; int32_t rtt; int32_t frozen_rate; int32_t video_index; int32_t jitter; } VideoStats; ``` | **参数** | **描述** | | --- | --- | | clarity | 视频流清晰度 ID | | width | 视频宽度 | | height | 视频高度 | | video\_loss\_rate | 视频丢包率；统计周期内的视频下行丢包率，单位为 % ，取值范围：\[0，1\] | | received\_kbitrate | 接收码率；统计周期内的视频接收码率，单位为 kbps | | decoder\_output\_frame\_rate | 解码器输出帧率；统计周期内的视频解码器输出帧率，单位 fps | | renderer\_output\_frame\_rate | 渲染帧率；统计周期内的视频渲染帧率，单位 fps | | stall\_count | 卡顿次数；统计周期内的卡顿次数 | | stall\_duration | 卡顿时长；统计周期内的视频卡顿总时长。单位 ms | | e2e\_delay | 用户体验级别的端到端延时；从发送端采集完成编码开始到接收端解码完成渲染开始的延时，单位为 ms | | is\_screen | 所属用户的媒体流是否为屏幕流；你可以知道当前数据来自主流还是屏幕流 | | stats\_interval | 统计间隔，此次统计周期的间隔，单位为 ms，此字段用于设置回调的统计周期，目前设置为 2s | | rtt | 往返时延，单位为 ms | | frozen\_rate | 云机用户在进房后发生视频卡顿的累计时长占视频总有效时长的百分比（%）；视频有效时长是指云机用户进房发布视频流后，除停止发送视频流和禁用视频模块之外的视频时长 | | video\_index | 对应多种分辨率的流的下标 | | jitter | 视频下行网络抖动，单位为 ms | ### VideoFrameInfo structure 描述：视频帧信息结构。语法： ```cpp typedef struct VideoFrameInfo { int32_t width; int32_t height; int32_t rotation; } VideoFrameInfo; ``` | **参数** | **描述** | | --- | --- | | width | 视频帧宽（像素） | | height | 视频帧高（像素） | | rotation | 视频帧顺时针旋转角度： |\ |||\ || - 0（顺时针旋转 0 度） |\ || |\ || - 90（顺时针旋转 90 度） |\ || |\ || - 180（顺时针旋转 180 度） |\ || |\ || - 270（顺时针旋转 270 度） | ### ControlState structure 描述：操控权状态。语法： ```cpp typedef struct tagControlState { std::string userId; bool enable; } ControlState; ``` | **参数** | **描述** | | --- | --- | | userId | 目标用户 ID。 | | enable | 目标用户当前是否具有云手机操控权。

true：持有操控权；

false：无操控权。

| ### ExpireTimeConfig structure 描述：更新拉流 Token 有效期配置。语法： ```cpp struct ExpireTimeConfig { std::string ak; std::string sk; std::string token; std::string accountId; std::string productId; std::string sessionUserId; std::vector podConfigList; std::string debugConfig; }; ``` | **参数** | **描述** | | --- | --- | | ak | 用户鉴权临时 access key | | sk | 用户鉴权临时 secret key | | token | 用户鉴权临时 token | | accountId | 火山引擎账号 ID | | productId | 云手机业务 ID | | sessionUserId | 会话 session 用户 ID | | podConfigList | 过期时长配置列表，参看 [ExpireTimeItem](#expiretimeitem-structure)| | debugConfig | debug 配置 | ### ExpireTimeItem structure 描述：更新拉流 Token 有效期详细配置语法： ```cpp struct ExpireTimeItem { std::string podId; int64_t expireTime { 0 }; }; ``` | **参数** | **描述** | | --- | --- | | podId | 实例 ID | | expireTime | Token 过期时间，单位为秒，取值范围 [0,172800]，即 2 天。 | ### ExpireTimeFailure structure 描述：更新拉流 Token 有效期失败时的详细信息语法： ```cpp struct ExpireTimeFailure { std::string podId; bool session{ true }; }; ``` | **参数** | **描述** | | --- | --- | | podId | Token 过期时间更新失败的实例 ID | | session | Token 过期时间是否更新成功 | ## 云手机操作相关类型 ### MouseKeyData structure 描述：鼠标按键信息结构。语法： ```cpp typedef struct tagMouseKeyData { uint8_t key; uint8_t down; int32_t abs_x; int32_t abs_y; } MouseKeyData; ``` | **参数** | **描述** | | --- | --- | | key | 鼠标按键值，参考 [https://docs.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes](https://docs.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes) | | down | 按键状态，0为up，1为down | | abs\_x | 鼠标在画面的 x 轴坐标，左->右映射到 \[0,65535\] | | abs\_y | 鼠标在画面的 y 轴坐标，上->下映射到 \[0,65535\] | ### MouseMoveData structure 描述：鼠标光标移动信息结构。语法： ```cpp typedef struct tagMouseMoveData { int32_t abs_x; int32_t abs_y; int32_t delta_x; int32_t delta_y; } MouseMoveData; ``` | **参数** | **描述** | | --- | --- | | abs\_x | 鼠标在画面的 x 轴坐标，左->右映射到 \[0,65535\] | | abs\_y | 鼠标在画面的 y 轴坐标，上->下映射到 \[0,65535\] | | delta\_x | 相对上次鼠标位置 x 方向移动值，左负，右正 | | delta\_y | 相对上次鼠标位置 y 方向移动值，上负，下正 | ### MouseWheelDataArm structure 描述：鼠标滚轮（ARM）滚动信息结构。语法： ```cpp typedef struct tagMouseWheelDataArm { double x; double y; double axis_v; double axis_h; int16_t action： int16_t button; } MouseWheelDataArm; ``` | **参数** | **描述** | | --- | --- | | x | 鼠标滚轮竖向滚动值，映射到 \[0,65535\] | | y | 鼠标滚轮横向滚动值，映射到 \[0,65535\] | | axis\_v | 表示上下方向，-1.0：下，1.0：上 | | axis\_h | 表示左右方向，-1.0：右，1.0：左 | | action | 动作类型，0：ACTION\_DOWN，1：ACTION\_UP，2：ACTION\_MOVE，8：ACTION\_SCROLL | | button | 0：左键，1：右键，2：中键 | ### ImeCompositionData structure 描述：输入状态及输入字符串。语法： ```cpp typedef struct tagImeCompositionData { ImeCompositionType type; const char* str; int32_t len; int32_t start; int32_t end; } ImeCompositionData; ``` | **参数** | **描述** | | --- | --- | | type | 输入类型： |\ || 0：输入开始 |\ || 1：输入结束 |\ || 2：输入中 | | str | 输入字符串，必须为 UTF-8 编码格式 | | len | 输入长度 | | start | 输入起点 | | end | 输入结束点 | ### MulitTouchData structure 描述：多指触控数据结构体。语法： ```cpp typedef struct _MulitTouchData { int32_t x{ 0 }; // 事件 X 坐标位置左-->右映射到 [0,65535] int32_t y{ 0 }; // 事件 Y 坐标位置上-->下映射到 [0,65535] int32_t point_id{ -1 }; // 触摸点 ID int32_t touch_action{ -1 }; // 参考具体枚举值定义 } MulitTouchData;y ``` | **参数** | **描述** | | --- | --- | | x | 事件 X 坐标位置左-->右映射到 \[0,65535\] | | y | 事件 Y 坐标位置上-->下映射到 \[0,65535\] | | point\_id | 触摸点 ID | | touch\_action | 触摸事件动作。具体枚举止请参考 [TouchType](#touchtype-enum)定义。 | ### FrameFormat enum 描述：外部渲染视频帧编码格式。语法： ```cpp enum FrameFormat { /** * @brief YUV I420 格式 */ YUVI420, /** * @brief ARGB 格式, 字节序为 A8 R8 G8 B8 */ ARGB, /** * @brief RGBA 格式, 字节序为 R8 G8 B8 A8 */ RGBA, /** * @brief BGRA 格式, 字节序为 B8 G8 R8 A8 */ BGRA }; ``` ### SessionStatus enum 描述：Session 状态码定义。语法： ```cpp enum class SessionStatus { /** * @brief 默认状态 */ Idle = 0x0000, /** * @brief 启动中 */ Starting = 0x0001, /** * @brief 启动完成 */ Started = 0x0002, /** * @brief 加房成功，拉流中 */ Streaming = 0x0003, /** * @brief 发生错误 */ Error = 0x0004, /** * @brief 结束状态 */ Stop = 0x005 }; ``` ### TouchType enum 描述：Touch 事件类型定义。语法： ```cpp enum class TouchType { /** * 默认值 */ None = -1, /** * 手指按下 */ Down = 0, /** * 手指抬起 */ Up = 1, /** * 手指移动 */ Move = 2, /** * 事件关闭 */ Cancel = 3, /** * @hide */ Outside = 4, /** * @hide */ PointerDown = 5, /** * @hide */ PointerUp = 6 }; ``` ### VeExternalSink | **接口** | **描述** | | --- | --- | | onFrame | 视频帧回调，详细的回调参数请参考 [VeExtVideoFrame](#veextvideoframe)。 | | release | 通知开发者渲染器即将被废弃。如果您收到该返回通知后即可释放资源。 | ```cpp void onFrame(VeExtVideoFrame* videoFrame) { (void)videoFrame; }; ``` ```cpp void release(); ``` ### VeExtVideoFrame | **接口** | **描述** | | --- | --- | | timestampUs | 获取视频帧时间戳，单位：微秒 | | width | 获取视频帧宽度，单位：px | | height | 获取视频帧高度，单位：px | | numberOfPlanes | 视频帧颜色 plane 数量，根据 [FrameFormat](../6394/1156707#frameformat-enum) 不同视频帧编码格式，获取相关平面数量不同，区别如下： |\ |||\ || - `RGBA` / `ARGB`/ `BGRA` 格式下，返回 1 |\ || |\ || - YUV 数据存储格式分为打包（packed）存储格式和平面（planar）存储格式；|\ || - planar 格式中 Y、U、V 分平面存储 |\ || |\ || - packed 格式中 Y、U、V 交叉存储 | | getPlaneData | 通过 plane 数据索引，获取 plane 数据指针。根据 [FrameFormat](../6394/1156707#frameformat-enum)不同视频帧编码格式，获取 plane 数据指针不同，区别如下：|\ |||\ || - 获取 `ARGB`/`RGBA`/`BGRA` 格式数据，getPlaneData(0)； |\ || |\ || - 获取 `YUVI420` 格式数据： |\ || - Y：getPlaneData(0) |\ || |\ || - U：getPlaneData(1) |\ || |\ || - V：getPlaneData(2) |\ || |\ |||\ ||| | getPlaneStride | 通过 plane 数据索引，获取 plane 中数据行的长度(步幅) 。根据 [FrameFormat](../6394/1156707#frameformat-enum) 不同视频帧编码格式，获取 plane 中数据行的长度(步幅) 不同，区别如下：|\ |||\ || - 获取 `ARGB`/`RGBA`/`BGRA` 格式数据，getPlaneStride(0) ； |\ || |\ || - 获取 `YUVI420` 格式数据 Stride |\ || - Y：getPlaneStride(0) |\ || |\ || - U：getPlaneStride(1) |\ || |\ || - V：getPlaneStride(2) | ```cpp int64_t timestampUs() const = 0; int width() const = 0; int height() const = 0; int numberOfPlanes() const = 0; uint8_t* getPlaneData(int planeIndex) = 0; int getPlaneStride(int planeIndex) = 0; ``` ### KeyboardType 描述：键盘类型语法： ```cpp enum class KeyboardType { /** * @brief 使用云机键盘。 */ POD = 0, /** * @brief 使用本地键盘。 */ LOCAL = 1 }; ``` ### VideoRenderMode 描述：视频的渲染模式。语法： ```cpp enum class VideoRenderMode { COVER = 1, FIT = 2, FILL = 3, }; ``` |

类型

值

说明

| | --- | --- | --- | | COVER | 1 | 覆盖模式。

适用于希望**全屏**观看视频内容，且**不介意视频内容完整性**的场景。

该模式优先考虑将视频填满整个屏幕，视频内容会等比例缩放直至屏幕边缘，确保没有黑边。这可能导致视频的某些部分被裁剪，以适应屏幕尺寸。

| | FIT | 2 | 适应模式，默认。

适用于需要**完整**观看视频内容，且**不介意黑边存在**的场景。

该模式确保视频内容完整显示在屏幕上，通过等比例缩放视频以适应屏幕大小，保持视频的原始宽高比。如果视频尺寸与屏幕尺寸不匹配，未填满的屏幕区域将用黑色填充，形成黑边。

| | FILL | 3 | 填充模式。

适用于需要**全屏且完整**观看视频内容，且**不介意画面轻微变形**的场景。

该模式旨在让视频内容完全覆盖屏幕，视频可能会进行非等比例缩放以填满整个屏幕，这意味着视频的宽高比可能会改变，导致画面变形。

| ### ChannelMessage structure 描述：消息实体。语法： ```cpp struct ChannelMessage { int type; std::string msgId; std::string ackId; std::string sourceUid; std::string destUid; std::string payload; int64_t timestamp; }; ``` | **参数** | **描述** | | --- | --- | | type | 消息类型。 | | msgId | 消息 ID。 | | ackId | ACK ID。 | | sourceUid | 消息发送端用户 ID。 | | destUid | 消息接收端用户 ID。 | | payload | 消息内容。 | | timestamp | 消息生成的时间戳。 | ### MessageChannelState enum 描述：消息通道状态。语法： ```cpp enum class MessageChannelState { Unknown = 0, Connected = 1, Disconnected = 2, }; ``` |

类型

值

说明

| | --- | --- | --- | | Unknown | 0 | 未知状态。 | | Connected | 1 | 消息通道已建联。 | | Disconnected | 2 | 消息通道已断联。 | # 警告码描述：`IEngineEventHandler::onWarning` 接口返回警告码及说明。详细的警告码及说明如下： |

Code

Message

说明

| | --- | --- | --- | | 21034001 | WARNING_TOKEN_WILL_EXPIRE | 拉流 token 即将过期，如果想继续维持拉流状态，请调用 [updateExpireTimeOneStep](#updateexpiretimeonestep) 接口以延长拉流有效期。 | | 30023002 | WARNING\_LOCAL\_ALREADY\_SET\_BACKGROUND | 本地客户端应用已切换到后台，请勿重复调用切换后台接口。 |\ ||| | 30023003 | WARNING\_LOCAL\_ALREADY\_SET\_FOREGROUND | 本地客户端应用已切换到前台，请勿重复调用切换前台接口。 |\ ||| | 30009002 | WARNING\_REMOTE\_\_ALREADY\_FOREGROUND | 云机应用戏切换前台失败。原因：云机应用已处于前台。 | | 30009101 | WARNING\_REMOTE\_\_FOREGROUND\_FAILURE\_NO\_SUCH\_PACKAGE\_NAME | 云机应用戏切换前台失败。原因：应用包名不存在。建议：请检查指定的应用包名是否正确。 | | 30009102 | WARNING\_REMOTE\_\_FOREGROUND\_FAILURE\_NO\_SUCH\_PACKAGE\_NAME | 云机应用切换前台失败。原因：应用包名不存在。建议：请检查指定的应用包名是否正确。 |\ |||| | 30009103 | WARNING\_REMOTE\_\_FOREGROUND\_FAILURE\_NO\_PACKAGE\_NAME\_BACKGROUND | 云机应用切换前台失败。原因：指定的应用不在后台或已被关闭。 |\ |||| | 51010010 | WARNING\_START\_NO\_STOP\_BEFORE | 启动云手机失败。原因：反复初始化流媒体 Engine。同一个客户端连续调用了两次 `start()` 接口启动云手机之前，未调用 `stop()` 接口停止云手机。建议：请调用服务端 [PodStop](../6394/658692) 接口后，再调用 `start()` 接口启动云手机。 |\ ||| | 51010019 | WARNING\_START\_INVALID\_AUTO\_RECYCLE\_TIME | 设置无操作回收服务时长出错。建议：请参考 `auto_recycle_time` 参数描述进行设置。 |\ ||| # 错误码描述：`IEngineEventHandler::onError` 接口返回错误码及说明。详细的错误码及说明如下： |

Code

Message

说明

| | --- | --- | --- | | 11000001 | ERROR\_REQUEST\_PARAMETER\_BINDING\_ERROR | 参数绑定错误。建议：检查传入的参数格式是否正确。 | | 11000007 | ERROR\_INVALID\_REQUEST\_PARAMETER | 请求参数错误。建议：检查传入的参数名称是否正确。 | | 11000008 | ERROR\_DOWN\_STREAM\_UNKNOWN\_ERROR | 服务端下游错误。建议：请联系火山引擎云手机技术支持。 |\ ||| | 12000000 | ERROR\_BUSINESS\_ID\_ERROR | 业务 ID 错误。建议：请检查业务是否存在，可通过火山引擎云手机控制台『业务详情』页面获取。 |\ ||| | 12000001 | ERROR\_START\_PRODUCT\_NOT\_EXIST | 启动云手机失败。原因：指定的云手机业务 ID 不存在。建议：检查您的业务 ID 是否正确。可通过火山引擎云手机控制台『业务管理』页面获取。 | | 13000001 | ERROR\_START\_APPLICATION\_NOT\_EXIST | 启动云手机失败。原因：指定的应用不存在。建议：检查指定的 `app_id` 是否正确。 | | 16000000 | ERROR\_START\_CONFIGURATION\_CODE\_NOT\_EXIST | 启动云手机失败。原因：实例资源套餐不存在。建议：检查指定的 `configuration_code` 是否正确。 |\ ||| | 17000000 | ERROR\_ACCOUNT\_ID\_INIT\_ERROR | 火山引擎账号 ID 错误。建议：请检查使用的账号和签名，可通过火山引擎官网页面右上角 **用户 > 账号管理 > 主账号信息** 获取正确的账号。 |\ ||| | 17000001 | ERROR\_ACCOUNT\_ID\_NOT\_FOUND | 火山引擎账号 ID 不合法。建议：通过火山引擎官网页面右上角 **用户 > 账号管理 > 主账号信息** 获取正确的账号。 |\ ||| | 17000003 | ERROR\_ACCOUNTID\_MISMATCH | 指定的火山引擎账号校验失败。建议：通过火山引擎官网页面右上角 **用户 > 账号管理 > 主账号信息** 获取正确的账号。 |\ ||| | 17100000 | ERROR\_USER\_IS\_INVALID | 子账号不合法。建议：请检查子账号是否有业务和实例相关操作权限。可参考 [创建和管理子账号权限](../6394/154568)。 |\ ||| | 18100000 | ERROR\_GENERIC\_INSTANCE\_ERROR | 套餐、实例不存在。建议：请检查实例状态、订购的资源是否过期。 | | 18100001 | ERROR\_START\_POD\_NOT\_EXIST | 启动云手机失败。原因：实例不存在。建议：检查指定的 `pod_id` 是否正确。 | | 18100002 | ERROR\_INSTANCE\_OFFLINE | 实例离线。建议：请检查实例状态。 | | 18100003 | ERROR\_POD\_NOT\_READY | 云机实例未就绪。建议：请检查指定的实例已开机运行。 |\ ||| | 18500000 | ERROR\_UNIVERSAL\_STARTUP\_FAILED | 启动云手机失败。 | | 18500001 | ERROR\_INTERNAL\_POD\_START\_FAILED | 启动云手机失败。建议：请检查实例状态或联系火山引擎云手机技术支持。 |\ ||| | 18500002 | ERROR\_INTERNAL\_POD\_MUTE\_FAILED | 启动云手机失败。建议：请检查实例状态或联系火山引擎云手机技术支持。 |\ ||| | 18500003 | ERROR\_INTERNAL\_CONFIG\_FAILED | 启动云手机失败。建议：请检查实例状态或联系火山引擎云手机技术支持。 | | 21001004 | ERROR\_GAME\_STOPPED\_DUPLICATE\_START | 游戏停止。原因：某个 `start()` 请求使用了与当前游戏相同的 `userId` 和 `gameId`，导致当前游戏停止。建议：请检查调用 `start()` 接口的参数是否重复。如果需要重新启动被停止的游戏，请再次使用相同的 `userId` 和 `gameId` 调用 `start()` 接口。 |\ ||| | 21001011 | ERROR\_START\_CONNECTION\_ENDED | 启动云手机失败。原因：在调用 `start()` 接口启动云手机成功回调触发之前，云手机被停止（可能原因包括：服务端应用崩溃导致启动失败）。 |\ ||| | 21040055 | ERROR_REMOTE_STOPPED_TOKEN_EXPIRED | 应用停止。原因：拉流 token 已过期，请再次调用 start 接口重新启动拉流。 |\ ||| | 30008000 | ERROR\_POD\_EXIT\_CRASH | 云手机停止。原因：服务端应用崩溃。建议：请尝试复现应用在本地设备是否运行异常，如本地未复现，可以联系火山引擎云手机服务技术支持。 |\ ||| | 30008003 | ERROR\_GAME\_STOPPED\_IDLE | 云手机停止。原因：用户长时间未操作，服务端自动断开连接。建议：客户端需要提示用户长时间无操作被踢下线。 |\ ||| | 30008005 | ERROR\_GAME\_STOPPED\_API | 云手机停止。原因：服务端主动停止。 | | 30008006 | ERROR\_POD\_STOPPED\_BACKGROUND\_TIMEOUT | 云手机停止。原因：客户端切换后台，超过指定的保活时长未切换前台，服务端自动断开了连接。建议：客户端需要提示用户因为应用切后台超过保活时长，连接断开。 |\ ||| | 51010000 | ERROR\_START\_GENERAL | 启动云手机失败。原因：通用错误。建议：请检查开始 `start()` 接口参数。 |\ ||| | 52030000 | ERROR\_SDK\_GENERAL | 客户端 SDK 通用错误。 | | 52030001 | ERROR\_SDK\_INIT\_FAILED | 客户端 SDK 初始化失败。 | | 52030002 | ERROR\_SDK\_\_PARAMETER\_EMPTY | 客户端调用 SDK 接口错误。原因：接口参数为空。建议：请参考接口说明文档，检查接口参数。 |\ ||| | 53071001 | ERROR\_FILE\_CHANNEL\_FILE\_NOT\_FOUND | 文件传输失败。原因：上传或下载的文件不存在。建议：请检查文件名是否正确且确保文件存在后重试。 |\ || | 53071002 | ERROR\_FILE\_CHANNEL\_FILE\_NO\_ACCESS | 文件传输失败。原因：上传或下载的文件无权限访问。建议：请检查文件的访问权限。 | | 53071003 | ERROR\_FILE\_CHANNEL\_NETWORK\_ABORT | 文件传输失败。原因：上传或下载文件过程中网络异常中断。建议：请检查网络连接后重试。 | | 53071004 | ERROR\_FILE\_CHANNEL\_TIMEOUT | 文件传输失败。原因：上传或下载文件过程中超时。建议：请检查网络连接后重试。 |\ ||| | 53071005 | ERROR\_FILE\_CHANNEL\_STORAGE\_NOT\_ENOUGH | 文件传输失败。原因：上传或下载文件磁盘空间不足。建议：请确保有足够的存储空间保存文件。 | | 53071006 | ERROR\_FILE\_CHANNEL\_INTERNAL\_ERROR | 文件传输失败。原因：上传或下载文件发生内部错误 | | 54050000 | ERROR\_MESSAGE\_GENERAL | 未知错误 | | 54050001 | ERROR\_MESSAGE\_NOT\_CONNECTED | 发送消息错误。原因：客户端 SDK 与火山引擎云游戏 PaaS 服务未连接。建议：请检查网络后，重新调用发送消息接口，进行消息发送。 |\ ||| | 54050002 | ERROR\_MESSAGE\_FAILED\_TO\_PARSE\_MSG | 消息通道数据解析失败。原因：无法解析接收到的消息。 |\ || | 54050003 | ERROR\_MESSAGE\_CHANNEL\_UID\_ILLEGAL | 指定的消息通道 ID 无效。原因：指定的消息通道 ID 与云机初始化 veMessageChannelClient 时填入的用户 ID 不符。 |\ || | 54050007 | ERROR\_MESSAGE\_OVER\_SIZED | 通过客户端 SDK 发送的消息错误。原因：消息包体过大（不应超过60kb）。建议：减小发送包体大小，重新发送。 |\ ||| | 54050009 | ERROR\_MESSAGE\_TIMEOUT\_ILLEGAL | 发送消息错误。原因：指定的消息发送超时时长不符合要求，必须为大于0的值。 |\ || | 6100000x | ERROR\_NET\_REQUEST\_ERROR | 网络请求失败 | | 62000xxx | ERROR\_HTTP\_REQUEST\_ERROR | 网络请求失败 |