接口说明

最近更新时间:2025-09-04 15:11:42

我的收藏

接口概览

生命周期接口

函数名
说明
获取 TcrClientHandle 实例。
初始化 TcrClientHandle。
创建会话对象。
初始化会话。
启动会话。
开始会话。
销毁会话对象。
设置会话事件观察者。
设置日志回调函数。
设置日志输出级别。
获取当前日志输出级别。
创建自定义数据通道。
通过自定义数据通道发送数据。
关闭自定义数据通道。

安卓实例操作接口

函数名
说明
获取 TcrAndroidInstance 操作对象。
加入分组
控制实例视频流开关及质量。
设置/取消主控实例。
设置同步列表。
获取实例截图图片 URL。
获取文件下载 URL。
获取 logcat 日志下载地址。
上传文件到云实例相册。
上传本地文件到云手机。
批量请求云端任务。
释放结果内存。

音视频控制接口

函数名
说明
设置视频帧回调。
转换视频帧到 I420 格式。
检查是否为 D3D11 格式。
获取 D3D11 纹理指针。
暂停媒体流。
恢复媒体流。
设置远端视频流参数。
发送透传消息。
粘贴文本到输入框。
直接输入文本。
切换输入法。
启用本地摄像头。
禁用本地摄像头。
启用本地摄像头(带视频配置参数)。
检查本地摄像头是否已启用。
配置本地摄像头参数。
获取可用摄像头设备数量。
获取摄像头设备信息。
启用本地麦克风。
禁用本地麦克风。
检查本地麦克风是否已启用。

外设控制接口

函数名
说明
开关摄像头。
开关麦克风。
发送云端键盘事件。
发送触摸事件。

详细说明

获取 TcrClientHandle 实例

获取 TcrClientHandle 实例,用于后续所有客户端相关操作。
TcrClientHandle tcr_client_get_instance();

初始化 TcrClientHandle

初始化 TcrClientHandle。
TcrErrorCode tcr_client_init(TcrClientHandle client, const TcrConfig* config);
参数
类型
说明
client
TcrClientHandle
客户端句柄。
config
const TcrConfig*
配置信息指针。

创建会话对象

创建会话对象,用于串流和控制云手机实例。
TcrSessionHandle tcr_client_create_session(TcrClientHandle client);
参数
类型
说明
client
TcrClientHandle
客户端句柄。

初始化会话

初始化会话,初始化成功后会通过回调发送 TCR_SESSION_EVENT_STATE_INITED 事件通知。
TCRSDK_API void tcr_session_init(TcrSessionHandle session);
参数
类型
说明
session
TcrSessionHandle
会话句柄。

启动会话并连接云手机

启动会话并连接云手机。
void tcr_session_access(TcrSessionHandle session, const char** instanceIds, int32_t length);
参数
类型
说明
session
TcrSessionHandle
会话句柄。
instanceIds
const char**
云端实例 ID 数组。
length
int32_t
实例 ID 数组长度。

开始会话

启动会话。注意,每个会话只能调用一次此函数。
TCRSDK_API void tcr_session_start(TcrSessionHandle session, const char* serverSession);
参数
类型
说明
session
TcrSessionHandle
会话句柄。
serverSession
const char*
服务端会话标识。

销毁会话对象

销毁会话对象,释放相关资源。
void tcr_client_destroy_session(TcrClientHandle client, TcrSessionHandle session);
参数
类型
说明
client
TcrClientHandle
客户端句柄。
session
TcrSessionHandle
会话句柄。

设置会话事件观察者

设置会话事件观察者,用于接收会话生命周期及业务事件。
void tcr_session_set_observer(TcrSessionHandle session, const TcrSessionObserver* observer);
参数
类型
说明
session
TcrSessionHandle
会话句柄。
observer
const TcrSessionObserver*
观察者结构体指针。

设置日志回调函数

设置日志回调函数,用于接收 SDK 日志。
void tcr_set_log_callback(const TcrLogCallback* callback);
参数
类型
说明
callback
const TcrLogCallback*
日志回调结构体指针。

设置日志输出级别

void tcr_set_log_level(TcrLogLevel level);
参数
类型
说明
level
TcrLogLevel
日志级别。

获取当前日志输出级别

TcrLogLevel tcr_get_log_level();

