agora-rdc-core
Version:
376 lines (375 loc) • 19.5 kB
TypeScript
import { EventEmitter } from './event-emitter';
import { RDCAddonAdapter, RDCEngineState, RDCJoinErrorCode, RDCMouseEventType } from '../addon';
import { RDCDisplay, RDCDisplayConfiguration, RDCOptions, RDCRoleType, RDCState, RDCThresholdOptions, RDCCapturedBy, RDCRemotelyPastingStatus, RDCRemotelyPastingCodes, Point, RDCPlatform, RDCAndroidAction } from './interfaces';
import { AbstractRTCAdapter } from './abstract-rtc-adapter';
/**
* Agora RDC Engine for remote desktop control
*/
export declare abstract class AbstractAgoraRemoteDesktopControl<T> extends EventEmitter {
protected abstract rtcAdapter: AbstractRTCAdapter<T>;
protected abstract get capturedBy(): RDCCapturedBy;
protected options: RDCOptions & RDCThresholdOptions;
protected rdcAdapter: RDCAddonAdapter;
protected state: {
[userId: string]: Partial<RDCState>;
};
protected channel?: string;
protected userId?: string;
protected streamId?: number;
/**
* @hidden
*/
constructor(options: RDCOptions);
/**
* Get the role of current user. see {@link RDCRoleType}
*
* Example:
* ```typescript
* const role = rdcEngine.getRole();
* ```
*
*/
getRole(): RDCRoleType;
/**
* Get a list of display's information.
*
* Example:
* ```typescript
* const displays: Display[] = await rdcEngine.getDisplays();
* ```
*
* @returns {Promise<RDCDisplay[]>} A promise object, when the promise object is `resolved` then you will get an array of displays information. see {@link RDCDisplay}
*
* @description this method must be called by controlled end, otherwise the promise object will be rejected.
*/
getDisplays(): Promise<RDCDisplay[]>;
/**
* Join an Agora RTC channel and logged into RTM.
*
* Example:
* ```typescript
* const userId = ; // userId generated by your server
* const userToken = ; // userToken generated by your server
* const screenStreamId = ; // screenStreamId generated by your server
* const screenStreamToken = ; // screenStreamToken generated by your server
* await rdcEngine.join(userId, userToken, channel, screenStreamId, screenStreamToken);
* ```
*
* @description Both host end and controlled end must be setup same channel.
* @description Please manage userId and streamId by yourself, we don't maintain any userId and streamId.
*
* @param userId The userId of the user logging in the Agora RTM system. The string length must be less than 64 bytes with the following character scope:
* - All lowercase English letters: a to z
* - All uppercase English letters: A to Z
* - All numeric characters: 0 to 9
* - The space character
* - Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
* @param token A Agora RTM token generated at your server. see [Get a token](https://docs.agora.io/en/Agora%20Platform/token?platform=All%20Platforms#get-a-token)
* @param channel A string that provides a unique channel name for the session. The length must be within 64 bytes. Supported character scopes:
* - All lowercase English letters: a to z
* - All uppercase English letters: A to Z
* - All numeric characters: 0 to 9
* - The space character
* Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
* @param streamId The screen stream's uid, an integer , ASCII characters only. Ensure this ID is unique. it should be a 32-bit unsigned integer with a value ranging from 0 to (232-1).
* @param streamToken A Agora RTC token generated at your server. see [Get a token](https://docs.agora.io/en/Agora%20Platform/token?platform=All%20Platforms#get-a-token)
* @returns
*/
join(userId: string, token: string, channel: string, streamId: number, streamToken: string): Promise<void>;
/**
* Request to control specific user's personal computer.
*
* Example:
* ```typescript
* const userId = ; // the userId which is you maintained.
* rdcEngine.requestControl(userId);
* ```
*
* @description Make sure that the user you want to control has joined.
* @description SDK will trigger `rdc-request-control` event at controlled end when this method was called host end. see {@link on}
* @description This method must be called by host end, otherwise will throw error.
*
* @param userId The userId which is you want to take control.
*/
requestControl(userId: string): void;
/**
* Authorize to control user's personal computer when the user has been received `rdc-request-control` event after.
*
* Example:
* ```typescript
* const displays: Display[] = await rdcEngine.getDisplays();
* let userId; // The userId which is you getting userId in the `rdc-request-control` event's callback.
*
* rdcEngine.on('rdc-request-control', (userId) => {
* userId = userId;
* });
*
* const rdcEngine.authorizeControl(userId, displays[0]); // get the first item in displays.
* ```
*
* @description SDK will trigger `rdc-request-control-authorized` event at host end when this method was called by controlled end. see {@link on}
* @description This method must be called by controlled end, otherwise will throw error.
*
* @param userId The userId, which is you getting userId in the `rdc-request-control` event's callback.
* @param display The display, which is should be controlled display. see {@link RDCDisplay}
* @param configuration The configuration, see {@link RDCDisplayConfiguration}
* @param withAudio Allows you to share the audio when you authorize the control. only works on Windows platform. see [limitation](https://github.com/electron/electron/blob/main/docs/api/desktop-capturer.md#caveats)
*/
authorizeControl(userId: string, display: RDCDisplay, configuration?: Partial<RDCDisplayConfiguration>, withAudio?: boolean): void;
/**
* Decline the other user's request to control current user's personal computer when the user has been received `rdc-request-control` event after.
*
* Example:
* ```typescript
* let userId; // The userId which is you getting userId in the `rdc-request-control` event's callback.
*
* rdcEngine.on('rdc-request-control', (userId) => {
* userId = userId;
* });
*
* const rdcEngine.unauthorizeControl(userId);
* ```
*
* @description SDK will trigger `rdc-request-control-unauthorized` event at host end when this method was called by controlled end. see {@link on}
* @description This method must be called by controlled end, otherwise will throw error.
*
* @param userId The userId, which is you getting userId in the `rdc-request-control` event's callback.
*/
unauthorizeControl(userId: string): void;
/**
* Take control user's personal computer when the request has been authorized.
*
* Example:
* ```typescript
* const userId = ; // `controlled` end's userId
* const streamId = ; // screen stream's streamId of `controlled` end
* const attachEl = ; // HTML element, the screen stream will be render to this element.
*
* const rdcEngine.takeControl(userId, streamId, attachEl);
* ```
*
* @description This method must be called by host end, otherwise will throw error.
*
* @param userId The userId, which is you getting userId in the `rdc-request-control-authorized` event's callback.
* @param streamId The streamId, which is controlled end's streamId that is you maintained.
* @param attachEl The attachEl, which is an HTML element, the screen stream will be render to this element.
*/
takeControl(userId: string, streamId: number, attachEl: HTMLElement): Promise<void>;
/**
* The `controlled` end's user terminate controlling.
*
* @description SDK will trigger `rdc-quit-control` event at `host` end. when the `controlled` end call this method.
* @description When the `rdc-quit-control` event is occurred at `host` end, you should call {@link quitControl} at `host` end either.
*
* @param userId The userId, which is `host` end's userId.
* @param role The role, role must be matched with userId which is `host` end's userId.
*/
quitControl(userId: string, role: RDCRoleType): void;
/**
* The `host` end's user stop controlling personal computer.
*
* @description SDK will trigger `rdc-quit-control` event at `controlled` end. when the `host` end call this method.
* @description When the `rdc-quit-control` event is occurred at `controlled` end, you should call {@link quitControl} at `controlled` end either.
*
* @param userId The userId, which is `controlled` end's userId.
* @param role The role, role must be matched with userId which is `controlled` end's userId.
* @param streamId The streamId, streamId must be the screen stream's streamId, and matched with userId which is `controlled` end's userId.
*/
quitControl(userId: string, role: RDCRoleType, streamId: number): void;
/**
* The user leave the channel.
*
* @description The user left the Agora RTC channel that the user was joined before.
* @description The user logout Agora RTM System that the user was logged before. if the user was joined Agora RTM channel, will be left this channel either.
*
*/
leave(): void;
/**
* Dispose the instance of {@link AgoraRemoteDesktopControl}
*/
dispose(): void;
/**
* Request full screen.
* @param attachEl The `screen stream` rendered view will be attached element.
* @param options @link [Spec](https://developer.mozilla.org/en-US/docs/Web/API/Element/requestFullScreen#options)
* @returns void
*/
abstract requestFullscreen(attachEl: HTMLElement, options?: FullscreenOptions): Promise<void>;
/**
* Exit full-screen, which is currently being presented in full-screen mode be taken out of full-screen mode.
* @returns
*/
exitFullscreen(): Promise<void>;
/**
* Allow observing the operation of the controlled end controlled by the host end.
* @description This method must be called by host end, otherwise will throw error.
*/
allowObservation(): void;
/**
* Disallow observing the operation of the controlled end controlled by the host end.
* @description This method must be called by host end, otherwise will throw error.
*/
disallowObservation(): void;
/**
* Observe the operation of the controlled end controlled by the host end.
* @description This method must be called by controlled end, otherwise will throw error.
* @param userId The userId, which is controlled end's userId that is you maintained.
* @param streamId The streamId, which is controlled end's streamId that is you maintained.
* @param attachEl The attachEl, which is an HTML element, the screen stream will be render to this element.
*/
observe(userId: string, streamId: number, attachEl: HTMLElement): void;
/**
* Stop observing the operation of the controlled and controlled by the host end.
* @description This method must be called by controlled end, otherwise will throw error.
* @param userId The userId, which is controlled end's userId that is you maintained.
* @param streamId The streamId, which is controlled end's streamId that is you maintained.
*/
unobserve(userId: string, streamId: number): void;
requestPlatform(userId: string): Promise<RDCPlatform>;
/**
* Send action to controlled end.
*
* @description This method must be called by host end, otherwise will throw error.
* @description This method only support when controlled end is {@link RDCPlatform.ANDROID} for now.
*
* @param userId controlled end's userId
* @param platform controlled end's platform, see {@link RDCPlatform}, you can get platform by calling {@link requestPlatform}
* @param action action name, see {@link RDCAndroidAction}
*
*/
sendAction(userId: string, platform: RDCPlatform, action: RDCAndroidAction): void;
/**
* It will be fired, when RDC engine's state changed.
* @param event 'rdc-state'
* @param callback
*/
on(event: 'rdc-state', callback: (code: RDCEngineState, message: string) => void): this;
/**
* It will be fired, when `requestControl` method was called by that RDC engine's role was setup `RDCRoleType.HOST`.
* @param event 'rdc-request-control'
* @param callback
*/
on(event: 'rdc-request-control', callback: (userId: string) => void): this;
/**
* It will be fired, when `authorizeControl` method was called by that RDC engine's role was setup `RDCRoleType.CONTROLLED`.
* @param event 'rdc-request-control-authorized'
* @param callback
*/
on(event: 'rdc-request-control-authorized', callback: (userId: string) => void): this;
/**
* It will be fired, when `unauthorizeControl` method was called by that RDC engine's role was setup `RDCRoleType.CONTROLLED`.
* @param event 'rdc-request-control-unauthorized'
* @param callback
*/
on(event: 'rdc-request-control-unauthorized', callback: (userId: string) => void): this;
/**
* It will be fired, when `quitControl` method was called by that RDC engine's role was setup `RDCRoleType.CONTROLLED`.
* @param event 'rdc-quit-control'
* @param callback
*/
on(event: 'rdc-quit-control', callback: (userId: string) => void): this;
/**
* It will be fired, when `requestFullscreen` or `exitFullscreen` method was called.
* @param event 'rdc-fullscreen-change'
* @param callback
*/
on(event: 'rdc-fullscreen-change', callback: (isFullscreen: boolean) => void): this;
on(event: 'rdc-join-error', callback: (code: RDCJoinErrorCode, message: string) => void): this;
/**
* It will be fired, when the file or content paste to `controlled end`.
* limitation:
* - file's max size is 30MB;
* - content's max size 24 KB;
* - can not copy folder and paste into the controlled end's folder.
* about the status you can see {@link RDCRemotelyPastingStatus}.
* about the code you can see {@link RDCRemotelyPastingCodes}.
* @description drag & drop files into the controlled end's folder.
* @description Press the shortcut key `ctrl + c` (Windows) or `command + c` (macOS) to copy the file or content. then you can press the shortcut key `ctrl + v` (macOS and Windows) to paste the file into the folder of the controlled end or paste the content into the text input area of the controlled end (for example: text, document editor, etc.).
* @param event 'rdc-remote-paste'
* @param callback
*/
on(event: 'rdc-remote-paste', callback: (status: RDCRemotelyPastingStatus, code: RDCRemotelyPastingCodes) => void): this;
on(event: string | symbol, listener: Function, prepend?: boolean): this;
/**
* Off event
* @param event 'rdc-state'
* @param callback
*/
off(event: 'rdc-state', callback: (code: RDCEngineState, message: string) => void): this;
/**
* Off event
* @param event 'rdc-request-control'
* @param callback
*/
off(event: 'rdc-request-control', callback: (userId: string) => void): this;
/**
* Off event
* @param event 'rdc-request-control-authorized'
* @param callback
*/
off(event: 'rdc-request-control-authorized', callback: (userId: string) => void): this;
/**
* Off event
* @param event 'rdc-request-control-unauthorized'
* @param callback
*/
off(event: 'rdc-request-control-unauthorized', callback: (userId: string) => void): this;
/**
* Off event
* @param event 'rdc-quit-control'
* @param callback
*/
off(event: 'rdc-quit-control', callback: (userId: string) => void): this;
/**
* Off event
* @param event 'rdc-fullscreen-change'
* @param callback
*/
off(event: 'rdc-fullscreen-change', callback: (isFullscreen: boolean) => void): this;
/**
* Off event
* @param event 'rdc-join-error'
* @param callback
*/
off(event: 'rdc-join-error', callback: (code: RDCJoinErrorCode, message: string) => void): this;
/**
* Off event
* @param event 'rdc-remote-paste'
* @param callback
*/
off(event: 'rdc-remote-paste', callback: (status: RDCRemotelyPastingStatus, code: RDCRemotelyPastingCodes) => void): this;
off(event: string | symbol, listener: Function): this;
protected initialize(): void;
protected setState(userId: string, state: Partial<RDCState>): void;
protected getState(userId: string): Partial<RDCState>;
protected updateControlRect(width: number, height: number): void;
protected enableFocus(renderingEl: HTMLElement): void;
protected createCursorUpdater(renderingEl: HTMLElement): (userId: string, code: number) => void;
protected cursorUpdaterForWebRTC(renderingEl: HTMLElement, code?: number): void;
protected cursorUpdaterForElectronRTC(renderingEl: HTMLElement, code?: number): void;
protected abstract handleAttachElMutationChange(userId: string, isObserver?: boolean): MutationCallback;
protected handleAddonEvents(): void;
protected handleRequestControl: (message: string) => void;
protected handleGettingFocus: (message: string) => void;
protected handleRDCMessage: (message: string) => void;
protected handleRemotePasteEvent(status: RDCRemotelyPastingStatus, code: RDCRemotelyPastingCodes): void;
protected handleMouseStateChange: (message: string) => void;
protected handleMouseEvent: (userId: string, type: RDCMouseEventType) => (event: MouseEvent | WheelEvent) => void;
protected bindDOMEvents(userId: string, renderingEl: HTMLElement): void;
protected unbindDOMEvents(userId: string, renderingEl: HTMLElement): void;
protected handleClick(userId: string): (event: MouseEvent) => void;
protected handleDblclick(userId: string): (event: MouseEvent) => void;
protected handleMouseDown: (userId: string) => (event: MouseEvent) => void;
protected handleMouseUp: (userId: string) => (event: MouseEvent) => void;
protected handleMouseMove: (userId: string) => (event: MouseEvent) => void;
protected handleMouseLeave: (userId: string) => (event: MouseEvent) => void;
protected handleKeydownEvent: (userId: string) => (event: KeyboardEvent) => void;
protected handleKeyupEvent: (userId: string) => (event: KeyboardEvent) => void;
protected handleDrop: (userId: string) => (event: DragEvent) => void;
protected handleFullscreenChange: () => void;
protected getKeyCode: (event: KeyboardEvent) => number;
protected handleObservationPositionChange: (userId: string) => (points: Point[]) => void;
protected createCursor(userId: string, renderingEl: HTMLCanvasElement | HTMLVideoElement): void;
protected removeCursor(userId: string): void;
protected updateCursorMaskSize(userId: string, width: number, height: number): void;
}