This page provides the Agora Remote & Desktop Control (RDC) SDK API reference, including methods and callback events.
RC_API agora::rdc::IRemoteControlEngine* RC_CALL createRDCEngine();
Creates an IRemoteControlEngine
object and returns a pointer.
Notes
IRemoteControlEngine
object per app.IRemoteControlEngine
object, be sure to call the release
method to release all resources occupied by the object.Returns
Pointer to an IRemoteControlEngine
object.
Sample code
IRemoteControlEngine* lpEngine = createRDCEngine();
virtual int initialize(const RtcEngineContext& context) = 0;
Initializes the Agora RDC SDK service.
Make sure to call initialize
to initialize theIRemoteControlEngine
object before calling other APIs.
Parameter | Description |
---|---|
config |
Configuration |
Returns
0
: Success.0
: Failure. For error codes and error information, see Initialization error codes.Sample code
IRemoteControlEngine* lpEngine = createRDCEngine();
Configuration config;
config.appId = "YourAppId"; // Refer to "Getting Started with Agora Platform" to get the App ID.
config.role = "role";
config.hwnd = "hwnd";
config.eventHandler = lpMyEventHandler;
lpEngine.initialize(config);
virtual int release() = 0;
Releases all IRemoteControlEngine
resources.
This method releases all resources used by the Agora RDC SDK. Once you call release
, you no longer use any methods or callbacks in the RDC SDK. To use the remote control function again, you must call the createRDCEngine
and initialize
methods in turn to create and initialize a new IRemoteControlEngine
object.
Notes
To create an IRemoteControlEngine
object again after destroying it, wait for the release
method to finish executing.
virtual int login(const char* userId, const char* token) = 0;
Logs in to the RDC system.
After successfully calling this method to log in, the local user triggers the EVT_LOGIN
callback.
Notes
Because the Agora RDC SDK uses the Agora RTM signaling service, logging in to the Agora RDC system is equivalent to logging in to the Agora RTM system and using the RTM Token authentication mechanism.
Parameter | Description |
---|---|
userId |
The ID of the user logging in the Agora RDC system. The string must not exceed 64 bytes in length. It cannot be empty, null , or "null" . Supported characters: |
token |
The dynamic key used to authenticate users who log in to the RDC system.token as NULL in the integration and test stages. |
Returns
0
: Success.
≠0
: Failure. For error codes and error information, see Login error codes.
Sample code
if (lpEngine) {
lpEngine->login("Your userId", NULL);
}
virtual int logout() = 0;
Logs out of the Agora RDC system.
A successful call of this method triggers the EVT_LOGOUT
callback on the local client.
Returns
0
: Success.0
: Failure. For error codes and error messages, see Logout error codes.virtual int joinChannel(const char* channelId) = 0;
Joins a channel.
Before starting the remote control, if other users in the channel need to observe the screen operation of the host side on the controlled side in real time, the host side and the controlled side need to call this method to join the same channel. If you only need one-to-one remote control, you do not need to call this method.
A successful call of this method triggers the EVT_JOIN
callback on the local client.
Parameter | Description |
---|---|
channelId |
The unique channel name for the Agora RDC session in the string format. The string length must be less than 64 bytes. Supported characters: |
Returns
0
: Success.0
: Failure. For error codes and error information, see Error codes for joining channel.Sample code
if (lpEngine) {
lpEngine->joinChannel("YourChannelId");
}
virtual int leaveChannel() = 0;
Leaves a channel.
After the host side and the controlled side call joinChannel
to join the channel, they must call leaveChannel
to end the remote control process; otherwise, the next remote control process cannot be started.
A successful call of this method triggers the EVT_LEAVE
callback on the local client.
Returns
0
: Success.0
: Failure. For error codes and error messages, see Error codes for leaving channel.virtual int updateViewPort(int left, int top, int right, int bottom) = 0;
Specifies or updates the view area of the remote control.
You need to call this method to specify or update the view area of the remote control after logging in or when the host's window changes.
Notes
This method must be called by the host side (HOST
); otherwise, the method call does not take effect.
Parameter | Description |
---|---|
left |
The abscissa of the upper left corner of the view area (client area coordinate system) |
top |
The ordinate of the upper left corner of the view area (client area coordinate system) |
right |
The abscissa of the lower right corner of the view area (client area coordinate system) |
bottom |
The ordinate of the lower right corner of the view area (client area coordinate system) |
For how to obtain the above coordinates, see Microsoft's official documentation.
Returns
0
: Success.0
: Failure. Check the parameter setting.Sample code
CRect rect;
GetClientRect(&rect); // Get the coordinates of the client area of the current window
if (lpEngine) {
lpEngine->updateViewPort(rect.left, rect.top, rect.right, rect.bottom);
}
virtual int updateView(int screenId) = 0;
Specify or update the screen number to be shared by the controlled side.
You need to call this method after logging in to specify the screen to be shared by the controlled side, or you can call this method during the remote control process to redesignate the screen to be shared by the controlled side.
Notes
This method must be called by the controlled side (CONTROLLED
); otherwise, the method call does not take effect.
Parameter | Description |
---|---|
screenId |
The number of the screen to be shared by the controlled side is the unique identifier of the controlled side screen in each IRemoteControlEngine object, which is used to ensure the correct order of the screens. For example: If there are three monitors connected to your computer, 0 (default) represents the main display, 1 represents secondary display 1, and 2 represents secondary display 2.null , or "null" . |
For how to get the screen ID, see Microsoft's official documentation.
Returns
0
: Success.0
: Failure. Check whether the parameter setting is empty or out of range.Sample code
int screenId = 0; // The controlled side shares the main screen.
lpEngine->updateView(screenId);
}
virtual int requestControl(const char* peer) = 0;
Requests control of the specified user's computer.
A successful call of this method triggers the EVT_CONTROL_REQUEST
callback on the peer client. If the call fails, the local client receives the EVT_SEND_RESULT
callback; check the error code and error information of the peer-to-peer message sent.
Notes
This method must be called by the host side (HOST
); otherwise, the method call does not take effect.
Parameter | Description |
---|---|
peer |
The user ID of the controlled side, that is, the userId of the controlled side used to log in to the RDC system. It cannot be empty, null , or "null" . |
Returns
0
: Success.0
: Failure. Check whether the parameter setting is empty.``Sample code
if (lpEngine) {
lpEngine->requestControl(peerId);
}
virtual int answerRequestControl(const char* peer, bool answer = true) = 0;
Responds to a control request from the specified user.
A successful call of this method triggers the EVT_CONTROL_REQUEST
callback on the peer client. If the call fails, the local client receives the EVT_SEND_RESULT
callback; check the error code and error information of the peer-to-peer message sent.
Notes
This method must be called by the controlled side (CONTROLLED
); otherwise, the method call does not take effect.
Parameter | Description |
---|---|
peer |
The user ID of the host side, that is, the userId of the host side used to log in to the RDC system. It cannot be empty, null , or "null" . |
answer |
In response to a control request from the specified user:true : Allows the specified user's control request.false : Denies the specified user's control request. |
Returns
0
: Success.0
: Failure. Check whether the parameter setting is empty.Sample code
if (lpEngine) {
lpEngine->answerRequestControl(peerId, true);
}
virtual int quitControl(const char* peer) = 0;
Requests to exit the remote control.
Both the host and the controlled side can call this method to request that the peer side exit the remote control. A successful call of this method triggers the EVT_CONTROL_QUIT
callback on the peer client.
Parameter | Description |
---|---|
peer |
The user ID of the peer, that is, the userId of the peer used to log in to the RDC system. It cannot be empty, null , or "null" . |
Returns
0
: Success.0
: Failure. Check whether the parameter setting is empty.Sample code
if (lpEngine) {
lpEngine->quitControl(peerId);
}
virtual int answerQuitControl(const char* peer, bool answer = true) = 0;
Responds to a request to exit the remote control from the specified user.
A successful call of this method triggers the EVT_CONTROL_QUIT
callback on the peer client.
Notes
When the controlled side calls quitControl
to request to quit the remote control process, the host side needs to call this method to respond.
When the host side calls quitControl
to request to quit the remote control process, the controlled side does not need to call this method.
Parameter | Description |
---|---|
peer |
The user ID of the peer, that is, the userId of the peer side used to log in to the RDC system. It cannot be empty, null , or "null" . |
answer |
In response to the peer user's request to exit the remote control:true : Allows the peer user's request to exit remote control.false : Denies the peer user's request to exit remote control. |
Returns
0
: Success.0
: Failure. Check whether the parameter setting is empty.``Sample code
if (lpEngine) {
lpEngine->answerQuitControl(peerId, true);
}
break;
virtual int requestRemoteInfo(const char* peer) = 0;
Gets the information of the peer user.
Parameter | Description |
---|---|
peer |
The user ID of the peer. |
virtual int remotePasteOp(bool isFile = false, const char* content = NULL) = 0;
The host side's computer pastes the local file or text to the target location of the host side's computer.
Parameter | Description |
---|---|
isFile |
Whether the content type to be pasted is a file or text:true : The content to be pasted is a file.false : (Default) The content to be pasted is text. |
content |
Content to be pasted.isFile istrue ), pass in the absolute path of the file.isFile isfalse ), pass in NULL ,and the SDK gets the file or text in the clipboard. |
Returns
0(ERR_OK)
: Success.0
: Failure. For error codes and error information, see File transfer error Codes.virtual void onEvent(RDC_EVENT event, int code, const char* msg) = 0;
The event handler of the Agora RDC SDK.
Parameter | Description |
---|---|
event |
Event name, see RDC_EVENT for details. |
code |
Error code, see RDC_EVENT for details. |
msg |
Error information, see RDC_EVENT for details. |
Sample code
class MyRDCEventHandler : public IRemoteControlEventHandler {
public:
void onEvent(RDC_EVENT event, int code, const char* msg) {
switch (event) {
case EVT_ERROR:
// processing logic
break;
case EVT_LOGIN:
// processing logic
break;
...
}
}
};