创建自定义数据通道

创建并返回一个自定义数据通道句柄,用于数据传输。
TCRSDK_API TcrDataChannelHandle tcr_session_create_data_channel(
TcrSessionHandle session,
int32_t port,
const TcrDataChannelObserver* observer
);
参数
类型
说明
session
TcrSessionHandle
会话句柄。
port
int32_t
云端唯一标识数据通道的端口号。
observer
const TcrDataChannelObserver*
观察者结构体指针,回调时会传入 user_data。生命周期需调用方保证有效。
返回值
TcrDataChannelHandle
数据通道句柄,失败返回 NULL。

发送数据

通过已创建的数据通道句柄向云端发送自定义数据。
TCRSDK_API TcrErrorCode tcr_data_channel_send(
TcrDataChannelHandle channel,
const uint8_t* data,
size_t size
);
参数
类型
说明
channel
TcrDataChannelHandle
数据通道句柄。
data
const uint8_t*
数据指针。
size
size_t
数据长度。
返回值
TcrErrorCode
错误码,TCR_SUCCESS 表示成功。

关闭数据通道

关闭指定的数据通道。
TCRSDK_API void tcr_data_channel_close(TcrDataChannelHandle channel);
参数
类型
说明
channel
TcrDataChannelHandle
数据通道句柄。

获取 TcrAndroidInstance 操作对象

TcrAndroidInstance tcr_client_get_android_instance(TcrClientHandle client);
参数
类型
说明
client
TcrClientHandle
客户端句柄。

将多个实例加入当前群组会话

将多个实例加入当前群组会话,实现多实例同步控制。
void tcr_instance_join_group(TcrAndroidInstance op, const char** instanceIds, int32_t length);
参数
类型
说明
op
TcrAndroidInstance
实例操作句柄。
instanceIds
const char**
实例 ID 字符串数组。
length
int32_t
实例 ID 数组长度。

请求打开或关闭指定实例的视频流

请求打开或关闭指定实例的视频流,并设置流质量。
void tcr_instance_request_stream(TcrAndroidInstance op, const char* instanceID, bool status, const char* level);
参数
类型
说明
op
TcrAndroidInstance
实例操作句柄。
instanceID
const char*
实例 ID。
status
bool
true:打开流
false:关闭流。
level
const char*
流质量级别("low"、"normal"、"high")。

设置或取消主控实例

设置或取消主控实例,实现主从同步。
void tcr_instance_set_master(TcrAndroidInstance op, const char* instanceId, bool status);
参数
类型
说明
op
TcrAndroidInstance
实例操作句柄。
instanceId
const char*
主控实例 ID。
status
bool
true 设置为主控,false 取消主控。

设置群组会话同步实例列表

设置群组会话中需要被操作的实例列表。
void tcr_instance_set_sync_list(TcrAndroidInstance op, const char** instanceIds, int32_t length);
参数
类型
说明
op
TcrAndroidInstance
实例操作句柄。
instanceIds
const char**
需要同步控制的实例 ID 数组。
length
int32_t
实例 ID 数组长度。

获取指定实例的截图图片 URL

bool tcr_instance_get_image(TcrAndroidInstance op, char* buffer, int bufferLen, const char* instanceId, int width, int height, int quality);
参数
类型
说明
op
TcrAndroidInstance
实例操作句柄。
buffer
char*
输出缓冲区。
bufferLen
int
输出缓冲区长度。
instanceId
const char*
实例 ID。
width
int
图片宽度(≤0 为默认)。
height
int
图片高度(≤0 为默认)。
quality
int
图片质量(1-100)。

获取文件下载 URL

bool tcr_instance_get_download_address(TcrAndroidInstance op, char* buffer, int bufferLen, const char* instanceId, const char* path);
参数
类型
说明
op
TcrAndroidInstance
实例操作句柄。
buffer
char*
输出缓冲区。
bufferLen
int
缓冲区长度。
instanceId
const char*
实例 ID。
path
const char*
文件路径。

获取 logcat 日志下载地址

获取云手机实例 logcat 日志压缩包的下载地址。
bool tcr_instance_get_download_logcat_address(TcrAndroidInstance op, char* buffer, int bufferLen, const char* instanceId, int recentDays);
参数
类型
说明
op
TcrAndroidInstance
实例操作句柄。
buffer
char*
输出缓冲区。
bufferLen
int
缓冲区长度。
instanceId
const char*
实例 ID。
recentDays
int
下载几天内的日志。

