Windows SDK 为开发者提供了完整的云手机集成能力，支持将远程云手机的操作界面与控制功能集成至自研应用。
运行环境说明
本 TcrSdk Windows C++ SDK 适用于 Windows 平台。请确保您的开发和运行环境满足以下要求：
操作系统：Windows 10 64位或更高版本（建议使用 Windows 10/11 64位）。
集成开发环境：Microsoft Visual Studio 2022/2019
若您使用 Qt 开发，请确保 Qt 工程配置为 MSVC 2022 64-bit 工具链。
运行库：需确保目标机器已安装
Visual C++ Redistributable for Visual Studio 2022 (x64)。获取 SDK
SDK | 下载地址 | SDK 说明文档 | 版本发布日志 |
Windows SDK |
工程环境准备
SDK 为纯 C 接口，无 Qt 依赖，可在任意 C++ 工程中集成。下文以 Qt Quick 工程为例，介绍典型的集成流程和注意事项。
依赖环境
TcrSdk：包含头文件、lib、dll 文件。
编译器要求
推荐集成环境使用 Microsoft Visual Studio 2022。
若使用 Qt 或其他项目，请确保编译器为 MSVC 2022 64-bit。
运行库：需确保目标机器已安装
Visual C++ Redistributable for Visual Studio 2022 (x64)。目录结构建议
CloudPhone_QtQuick/├── src/ # 业务代码├── qml/ # QML 资源├── shaders/ # 着色器├── third_party/│ └── TcrSdk/ # 拷贝下载的TcrSdk到此处│ ├── Release/│ └── Debug/└── CMakeLists.txt
CMake 工程配置
参考如下 CMake 配置片段，确保 SDK 头文件、lib、dll 正确集成：
# 源码与头文件target_include_directories(CloudPhone_QtQuick PRIVATE${CMAKE_CURRENT_SOURCE_DIR}/src${CMAKE_CURRENT_SOURCE_DIR}/third_party/TcrSdk/Release/include)# TcrSdk 库路径（以Release为例）set(TCRSDK_BASE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/third_party/TcrSdk)if(CMAKE_SIZEOF_VOID_P EQUAL 8)set(TCRSDK_PLATFORM x64)else()set(TCRSDK_PLATFORM Win32)endif()set(TCRSDK_DLL "${TCRSDK_BASE_DIR}/Release/${TCRSDK_PLATFORM}/TcrSdk.dll")set(TCRSDK_LIB "${TCRSDK_BASE_DIR}/Release/${TCRSDK_PLATFORM}/TcrSdk.lib")target_link_libraries(CloudPhone_QtQuick PRIVATE ${TCRSDK_LIB})# 拷贝 DLL 到输出目录add_custom_command(TARGET CloudPhone_QtQuick POST_BUILDCOMMAND ${CMAKE_COMMAND} -E copy_if_different${TCRSDK_DLL}$<TARGET_FILE_DIR:CloudPhone_QtQuick>)
SDK 典型使用流程
1. 初始化 Client
#include "tcr_c_api.h"TcrConfig config;config.Token = tokenResult.token.c_str(); // 业务后台获取的 Tokenconfig.AccessInfo = tokenResult.accessInfo.c_str(); // 业务后台获取的 AccessInfoTcrClientHandle tcrClient = tcr_client_get_instance();TcrErrorCode err = tcr_client_init(tcrClient, &config);if (err != TCR_SUCCESS) {// 处理初始化失败}
2. 获取实例截图（按需可选）
char buffer[2048];TcrAndroidInstance instance = tcr_client_get_android_instance(tcrClient);bool ok = tcr_instance_get_image(instance, buffer, 2048, instanceId.c_str(), 0, 0, 0);if (ok) {// buffer 返回图片 URL，可用于加载图片}
3. 创建串流会话并连接实例
单实例连接
TcrSessionHandle tcrSession = tcr_client_create_session(tcrClient);const char* instanceIds[] = { instanceId.c_str() };tcr_session_access(tcrSession, instanceIds, 1, false); // false 表示单实例
多实例连接
TcrSessionHandle tcrSession = tcr_client_create_session(tcrClient);std::vector<const char*> idPtrs;for (const auto& id : instanceIds) idPtrs.push_back(id.c_str());tcr_session_access(tcrSession, idPtrs.data(), idPtrs.size(), true); // true 表示多实例
说明：
如需动态加入实例组，可通过
tcr_instance_join_group。4. 设置回调
视频帧回调
static void VideoFrameCallback(void* user_data, const TcrVideoFrameBuffer* frame_buffer, int64_t timestamp_us, TcrVideoRotation rotation) {// 处理视频帧}static TcrVideoFrameObserver video_observer;video_observer.user_data = nullptr; // 可传 this 指针video_observer.on_frame_buffer = VideoFrameCallback;tcr_session_set_video_frame_observer(tcrSession, &video_observer);
事件回调
static void SessionEventCallback(void* user_data, TcrSessionEvent event, const char* eventData) {// 处理事件}static TcrSessionObserver session_observer;session_observer.user_data = nullptr; // 可传 this 指针session_observer.on_event = SessionEventCallback;tcr_session_set_observer(tcrSession, &session_observer);
5. 业务操作
实时控制
// 模拟返回键tcr_session_send_keyboard_event(tcrSession, 158, true); // 按下tcr_session_send_keyboard_event(tcrSession, 158, false); // 抬起// 触摸事件（按下）tcr_session_touchscreen_touch(tcrSession, 100, 200, 0, 720, 1280, 0); // eventType: 0=DOWN, 1=MOVE, 2=UP// 透传消息tcr_session_send_trans_message(tcrSession, "com.example.app", "your_message");// 粘贴文本tcr_session_paste_text(tcrSession, "hello world");// 切换输入法tcr_session_switch_ime(tcrSession, "cloud"); // "cloud" 或 "local"
批量任务
对云手机进行批量任务操作（如修改分辨率、应用管理等）：
const char* input_json = R"({"TaskType": "ModifyResolution","Params": {"cai-xxxx-xxx": { "Width": 1080, "Height": 1920 }}})";char* output = nullptr;size_t output_size = 0;TcrAndroidInstance instance = tcr_client_get_android_instance(tcrClient);TcrErrorCode code = tcr_instance_request(instance, input_json, &output, &output_size);if (code == TCR_SUCCESS && output) {// output 为 JSON 字符串, 具体内容需解析// ... 业务处理 ...tcr_instance_free_result(instance, output);}
6. 资源释放
每一个创建的会话实例在使用完成后必须释放：
tcr_client_destroy_session(tcrClient, tcrSession);
批量任务接口说明
批量任务调用
const char* input_json = R"({"TaskType": "ModifyResolution","Params": {"cai-xxxx-xxx": { "Width": 1080, "Height": 1920 }}})";char* output = nullptr;size_t output_size = 0;TcrErrorCode code = tcr_instance_request(instance, input_json, &output, &output_size);if (code == TCR_SUCCESS && output) {// output 为 JSON 字符串, 具体内容需要根据不同任务进行解析(不关注结果则可忽略)// ... 业务处理 ...tcr_instance_free_result(tcrOperator, output);}
支持的任务类型
操作类型 | 任务 |
修改分辨率 | ModifyResolution |
修改 GPS | ModifyGPS |
粘贴文本 | Paste |
发送剪贴板 | SendClipboard |
修改传感器 | ModifySensor |
摇动/吹气 | Shake Blow |
透传消息 | SendTransMessage |
修改实例属性 | ModifyInstanceProperties |
应用管理 | StartApp StopApp UnInstallByPackageName ClearAppData EnableApp DisableApp |
保活管理 | AddKeepAliveList RemoveKeepAliveList SetKeepAliveList ClearKeepAliveList DescribeKeepAliveList ModifyKeepFrontAppStatus |
摄像头 | StartCameraMediaPlay StopCameraMediaPlay DescribeCameraMediaPlayStatus DisplayCameraImage |
应用黑名单 | AddAppInstallBlackList SetAppInstallBlackList DescribeAppInstallBlackList ClearAppInstallBlackList |
查询应用列表 | ListUserApps ListAllApps |
静音 | Mute |
媒体库搜索 | MediaSearch |
重启实例 | Reboot |
应用后台 | MoveAppBackground |
详情参见头文件，每个任务类型的参数和返回格式均有详细说明。
常见问题与建议
内存释放：批量任务返回的
output 需调用 tcr_operator_free_result 释放。会话管理：每一个
TcrClientHandle只能调用一次tcr_session_access，如需多个会话请创建多个实例并释放使用过的实例。日志调试：您需要通过
tcr_set_log_callback、tcr_set_log_level 配置日志，以便在出现问题之后将日志反馈给开发团队定位问题。
