本文提供声网远程控制(RDC)SDK API 参考,包括方法和回调事件。
如果你的项目已集成声网 RTC Native SDK,请创建 RDC Native 实例:
static create(rtcEngine: AgoraRtcEngine, options: RDCOptions & RDCThresholdOptions): AgoraRemoteDesktopControl
如果你的项目已集成声网 RTC Web SDK,请创建 RDC Web 实例:
static create(rtcEngine: IAgoraRTCClient, options: RDCOptions & RDCThresholdOptions): AgoraRemoteDesktopControl
创建并初始化一个本地端或 Web 端的 AgoraRemoteDesktopControl
实例。
AgoraRemoteDesktopControl
实例。create
方法前,你需要先初始化一个本地端 AgoraRtcEngine
实例或 Web 端 IAgoraRTCClient
实例。 参数 | 类型 | 描述 |
---|---|---|
rtcEngine |
IAgoraRTCClient | 初始化后的 RTC Native AgoraRtcEngine 实例或 RTC Web IAgoraRTCClient 实例。 |
options |
RDCOptions & RDCThresholdOptions | AgoraRemoteDesktopControl 实例的配置项。详见 RDCOptions 和 RDCThresholdOptions 。 仅主控端需要配置 RDCThresholdOptions 。 |
返回
初始化后的 AgoraRemoteDesktopControl
实例。
示例代码
import { AgoraRemoteDesktopControl, RDCRoleType } from 'agora-rdc-electron';
import AgoraRtcEngine from 'agora-electron-sdk';
const appId = '<YourAppId>'// 请参考《开始使用声网平台》获取 App ID。
const rtcEngine = new AgoraRtcEngine();
rtcEngine.initialize(appId);
const rdcEngine = AgoraRemoteDesktopControl.create(rtcEngine, { role: RDCRoleType.HOST, appId });
async getDisplays(): Promise<RDCDisplay[]>
获取被控端计算机的屏幕信息列表。
注意
该方法必须由被控端调用,否则 SDK 报错。
返回
Return Promise<RDCDisplay[]>
被控端计算机的屏幕信息列表。详见 RDCDisplay
。
示例代码
const displays: Display[] = rdcEngine.getDisplays();
async join(userId: string, token: string, channel: string, streamId: number, streamToken: string): Promise<void>;
加入频道。
调用远程控制其他方法前,主控端和被控端需要调用该方法加入同一频道。
rdc-join-error
。注意
对于 RDC Native 实例,调用 join
后还需要调用 AgoraRtcEngine
的 setChannelProfile(0)
、setClientRole(1)
、enableVideo
、joinChannel
。
参数 | 类型 | 描述 |
---|---|---|
userId |
String | 用户 ID,长度在 64 个字节内。支持的字符集为: App 层必须记住该传入值并维护,SDK 不对该返回值进行维护。频道内每个用户 ID 必须是唯一的。如果想要从不同的设备同时接入同一个频道,请确保每个设备上使用的用户 ID 是不同的。 |
token |
String | 动态密钥,用于对即将登录 RTM 系统的用户鉴权。你需要在服务端生成 Token,详见使用 RTM Token 鉴权。 |
channel |
String | 标识远程控制的频道名称,长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符): |
streamId |
Number | 屏幕流 ID,32 位无符号整数。建议设置范围:1 到 (232-1),并保证唯一性。 |
streamToken |
String | 动态密钥,用于对即将加入 RTC 频道的用户鉴权。你需要在服务端生成 Token,详见使用 RTC Token 鉴权。 请确保生成 RTC Token 时传入的用户 ID 和频道名称与上述 streamId 和 channel 的值一致,传入的 App ID 与调用 create 方法时传入的 App ID 一致。 |
返回
Promise<void>
示例代码
const userId = ;
const userToken = ;
const screenStreamId = ;
const screenStreamToken = ;
await rdcEngine.join(userId, userToken, channel, screenStreamId, screenStreamToken);
requestControl(userId: string): void
请求控制指定用户的计算机。
成功调用该方法后,对端会触发 on('rdc-request-control')
回调。
注意
该方法必须由主控端收到如下 RTC 加入频道的回调后方可调用,否则 SDK 报错。
onUserJoined
(Windows)/didJoinedOfUid
(macOS)AgoraRTCClient.on("user-joined")
参数 | 类型 | 描述 |
---|---|---|
userId |
String | 用户 ID,被控端加入频道时的 userId。 |
返回
Returns void
示例代码
const userId = ;
rdcEngine.requestControl(userId);
authorizeControl(userId: string, display: RDCDisplay, configuration?: Partial<RDCDisplayConfiguration>): void
授权指定用户控制计算机。
成功调用该方法后,对端会触发 on('rdc-request-control-authorized')
回调。
注意
该方法必须由被控端收到 on('rdc-request-control')
回调后方可调用,否则 SDK 报错。
参数 | 类型 | 描述 |
---|---|---|
userId |
String | 用户 ID。该 userId 的值为主控端用户 ID,即 on('rdc-request-control') 回调中的 userId 。 |
display |
RDCDisplay | 被控端计算机的屏幕信息。详见 RDCDisplay 。 |
configuration |
Partial |
(选填)被控端计算机编码配置。详见 RDCDisplayConfiguration 。 |
示例代码
const displays: Display[] = await rdcEngine.getDisplays();
let userId;
rdcEngine.on('rdc-request-control', (userId) => {
userId = userId;
});
const rdcEngine.authorizeControl(userId, displays[0]); // 授权控制主显示器
返回
Returns void
unauthorizeControl(userId: string): void
拒绝指定用户的控制请求。
成功调用该方法后,对端会触发 on('rdc-request-control-unauthorized')
回调。
注意
该方法必须由被控端收到 on('rdc-request-control')
回调后方可调用,否则 SDK 报错。
参数 | 类型 | 描述 |
---|---|---|
userId |
String | 用户 ID。该 userId 为主控端用户 ID,即 on('rdc-request-control') 回调中的 userId 。 |
示例代码
let userId;
rdcEngine.on('rdc-request-control', (userId) => {
userId = userId;
});
const rdcEngine.unauthorizeControl(userId);
返回
Returns void
async takeControl(userId: string, streamId: number, attachEl: HTMLElement): Promise<void>
控制指定用户的计算机。
注意
该方法必须由主控端收到 on('rdc-request-control-authorized')
回调后方可调用,否则 SDK 报错。
参数 | 类型 | 描述 |
---|---|---|
userId |
String | 用户 ID。该 userId 为被控端用户 ID,即 on('rdc-request-control-authorized') 回调中的 userId 。 |
streamId |
Number | 屏幕流 ID。被控端加入频道时设置的 streamId 。 |
attachEl |
HTMLElement | 被控端屏幕流渲染的 HTML 元素。 |
示例代码
const userId = {userId};
const streamId = ;
const attachEl = ;
const rdcEngine.takeControl(userId, streamId, attachEl);
返回
Returns Promise
quitControl(userId: string, role: RDCRoleType): void
被控端停止指定用户对自身计算机的控制。
成功调用该方法后,主控端会触发 on('rdc-quit-control')
回调。
注意
主控端收到 on('rdc-quit-control')
回调后,需要调用 quitControl [2/2]
停止控制。
参数 | 类型 | 描述 |
---|---|---|
userId | String | 用户 ID。该 userId 为主控端用户 ID,即 on('rdc-request-control') 回调中的 userId 。 |
role | RDCRoleType | 用户角色类型,设置为 1 (主控端)。 |
返回
Returns void
quitControl(userId: string, role: RDCRoleType, streamId: number): void
主控端停止对指定用户屏幕计算机的控制。
成功调用该方法后,被控端触发 on('rdc-quit-control')
回调。
注意
被控端收到 on('rdc-quit-control')
回调后,需要调用 quitControl [1/2]
停止控制。
参数 | 类型 | 描述 |
---|---|---|
userId |
String | 用户 ID。该 userId 为被控端用户 ID,即 on('rdc-request-control-authorized') 回调中的 userId 。 |
role |
RDCRoleType | 用户角色类型,设置为 2 (被控端)。 |
streamId |
Number | 屏幕流 ID,被控端加入频道时设置的 streamId 。 |
leave(): void
离开频道。
主控端和被控端调用 join
后,必须调用 leave
结束远程控制,否则无法开始下一次远程控制。
该方法会把会话相关的所有资源释放掉。该方法是异步操作,调用返回时并没有真正退出频道。
成功调用该方法离开频道后,相当于离开 RTC 频道,并登出 RTM 系统。你需要自行监听离开 RTC 频道事件。
返回
Returns void
dispose(): void
销毁 AgoraRemoteDesktopControl
实例。
该方法释放声网 RDC SDK 使用的所有资源。只要调用了 dispose
方法, 用户将无法再使用和回调该 SDK 内的其它方法。如需再次使用远程控制,必须重新创建一个 AgoraRemoteDesktopControl
实例。
返回
Returns void
requestFullscreen(attachEl: HTMLElement, options?: FullscreenOptions): Promise<void>
将已控制的被控端计算机的屏幕设置为全屏模式。
成功调用该方法后,本地端触发 on('rdc-fullscreen-change')
事件。
注意
该方法必须由主控端收到 on('rdc-request-control-authorized')
回调后方可调用。
参数 | 类型 | 描述 |
---|---|---|
attachEl |
HTMLElement | 被控端屏幕流渲染的 HTML 元素。 |
options |
FullscreenOptions | (选填)远程控制处于全屏模式时,导航 UI 的显示状态设置。详见 Web 官方文档。 |
返回
Returns Promise
async exitFullscreen(): Promise<void>
将已控制的被控端计算机的屏幕退出全屏模式。
成功调用该方法后,本地端触发 on('rdc-fullscreen-change')
事件。
注意
该方法必须由主控端调用。
返回
Returns Promise
observe(userId: string, streamId: number, attachEl: HTMLElement)
请求观测主控端对频道中其他被控端计算机的操作。
主控端 A 与被控端 B、C 在同一频道中,且当前主控端 A 正在控制被控端 B 的计算机。被控端 C 可以调用该方法,请求观测主控端 A 对被控端 B 的操作:
allowObservation
方法允许观测行为,被控端 C 的观测行为生效。disallowObservation
方法拒绝观测行为,被控端 C 的观测行为不生效。unobserve
方法,停止观测行为。注意
该方法必须由被控端加入频道后方可调用,否则 SDK 报错。
参数 | 类型 | 描述 |
---|---|---|
userId |
String | 用户 ID。该 userId 为被控端用户 ID,即 on('rdc-request-control-authorized') 回调中的 userId 。 |
streamId |
Number | 屏幕流 ID,被控端加入频道时设置的 streamId 。 |
attachEl |
HTMLElement | 被控端屏幕流渲染的 HTML 元素,详见 Web 官方文档。 |
allowObservation(): void
允许频道中用户观测主控端对其他被控端计算机的操作行为。
注意
该方法必须由主控端加入频道后方可调用,否则 SDK 报错。
返回
Returns void
disallowObservation(): void
不允许频道中用户观测主控端对其他被控端计算机的操作行为。
注意
该方法必须由主控端加入频道后方可调用,否则 SDK 报错。
返回
Returns void
unobserve(userId: string, streamId: number)
停止观测主控端对频道中其他被控端计算机的操作行为。
注意
该方法必须由被控端加入频道后方可调用,否则 SDK 报错。
参数 | 类型 | 描述 |
---|---|---|
userId |
String | 用户 ID。该 userId 为被控端用户 ID,即 on('rdc-request-control-authorized') 回调中的 userId 。 |
streamId |
Number | 屏幕流 ID,被控端加入频道时设置的 streamId 。 |
你可以通过 on()
监听以下事件,也可以通过 off()
取消监听以下事件。
on(event: 'rdc-state', callback: (code: RDCEngineState, message: string) => void): this;
AgoraRemoteDesktopControl
实例状态变化回调。
参数 | 描述 |
---|---|
event |
事件名称,即rdc-state 。 |
callback |
回调内容。该事件的回调内容包括如下字段:code :状态码。详见 RDCEngineState 。message :状态说明信息。对状态码的详细说明。 |
on(event: 'rdc-request-control', callback: (userId: string) => void): this;
请求远程控制回调。
参数 | 描述 |
---|---|
event |
事件名称,即 rdc-request-control 。 |
callback |
回调内容。该事件的回调内容为主控端 userId 。 |
on(event: 'rdc-request-control-authorized', callback: (userId: string) => void): this;
授权指定用户控制回调。
参数 | 描述 |
---|---|
event |
事件名称,即 rdc-request-control-authorized 。 |
callback |
回调内容。该事件的回调内容为被控端 userId 。 |
on(event: 'rdc-request-control-unauthorized', callback: (userId: string) => void): this;
拒绝授权指定用户控制回调。
参数 | 描述 |
---|---|
event |
事件名称,即 rdc-request-control-unauthorized 。 |
callback |
回调内容。该事件的回调内容为被控端 userId 。 |
on(event: 'rdc-quit-control', callback: (userId: string) => void): this;
停止远程控制回调。
主控端和被控端均需要监听该回调事件。
参数 | 描述 |
---|---|
event |
事件名称,即 rdc-quit-control 。 |
callback |
回调内容。该事件的回调内容为远端userId 。例如,主控端调用 quitControl 后,被控端收到 rdc-quit-control 回调为主控端 userId 。 |
on(event: 'rdc-fullscreen-change', callback: (isFullscreen: boolean) => void): this;
全屏状态变化回调。
参数 | 描述 |
---|---|
event |
事件名称,即 rdc-fullscreen-change 。 |
callback |
回调内容。该事件的回调内容为 isFullscreen 参数,表示当前控制的屏幕是否为全屏模式。 |
文件或文本粘贴状态回调。
该回调用于主控端到被控端的文件、文本传输,当主控端将本地文件或文本粘贴到被控端时,SDK 会触发该回调。
你可以使用快捷键 Ctrl + C 或 Command + C 复制文件或文本,使用 Ctrl + V 或 Command + V 将文件粘贴到被控端的文件夹,或将文本粘贴到被控端的文本输入区,例如文本、文档、代码编辑器等。
注意
文件大小必须在 30MB 以内,文本内容必须在 24KB 以内。
on(
event: 'rdc-remote-paste',
callback: (status: RDCRemotelyPastingStatus, code: RDCRemotelyPastingCodes) => void,
): this;
参数 | 描述 |
---|---|
event |
事件名称,即rdc-remote-paste 。 |
callback |
回调内容。该事件的回调内容包括如下字段:status :文件或文本的粘贴状态。详见 RDCRemotelyPastingStatus 。code :状态码,详见 RDCRemotelyPastingCodes 。 |
on(event: 'rdc-join-error', callback: (code: RDCJoinErrorCode, message: string) => void): this;
加入频道出错回调。表示用户加入频道时发生错误。
参数 | 描述 |
---|---|
event |
事件名称,即 rdc-join-error 。 |
callback |
回调内容。该事件的回调内容包括如下字段:code :错误码。详见 RDCJoinErrorCode 。message :错误信息。对错误码的详细描述。 |