上传文件到云实例相册

上传文件到云实例,固定上传至 /data/media/0/DCIM,并自动添加到相册。
bool tcr_instance_upload_media(
TcrAndroidInstance op,
const char* instanceId,
const char** local_paths,
int file_count,
char** output,
size_t* output_size,
const TcrUploadCallback* callback
);
参数
类型
说明
op
TcrAndroidInstance
实例操作句柄。
instanceId
const char*
实例 ID。
local_paths
const char**
本地文件路径数组。
file_count
int
文件数量。
output
char**
输出 JSON 字符串(需释放)。
output_size
size_t*
输出字符串长度。
callback
const TcrUploadCallback*
上传进度回调(可为 NULL)。

上传本地文件到云手机实例

上传本地文件到云手机实例指定目录。
bool tcr_instance_upload_files(
TcrAndroidInstance op,
const char* instanceId,
const char** local_paths,
const char** cloud_paths,
int file_count,
char** output,
size_t* output_size,
const TcrUploadCallback* callback
);
参数
类型
说明
op
TcrAndroidInstance
实例操作句柄。
instanceId
const char*
实例 ID。
local_paths
const char**
本地文件路径数组。
cloud_paths
const char**
云端目标路径数组(可为 NULL)。
file_count
int
文件数量。
output
char**
输出 JSON 字符串(需释放)。
output_size
size_t*
输出字符串长度。
callback
const TcrUploadCallback*
上传进度回调(可为 NULL)。

批量请求云端任务

tcr_instance_request 用于批量请求云端安卓实例的各类任务操作,包括但不限于分辨率修改、文本粘贴、GPS 修改、应用管理、设备属性变更、保活策略、媒体操作等。该接口支持一次性对多个实例下发同类型任务。
TcrErrorCode tcr_instance_request(TcrAndroidInstance op, const char* input_json, char** output, size_t* output_size);
参数
类型
说明
op
TcrAndroidInstance
实例操作句柄。
input_json
const char*
输入 JSON 字符串,指定任务类型、目标实例及参数,详见下方 输入 JSON 格式说明
output
char**
输出 JSON 字符串(需调用 tcr_instance_free_result 释放)。
output_size
size_t*
输出字符串长度。

输入 JSON 格式

