本文提供声网远程控制(RDC)SDK API 参考,包括方法和回调事件。
RC_API agora::rdc::IRemoteControlEngine* RC_CALL createRDCEngine();
创建 IRemoteControlEngine
对象并返回指针。
注意
IRemoteControlEngine
对象。IRemoteControlEngine
对象时,务必调用 release
方法释放该对象占用的所有资源。返回
指向 IRemoteControlEngine
对象的指针。
示例代码
IRemoteControlEngine* lpEngine = createRDCEngine();
virtual int initialize(Configuration& config) = 0;
初始化声网 RDC SDK 服务。
请确保在调用其他 API 前先调用 initialize
初始化 IRemoteControlEngine
对象。
参数 | 描述 |
---|---|
config |
详见 Configuration 。 |
返回
0
:方法调用成功。0
:方法调用失败。错误码及错误信息详见初始化错误码。示例代码
IRemoteControlEngine* lpEngine = createRDCEngine();
Configuration config;
config.appId = "YourAppId"; // 请参考《开始使用声网平台》获取 App ID。
config.role = "role";
config.hwnd = "hwnd";
config.eventHandler = lpMyEventHandler;
lpEngine.initialize(config);
virtual int release() = 0;
销毁 IRemoteControlEngine
对象。
该方法释放声网远程控制 SDK 使用的所有资源。调用 release
方法后,你将无法再使用远程控制 SDK 的其它方法和回调。如需再次使用远程控制功能, 你必须重新依次调用 createRDCEngine
和 initialize
方法创建并初始化一个新的 IRemoteControlEngine
对象。
注意
如需在销毁后再次创建 IRemoteControlEngine
对象,请先等待 release
方法执行结束。
virtual int login(const char* userId, const char* token) = 0;
登录声网 RDC 系统。
成功调用该方法登录后,本地端会触发 EVT_LOGIN
回调。
注意
由于声网 RDC SDK 使用声网 RTM 的信令服务,因此登录声网 RDC 系统等同于登录声网 RTM 系统,并使用 RTM Token 鉴权机制。
参数 | 描述 |
---|---|
userId |
登录声网 RDC 系统的用户 ID。该字符串不可超过 64 字节。不可设为空、null 或 "null" 。以下为支持的字符集范围: |
token |
动态密钥,用于对即将加登录 RDC 系统的用户鉴权。token 设置为 NULL 。 |
返回
0
:方法调用成功。
≠0
:方法调用失败。错误码及错误信息详见登录错误码。
示例代码
if (lpEngine) {
lpEngine->login("Your userId", NULL);
}
virtual int logout() = 0;
登出声网 RDC 系统。
成功调用该方法登出后,本地端会触发 EVT_LOGOUT
回调。
返回
0
:方法调用成功。0
:方法调用失败。错误码及错误信息详见登出错误码。virtual int joinChannel(const char* channelId) = 0;
加入频道。
开始远程控制前,如果频道中其他用户需要实时观察主控端对被控端的屏幕操作,主控端和被控端需要调用该方法加入同一频道。如果仅需要一对一远程控制,则无需调用该方法。
成功调用该方加入频道后,本地端会触发 EVT_JOIN
回调。
参数 | 描述 |
---|---|
channelId |
标识远程控制的频道名称,长度在 64 字节以内的字符串。 以下为支持的字符集范围(共 89 个字符): |
返回
0
:方法调用成功。0
:方法调用失败。错误码及错误信息详见加入频道错误码。示例代码
if (lpEngine) {
lpEngine->joinChannel("YourChannelId");
}
virtual int leaveChannel() = 0;
离开频道。
主控端和被控端调用 joinChannel
加入频道后,必须调用 leaveChannel
结束远程控制,否则无法开始下一次远程控制。
成功调用该方离开频道后,本地端收到 EVT_LEAVE
回调。
返回
0
:方法调用成功。≠0
:方法调用失败。错误码及错误信息详见离开频道错误码。virtual int updateViewPort(int left, int top, int right, int bottom) = 0;
指定或更新远程控制的视图区域。
你需要在登录后或主控端窗口改变时,调用该方法指定或更新远程控制的视图区域。
注意
该方法必须由主控端(HOST
)调用,否则方法调用不生效。
参数 | 描述 |
---|---|
left |
视图区域左上角的横坐标(客户区坐标系) |
top |
视图区域左上角的纵坐标(客户区坐标系) |
right |
视图区域右下角的横坐标(客户区坐标系) |
bottom |
视图区域右下角的纵坐标(客户区坐标系) |
如何获取以上坐标,详见微软官方文档。
返回
0
:方法调用成功。≠0
:方法调用失败。请确认传入参数是否正确。示例代码
CRect rect;
GetClientRect(&rect); // 获取当前窗口客户区坐标
if (lpEngine) {
lpEngine->updateViewPort(rect.left, rect.top, rect.right, rect.bottom);
}
virtual int updateView(int screenId) = 0;
指定或更新被控端待共享的屏幕序号。
你需要在登录后调用该方法指定被控端待共享的屏幕,也可以在远程控制过程中调用该方法重新指定被控端待共享的屏幕。
注意
该方法必须由被控端(CONTROLLED
)调用,否则方法调用不生效。
参数 | 描述 |
---|---|
screenId |
被控端待共享的屏幕序号,是每个 IRemoteControlEngine 对象内被控端屏幕的唯一标识符,用于确保屏幕的有序性。例如:你的计算机共连接三个显示器, 0 (默认值) 代表主显示器,1 代表副显示器 1,2 代表副显示器 2。null 或 "null" 。 |
如何获取屏幕 ID,详见微软官方文档。
返回
0
:方法调用成功。≠0
:方法调用失败。请确认传入参数是否为空或超出取值范围。示例代码
int screenId = 0; // 被控端共享主屏幕。
lpEngine->updateView(screenId);
}
virtual int requestControl(const char* peer) = 0;
请求控制指定用户的计算机。
成功调用该方法后,对端收到 EVT_CONTROL_REQUEST
回调。如果调用失败,本地端收到 EVT_SEND_RESULT
回调,请根据发送点对点指令错误码和错误信息进行排查。
注意
该方法必须由主控端(HOST
)调用,否则方法调用不生效。
参数 | 描述 |
---|---|
peer |
被控端用户 ID,即被控端登录 RDC 系统的 userId 。不可设为空、null 或 "null" 。 |
返回
0
:方法调用成功。≠0
:方法调用失败。请确认传入参数是否为空。示例代码
if (lpEngine) {
lpEngine->requestControl(peerId);
}
virtual int answerRequestControl(const char* peer, bool answer = true) = 0;
响应指定用户的控制请求。
成功调用该方法后,对端收到 EVT_CONTROL_REQUEST
回调。如果调用失败,本地端收到 EVT_SEND_RESULT
回调,请根据发送点对点指令错误码和错误信息进行排查。
注意
该方法必须由被控端(CONTROLLED
)调用,否则方法调用不生效。
参数 | 描述 |
---|---|
peer |
主控端用户 ID,即主控端登录 RDC 系统的 userId 。不可设为空、null 或 "null" 。 |
answer |
响应指定用户的控制请求:true :同意指定用户的控制请求。false :拒绝指定用户的控制请求。 |
返回
0
:方法调用成功。≠0
:方法调用失败。请确认传入参数是否为空。示例代码
if (lpEngine) {
lpEngine->answerRequestControl(peerId, true);
}
virtual int quitControl(const char* peer) = 0;
请求退出远程控制。
主控端和被控端均可调用该方法,向对端请求退出远程控制。成功调用该方法后,对端收到 EVT_CONTROL_QUIT
回调。
参数 | 描述 |
---|---|
peer |
对端的用户 ID,即对端登录 RDC 系统的 userId 。不可设为空、null 或 "null" 。 |
返回
0
:方法调用成功。≠0
:方法调用失败。请确认传入参数是否为空。示例代码
if (lpEngine) {
lpEngine->quitControl(peerId);
}
virtual int answerQuitControl(const char* peer, bool answer = true) = 0;
响应指定用户的退出控制请求。
成功调用该方法后,对端收到 EVT_CONTROL_QUIT
回调。
注意
当被控端调用 quitControl
请求退出远程控制,主控端需要调用该方法进行响应。
当主控端调用 quitControl
请求退出远程控制,被控端无需调用该方法。
参数 | 描述 |
---|---|
peer |
对端用户 ID,即对端登录 RDC 系统的 userId 。不可设为空、null 或 "null" 。 |
answer |
响应对端的退出控制请求: true :同意对端的退出控制请求。false :拒绝对端的退出控制请求。 |
返回
0
:方法调用成功。≠0
:方法调用失败。请确认传入参数是否为空。示例代码
if (lpEngine) {
lpEngine->answerQuitControl(peerId, true);
}
break;
virtual int requestRemoteInfo(const char* peer) = 0;
获取对端信息。
参数 | 描述 |
---|---|
peer |
对端用户 ID。 |
virtual int remotePasteOp(bool isFile = false, const char* content = NULL) = 0;
主控端将本地文件或文本粘贴到被控端目标位置。
参数 | 描述 |
---|---|
isFile |
待粘贴内容类型为文件或文本:true :待粘贴内容为文件。false :(默认)待粘贴内容为文本。 |
content |
待粘贴内容。isFile 为 true ),则传入该文件的绝对路径。 isFile 为 false ),则传入 NULL ,SDK 会获取剪贴板内的文件或文本。 |
返回
0(ERR_OK)
:方法调用成功。0
:方法调用失败。错误码及错误信息详见文件传输错误码。virtual void onEvent(RDC_EVENT event, int code, const char* msg) = 0;
声网 RDC SDK 事件回调。
参数 | 描述 |
---|---|
event |
事件名称,详见 RDC_EVENT 。 |
code |
错误码,详见 RDC_EVENT 。 |
msg |
错误信息,详见 RDC_EVENT 。 |
示例代码
class MyRDCEventHandler : public IRemoteControlEventHandler {
public:
void onEvent(RDC_EVENT event, int code, const char* msg) {
switch (event) {
case EVT_ERROR:
// 处理逻辑
break;
case EVT_LOGIN:
// 处理逻辑
break;
...
}
}
};