{
"TaskType": "任务类型字符串",
"Params": {
"cai-xxxx-xxx": { ... }, // 实例ID: 任务参数
"cai-yyyy-yyy": { ... }
}
}
TaskType:必填,字符串,指定要执行的任务类型。支持的任务类型详见 下表
Params:必填,字典。key 为实例 ID,value 为该实例的任务参数对象。参数结构依赖于 TaskType。
支持的任务类型及参数说明
任务类型
说明
参数结构示例
ModifyResolution
修改分辨率。
{ "Width": 1080, "Height": 1920, "DPI": 320 }
ModifyGPS
修改 GPS 位置。
{ "Longitude": 121.47, "Latitude": 31.23 }
Paste
粘贴文本。
{ "Text": "hello" }
SendClipboard
发送剪贴板内容。
{ "Text": "hello" }
ModifySensor
修改传感器数据。
{ "Type": "accelerometer", "Values": [0.1, 0.2, 0.3], "Accuracy": 3 }
Shake
摇动设备。
{}
Blow
吹气。
{}
SendTransMessage
发送透传消息。
{ "PackageName": "com.example", "Msg": "hello" }
ModifyInstanceProperties
修改实例属性。
详见下方说明
ModifyKeepFrontAppStatus
修改保活应用状态。
{ "PackageName": "com.example", "Enable": true, "RestartInterValSeconds": 3 }
UnInstallByPackageName
卸载应用。
{ "PackageName": "com.example" }
StartApp
启动应用。
{ "PackageName": "com.example", "ActivityName": "xxx" }
StopApp
停止应用。
{ "PackageName": "com.example" }
ClearAppData
清除应用数据。
{ "PackageName": "com.example" }
EnableApp
启用应用。
{ "PackageName": "com.example" }
DisableApp
禁用应用。
{ "PackageName": "com.example" }
StartCameraMediaPlay
开始摄像头媒体播放。
{ "FilePath": "/sdcard/video.mp4", "Loops": 3 }
DisplayCameraImage
显示摄像头图像。
{ "FilePath": "/sdcard/image.jpg" }
AddKeepAliveList
添加保活列表。
{ "AppList": ["com.wechat", "com.alipay"] }
RemoveKeepAliveList
移除保活列表。
{ "AppList": ["com.wechat"] }
SetKeepAliveList
设置保活列表。
{ "AppList": ["com.wechat", "com.alipay"] }
DescribeKeepFrontAppStatus
获取保活应用状态。
{}
StopCameraMediaPlay
停止摄像头播放。
{}
DescribeCameraMediaPlayStatus
获取摄像头播放状态。
{}
DescribeKeepAliveList
获取保活列表。
{}
ClearKeepAliveList
清除保活列表。
{}
ListUserApps
列出用户应用。
{}
Mute
静音开关。
{ "Mute": true }
MediaSearch
媒体库文件搜索。
{ "Keyword": "abc" }
Reboot
重启实例。
{}
ListAllApps
查询所有应用列表。
{}
MoveAppBackground
关闭应用至后台。
{}
AddAppInstallBlackList
新增应用安装黑名单。
{ "AppList": ["com.xxx"] }
RemoveAppInstallBlackList
移除应用安装黑名单。
{ "AppList": ["com.xxx"] }
SetAppInstallBlackList
覆盖应用安装黑名单。
{ "AppList": ["com.xxx"] }
DescribeAppInstallBlackList
查询应用安装黑名单。
{}
ClearAppInstallBlackList
清空应用安装黑名单。
{}
说明:
详细参数结构和返回示例可参考头文件中的说明。
典型输入示例
{
"TaskType": "ModifyResolution",
"Params": {
"cai-xxxx-xxx": { "Width": 1080, "Height": 1920 },
"cai-yyyy-yyy": { "Width": 720, "Height": 1280 }
}
}
输出结果格式
返回值为一个 JSON 对象,key 为实例 ID,value 为该实例的任务执行结果对象。例如:
{
"cai-xxxx-xxx": { "Code": 0 },
"cai-yyyy-yyy": { "Code": 10100, "Msg": "operation denied" },
"cai-zzzz-zzz": { "Code": -101, "Msg": "HTTP request failed" }
}
Code为0表示成功,非0表示失败,Msg为失败原因。
某些查询类任务(如 DescribeInstanceProperties、ListUserApps 等)返回结构会包含详细数据,详见各任务类型在头文件中的说明。

其他说明

output 由 SDK 内部分配内存,使用完毕后需调用 tcr_instance_free_result 释放。
支持批量对多个实例下发同类型任务,便于大规模自动化管理。
返回的 JSON 字符串长度通过output_size返回。
任务类型及参数如有疑问,请参考接口注释或联系技术支持。

返回值

TCR_SUCCESS:任务请求成功。
TCR_ERR_INVALID_PARAMS:输入参数无效。

释放由 tcr_instance_request 分配的结果内存

void tcr_instance_free_result(TcrAndroidInstance op, char* output);
参数
类型
说明
op
TcrAndroidInstance
实例操作句柄。
output
char*
需要释放的内存指针。

设置远端视频帧观察者

设置远端视频帧观察者,用于接收解码后的视频帧数据。
void tcr_session_set_video_frame_observer(TcrSessionHandle session, const TcrVideoFrameObserver* observer);
参数
类型
说明
session
TcrSessionHandle
会话句柄。
observer
const TcrVideoFrameObserver*
视频帧观察者结构体指针。

视频帧缓冲区转 I420 格式

将输入的视频帧缓冲区转换为 I420 格式缓冲区。
TCRSDK_API bool tcr_video_frame_buffer_to_i420(const TcrVideoFrameBuffer* buffer, TcrI420Buffer* output_i420);
参数
类型
说明
buffer
const TcrVideoFrameBuffer*
输入的视频帧缓冲区。
output_i420
TcrI420Buffer*
输出的 I420 缓冲区指针。
返回值
bool
转换是否成功。

检查视频帧格式

检查视频帧缓冲区是否为D3D11格式。
TCRSDK_API bool tcr_video_frame_buffer_is_d3d11(const TcrVideoFrameBuffer* buffer);
参数
类型
说明
buffer
const TcrVideoFrameBuffer*
视频帧缓冲区。
返回值
bool
是否为D3D11格式。

获取 D3D11 纹理指针

获取视频帧缓冲区中的 D3D11 纹理指针(需保证缓冲区为 D3D11 格式)。
TCRSDK_API void* tcr_video_frame_buffer_get_d3d11_texture(const TcrVideoFrameBuffer* buffer);
参数
类型
说明
buffer
const TcrVideoFrameBuffer*
视频帧缓冲区(必须为 D3D11 格式)。
返回值
void*
ID3D11Texture2D 指针,失败时返回 NULL。

暂停媒体流

暂停媒体流(如视频流),通常用于临时挂起。
void tcr_session_pause_streaming(TcrSessionHandle session);
参数
类型
说明
session
TcrSessionHandle
会话句柄。

恢复媒体流

恢复媒体流(如视频流),与暂停配合使用。
void tcr_session_resume_streaming(TcrSessionHandle session);
参数
类型
说明
session
TcrSessionHandle
会话句柄。

设置远端视频流参数

设置远端视频流参数(帧率、码率等)。
void tcr_session_set_remote_video_profile(TcrSessionHandle session, int32_t fps, int32_t minBitrate, int32_t maxBitrate);
参数
类型
说明
session
TcrSessionHandle
会话句柄。
fps
int32_t
视频帧率。
minBitrate
int32_t
最小码率(kbps)。
maxBitrate
int32_t
最大码率(kbps)。

向云端应用发送透传消息

void tcr_session_send_trans_message(TcrSessionHandle session, const char* package_name, const char* msg);
参数
类型
说明
session
TcrSessionHandle
会话句柄。
package_name
const char*
应用包名。
msg
const char*
消息内容。

将文本写入剪贴板并粘贴到输入框

void tcr_session_paste_text(TcrSessionHandle session, const char* msg);
参数
类型
说明
session
TcrSessionHandle
会话句柄。
msg
const char*
文本内容。

将文本直接输入到输入框

该方法直接输入文本,不使用剪贴板。
注意:
调用此方法前,客户端必须已经收到 ime_type 设置为 "local" 的 IME_STATUS_CHANGE 事件。
void tcr_session_input_text(TcrSessionHandle session, const char* content, const char* mode);
参数
类型
说明
session
TcrSessionHandle
会话句柄。
content
const char*
输入文本内容。
mode
const char*
输入模式:"append" 或 "override"。

切换输入法

void tcr_session_switch_ime(TcrSessionHandle session, const char* ime);
参数
类型
说明
session
TcrSessionHandle
会话句柄。
ime
const char*
输入法类型:"cloud" 或 "local"。

启用本地摄像头

启用或禁用本地摄像头。
bool tcr_session_enable_local_camera(TcrSessionHandle session, bool enable);
参数
类型
说明
session
TcrSessionHandle
会话句柄
enable
bool
true 启用,false 禁用摄像头
返回值:操作是否成功,true 表示成功。

禁用本地摄像头

禁用本地摄像头。
void tcr_session_disable_local_camera(TcrSessionHandle session);
参数
类型
说明
session
TcrSessionHandle
会话句柄。

启用本地摄像头(带视频配置参数)

启用本地摄像头,支持指定视频配置参数。内部会自动查找并选择最匹配的摄像头。
建议客户端可通过 tcr_session_get_camera_device_counttcr_session_get_camera_device 获取设备支持的摄像头能力进行参数选择。
bool tcr_session_enable_local_camera_with_config(TcrSessionHandle session, const TcrVideoConfig* config);
参数
类型
说明
session
TcrSessionHandle
会话句柄。
config
const TcrVideoConfig*
视频配置参数。
返回值:是否成功启用,true 表示成功。

检查本地摄像头是否已启用

判断当前会话的本地摄像头是否已启用。
bool tcr_session_is_local_camera_enabled(TcrSessionHandle session);
参数
类型
说明
session
TcrSessionHandle
会话句柄。
返回值:true 已启用,false 未启用。

配置本地摄像头参数

设置摄像头的最大码率和最大帧率(需要先启用摄像头,否则无效)。
bool tcr_session_local_camera_config(TcrSessionHandle session, int max_bitrate_bps, int max_fps);
参数
类型
说明
session
TcrSessionHandle
会话句柄。
max_bitrate_bps
int
最大码率(单位:bps)。
max_fps
int
最大帧率(单位:fps)。
返回值:配置结果,true 表示成功。

获取可用摄像头设备数量

用于查询设备支持的摄像头数量,负值表示出错。
int tcr_session_get_camera_device_count(TcrSessionHandle session);
参数
类型
说明
session
TcrSessionHandle
会话句柄。
返回值:可用摄像头设备数量(≥0),负值表示出错。

获取摄像头设备

获取指定摄像头设备的详细信息。
TCRSDK_API bool tcr_session_get_camera_device(TcrSessionHandle session, int device_index, TcrCameraDeviceInfo* info);
参数
类型
说明
session
TcrSessionHandle
会话句柄。
device_index
int
设备索引,范围:(0, 设备数量-1)。
info
TcrCameraDeviceInfo
输出参数,指向 TcrCameraDeviceInfo 结构体,由调用方分配。
返回值:成功返回 true,失败返回 false。

启用本地麦克风

启用本地麦克风。
TCRSDK_API bool tcr_session_enable_local_microphone(TcrSessionHandle session);
参数
类型
说明
session
TcrSessionHandle
会话句柄。
返回值:是否成功启用,true 表示成功。

禁用本地麦克风

禁用本地麦克风。
TCRSDK_API void tcr_session_disable_local_microphone(TcrSessionHandle session);
参数
类型
说明
session
TcrSessionHandle
会话句柄。

检查本地麦克风

检查本地麦克风是否已启用。
TCRSDK_API bool tcr_session_is_local_microphone_enabled(TcrSessionHandle session);
参数
类型
说明
session
TcrSessionHandle
会话句柄。
返回值:是否已启用,true 表示已启用。

开关云端摄像头

void tcr_session_switch_camera(TcrSessionHandle session, const char* status);
参数
类型
说明
session
TcrSessionHandle
会话句柄。
status
const char*
状态:"open" 或 "close"。

开关云端麦克风

void tcr_session_switch_mic(TcrSessionHandle session, const char* status);
参数
类型
说明
session
TcrSessionHandle
会话句柄。
status
const char*
状态:"open" 或 "close"。

发送键盘事件

向云端实例发送单个键盘事件(按键按下/抬起),用于模拟物理键盘操作。
void tcr_session_send_keyboard_event(TcrSessionHandle session, int32_t keycode, bool down);
参数
类型
说明
session
TcrSessionHandle
会话句柄。
keycode
int32_t
按键码(建议使用十进制,可参考 keycode 列表 或 Android KeyEvent 定义)。
down
bool
true 表示按下(KeyDown),false 表示抬起(KeyUp)。

功能说明

该接口用于向云端实例发送单个按键事件,通常需要成对调用(即先发送按下事件,再发送抬起事件),以模拟真实物理键盘的操作。例如,模拟输入字母“A”时,应先调用一次 down=true,再调用一次 down=false

常用云手机按键 keycode 对照表(十进制)

按键名称
keycode
返回键
158
菜单键
139
Home 键
172
音量加
58
音量减
59

注意事项

keycode 建议使用十进制,部分特殊按键可参考上表或 Android KeyEvent 定义。
若需模拟连续输入,请依次发送对应的按下/抬起事件。
该接口仅发送单个按键事件,复杂输入需自行组合多次调用。

使用示例

模拟点击返回键:
tcr_session_send_keyboard_event(session, 158, true); // 按下
tcr_session_send_keyboard_event(session, 158, false); // 抬起

发送触摸屏触摸事件

void tcr_session_touchscreen_touch(TcrSessionHandle session, float x, float y, int eventType, int width, int height, long timestamp);
参数
类型
说明
session
TcrSessionHandle
会话句柄。
x
float
触摸点横坐标(像素)。
y
float
触摸点纵坐标(像素)。
eventType
int
事件类型。
0:按下
1:移动
2:抬起
width
int
屏幕宽度(像素)。
height
int
屏幕高度(像素)。
timestamp
long
事件时间戳(毫秒)。