Core Methods and Callbacks
Introduces the core methods and corresponding callbacks in the Agora RTC SDK.
createAgoraRtcEngine
Creates the IRtcEngine object.
AGORA_API agora::rtc::IRtcEngine *AGORA_CALL createAgoraRtcEngine ()
Currently, the Agora RTC SDK v4.0.0 supports creating only one IRtcEngine object for an app.
Returns
Pointer to the IRtcEngine object.
getConnectionState
Gets the current connection state of the SDK.
virtual CONNECTION_STATE_TYPE getConnectionState() = 0;
You can call this method either before or after joining a channel.
Returns
The current connection state. For details, see CONNECTION_STATE_TYPE.
initialize
Initializes IRtcEngine.
virtual int initialize(const RtcEngineContext& context) = 0;
All called methods provided by the IRtcEngine class are executed asynchronously. Agora recommends calling these methods in the same thread.
- Before calling other APIs, you must call createAgoraRtcEngine and initialize to create and initialize the IRtcEngine object.
- The SDK supports creating only one IRtcEngine instance for an app.
Parameters
- context
-
Configurations for the IRtcEngine instance. See RtcEngineContext.
Returns
- 0: Success.
- < 0: Failure.
- -1: A general error occurs (no specified reason).
- -2: The parameter is invalid.
- -7: The SDK is not initialized.
- -22: The resource request failed. The SDK fails to allocate resources because your app consumes too much system resource or the system resources are insufficient.
- -101: The App ID is invalid.
joinChannel [1/2]
Joins a channel.
virtual int joinChannel(const char* token, const char* channelId, const char* info,
uid_t uid) = 0;
This method enables users to join a channel. Users in the same channel can talk to each other, and multiple users in the same channel can start a group chat. Users with different App IDs cannot call each other.
- The local client: The onJoinChannelSuccess and onConnectionStateChanged callbacks.
- The remote client: onUserJoined, if the user joining the channel is in the Communication profile or is a host in the Live-broadcasting profile.
When the connection between the client and Agora's server is interrupted due to poor network conditions, the SDK tries reconnecting to the server. When the local client successfully rejoins the channel, the SDK triggers the onRejoinChannelSuccess callback on the local client.
Parameters
- token
- The token generated on your server for authentication. See .
- channelId
-
The channel name. This parameter signifies the channel in which users engage in real-time audio and video interaction. Under the premise of the same App ID, users who fill in the same channel ID enter the same channel for audio and video interaction. The string length must be less than 64 bytes. Supported characters:
- All lowercase English letters: a to z.
- All uppercase English letters: A to Z.
- All numeric characters: 0 to 9.
- Space
- "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "= ", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","
- info
- (Optional) Reserved for future use.
- uid
- The user ID. This parameter is used to identify the user in the channel for real-time audio and video interaction. You need to set and manage user IDs yourself, and ensure that each user ID in the same channel is unique. This parameter is a 32-bit unsigned integer. The value range is 1 to 232-1. If the user ID is not assigned (or set to 0), the SDK assigns a random user ID and returns it in the onJoinChannelSuccess callback. Your application must record and maintain the returned user ID, because the SDK does not do so.
Returns
- 0: Success.
- < 0: Failure.
- -2: The parameter is invalid. For example, the token is invalid, the uid parameter is not set to an integer, or the value of a member in the ChannelMediaOptions structure is invalid. You need to pass in a valid parameter and join the channel again.
- -3: Failes to initialize the IRtcEngine object. You need to reinitialize the IRtcEngine object.
- -7: The IRtcEngine object has not been initialized. You need to initialize the IRtcEngine object before calling this method.
- -8: IRtcEngineThe internal state of the object is wrong. The typical cause is that you call this method to join the channel without calling stopEchoTest to stop the test after calling startEchoTest [2/3] to start a call loop test. You need to call stopEchoTest before calling this method.
- -17: The request to join the channel is rejected. The typical cause is that the user is in the channel. Agora recommends using the onConnectionStateChanged callback to get whether the user is in the channel. Do not call this method to join the channel unless you receive the CONNECTION_STATE_DISCONNECTED(1) state.
- -102: The channel name is invalid. You need to pass in a valid channel name inchannelId to rejoin the channel.
- -121: The user ID is invalid. You need to pass in a valid user ID in uid to rejoin the channel.
joinChannel [2/2]
Joins a channel with media options.
virtual int joinChannel(const char* token, const char* channelId, uid_t uid,
const ChannelMediaOptions& options) = 0;
This method enables users to join a channel. Users in the same channel can talk to each other, and multiple users in the same channel can start a group chat. Users with different App IDs cannot call each other.
- The local client: The onJoinChannelSuccess and onConnectionStateChanged callbacks.
- The remote client: onUserJoined, if the user joining the channel is in the Communication profile or is a host in the Live-broadcasting profile.
When the connection between the client and Agora's server is interrupted due to poor network conditions, the SDK tries reconnecting to the server. When the local client successfully rejoins the channel, the SDK triggers the onRejoinChannelSuccess callback on the local client.
Compared to joinChannel [1/2], this method adds the options parameter to configure whether to automatically subscribe to all remote audio and video streams in the channel when the user joins the channel. By default, the user subscribes to the audio and video streams of all the other users in the channel, giving rise to usage and billings. To unsubscribe, set the options parameter or call the mute methods accordingly.
- This method allows users to join only one channel at a time.
- Ensure that the app ID you use to generate the token is the same app ID that you pass in the initialize method; otherwise, you may fail to join the channel by token.
Parameters
- token
- The token generated on your server for authentication. See .
- channelId
-
The channel name. This parameter signifies the channel in which users engage in real-time audio and video interaction. Under the premise of the same App ID, users who fill in the same channel ID enter the same channel for audio and video interaction. The string length must be less than 64 bytes. Supported characters:
- All lowercase English letters: a to z.
- All uppercase English letters: A to Z.
- All numeric characters: 0 to 9.
- Space
- "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "= ", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","
- uid
- The user ID. This parameter is used to identify the user in the channel for real-time audio and video interaction. You need to set and manage user IDs yourself, and ensure that each user ID in the same channel is unique. This parameter is a 32-bit unsigned integer. The value range is 1 to 232-1. If the user ID is not assigned (or set to 0), the SDK assigns a random user ID and returns it in the onJoinChannelSuccess callback. Your application must record and maintain the returned user ID, because the SDK does not do so.
- options
- The channel media options. See ChannelMediaOptions.
Returns
- 0: Success.
- < 0: Failure.
- -2: The parameter is invalid. For example, the token is invalid, the uid parameter is not set to an integer, or the value of a member in the ChannelMediaOptions structure is invalid. You need to pass in a valid parameter and join the channel again.
- -3: Failes to initialize the IRtcEngine object. You need to reinitialize the IRtcEngine object.
- -7: The IRtcEngine object has not been initialized. You need to initialize the IRtcEngine object before calling this method.
- -8: IRtcEngineThe internal state of the object is wrong. The typical cause is that you call this method to join the channel without calling stopEchoTest to stop the test after calling startEchoTest [2/3] to start a call loop test. You need to call stopEchoTest before calling this method.
- -17: The request to join the channel is rejected. The typical cause is that the user is in the channel. Agora recommends using the onConnectionStateChanged callback to get whether the user is in the channel. Do not call this method to join the channel unless you receive the CONNECTION_STATE_DISCONNECTED(1) state.
- -102: The channel name is invalid. You need to pass in a valid channel name inchannelId to rejoin the channel.
- -121: The user ID is invalid. You need to pass in a valid user ID in uid to rejoin the channel.
joinChannelWithUserAccount [1/2]
Joins a channel with a User Account and Token.
virtual int joinChannelWithUserAccount(const char* token,
const char* channelId,
const char* userAccount) = 0;
- The local client: onLocalUserRegistered, onJoinChannelSuccess and onConnectionStateChanged callbacks.
- The remote client: onUserJoined and onUserInfoUpdated, if the user joining the channel is in the communication profile or is a host in the live streaming profile.
Once a user joins the channel, the user subscribes to the audio and video streams of all the other users in the channel by default, giving rise to usage and billing calculation. To stop subscribing to a specified stream or all remote streams, call the corresponding mute methods.
Parameters
- token
- The token generated on your server for authentication. See .
- channelId
-
The channel name. This parameter signifies the channel in which users engage in real-time audio and video interaction. Under the premise of the same App ID, users who fill in the same channel ID enter the same channel for audio and video interaction. The string length must be less than 64 bytes. Supported characters:
- All lowercase English letters: a to z.
- All uppercase English letters: A to Z.
- All numeric characters: 0 to 9.
- Space
- "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "= ", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","
- userAccount
-
The user account. This parameter is used to identify the user in the channel for real-time audio and video engagement. You need to set and manage user accounts yourself and ensure that each user account in the same channel is unique. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as NULL. Supported characters are (89 in total):
- The 26 lowercase English letters: a to z.
- The 26 uppercase English letters: A to Z.
- All numeric characters: 0 to 9.
- Space
- "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "= ", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","
Returns
- 0: Success.
- < 0: Failure.
- 2: The parameter is invalid.
- 3: The initialization of the SDK fails. You can try to initialize the SDK again.
- 5: The request is rejected.
- 17: The request to join the channel is rejected. Since the SDK only supports users to join one IRtcEngine channel at a time; this error code will be returned when the user who has joined the IRtcEngine channel calls the join channel method in the IRtcEngine class again with a valid channel name.
joinChannelWithUserAccount [2/2]
Joins the channel with a user account, and configures whether to automatically subscribe to audio or video streams after joining the channel.
virtual int joinChannelWithUserAccount(const char* token,
const char* channelId,
const char* userAccount,
const ChannelMediaOptions& options) = 0;
- The local client: onLocalUserRegistered, onJoinChannelSuccess and onConnectionStateChanged callbacks.
- The remote client: The onUserJoined callback if the user is in the COMMUNICATION profile, and the onUserInfoUpdated callback if the user is a host in the LIVE_BROADCASTING profile.
Once a user joins the channel, the user subscribes to the audio and video streams of all the other users in the channel by default, giving rise to usage and billing calculation. To stop subscribing to a specified stream or all remote streams, call the corresponding mute methods.
Compared to joinChannelWithUserAccount [1/2], this method adds the options parameter to configure whether to automatically subscribe to all remote audio and video streams in the channel when the user joins the channel. By default, the user subscribes to the audio and video streams of all the other users in the channel, giving rise to usage and billings. To unsubscribe, set the options parameter or call the mute methods accordingly.
Parameters
- token
- The token generated on your server for authentication. See .
- channelId
-
The channel name. This parameter signifies the channel in which users engage in real-time audio and video interaction. Under the premise of the same App ID, users who fill in the same channel ID enter the same channel for audio and video interaction. The string length must be less than 64 bytes. Supported characters:
- All lowercase English letters: a to z.
- All uppercase English letters: A to Z.
- All numeric characters: 0 to 9.
- Space
- "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "= ", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","
- userAccount
-
The user account. This parameter is used to identify the user in the channel for real-time audio and video engagement. You need to set and manage user accounts yourself and ensure that each user account in the same channel is unique. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as NULL. Supported characters are (89 in total):
- The 26 lowercase English letters: a to z.
- The 26 uppercase English letters: A to Z.
- All numeric characters: 0 to 9.
- Space
- "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "= ", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","
- options
- The channel media options. See ChannelMediaOptions.
Returns
- 0: Success.
- < 0: Failure.
- -2: The parameter is invalid. For example, the token is invalid, the uid parameter is not set to an integer, or the value of a member in the ChannelMediaOptions structure is invalid. You need to pass in a valid parameter and join the channel again.
- -3: Failes to initialize the IRtcEngine object. You need to reinitialize the IRtcEngine object.
- -7: The IRtcEngine object has not been initialized. You need to initialize the IRtcEngine object before calling this method.
- -8: IRtcEngineThe internal state of the object is wrong. The typical cause is that you call this method to join the channel without calling stopEchoTest to stop the test after calling startEchoTest [2/3] to start a call loop test. You need to call stopEchoTest before calling this method.
- -17: The request to join the channel is rejected. The typical cause is that the user is in the channel. Agora recommends using the onConnectionStateChanged callback to get whether the user is in the channel. Do not call this method to join the channel unless you receive the CONNECTION_STATE_DISCONNECTED(1) state.
- -102: The channel name is invalid. You need to pass in a valid channel name inchannelId to rejoin the channel.
- -121: The user ID is invalid. You need to pass in a valid user ID in uid to rejoin the channel.
leaveChannel [1/2]
Leaves a channel.
virtual int leaveChannel() = 0;
This method releases all resources related to the session.
This method call is asynchronous. When this method returns, it does not necessarily mean that the user has left the channel.
After joining the channel, you must call this method or leaveChannel [2/2] to end the call, otherwise, the next call cannot be started.
- The local client: onLeaveChannel.
- The remote client: onUserOffline, if the user joining the channel is in the Communication profile, or is a host in the Live-broadcasting profile.
- If you call release immediately after calling this method, the SDK does not trigger the onLeaveChannel callback.
- If you have called joinChannelEx to join multiple channels, calling this method will leave the channels when calling joinChannel [2/2] and joinChannelEx at the same time.
Returns
- 0: Success.
- < 0: Failure.
- -1: A general error occurs (no specified reason).
- -2: The parameter is invalid.
- -7: The SDK is not initialized.
leaveChannel [2/2]
Sets channel options and leaves the channel.
virtual int leaveChannel(const LeaveChannelOptions& options) = 0;
This method will release all resources related to the session, leave the channel, that is, hang up or exit the call. This method can be called whether or not a call is currently in progress.
After joining the channel, you must call this method or to end the call, otherwise, the next call cannot be started.
This method call is asynchronous. When this method returns, it does not necessarily mean that the user has left the channel. After actually leaving the channel, the local user triggers the onLeaveChannel callback; after the user in the communication scenario and the host in the live streaming scenario leave the channel, the remote user triggers the onUserOffline callback.
- If you call release immediately after calling this method, the SDK does not trigger the onLeaveChannel callback.
- If you have called joinChannelEx to join multiple channels, calling this method will leave the channels when calling joinChannel [2/2] and joinChannelEx at the same time.
Parameters
- options
- The options for leaving the channel. See LeaveChannelOptions.
Returns
- 0: Success.
- < 0: Failure.
release
Releases the IRtcEngine instance.
virtual void release(bool sync = false) = 0;
This method releases all resources used by the Agora SDK. Use this method for apps in which users occasionally make voice or video calls. When users do not make calls, you can free up resources for other operations.
After a successful method call, you can no longer use any method or callback in the SDK anymore. If you want to use the real-time communication functions again, you must call createAgoraRtcEngine and initialize to create a new IRtcEngine instance.
Parameters
- sync
-
Whether the method is called synchronously:
true
: Synchronous call. Agora suggests calling this method in a sub-thread to avoid congestion in the main thread because the synchronous call and the app cannot move on to another task until the resources used by IRtcEngine are released. Besides, you cannot call release in any method or callback of the SDK. Otherwise, the SDK cannot release the resources until the callbacks return results, which may result in a deadlock.false
: Asynchronous call. Currently this method only supports synchronous calls, do not set this parameter to this value.
renewToken
Gets a new token when the current token expires after a period of time.
virtual int renewToken(const char* token) = 0;
- The SDK triggers the onTokenPrivilegeWillExpire callback.
- The onConnectionStateChanged callback reports CONNECTION_CHANGED_TOKEN_EXPIRED(9).
Parameters
- token
- The new token.
Returns
- 0: Success.
- < 0: Failure.
- -2: The parameter is invalid. For example, the token is invalid. You need to fill in a valid parameter.
- -7: The IRtcEngine object has not been initialized. You need to initialize the IRtcEngine object before calling this method.
setChannelProfile
Sets the channel profile.
virtual int setChannelProfile(CHANNEL_PROFILE_TYPE profile) = 0;
After initializing the SDK, the default channel profile is the live streaming profile. You can call this method to set the usage scenario of Agora channel. The Agora SDK differentiates channel profiles and applies optimization algorithms accordingly. For example, it prioritizes smoothness and low latency for a video call and prioritizes video quality for interactive live video streaming.
- To ensure the quality of real-time communication, Agora recommends that all users in a channel use the same channel profile.
- This method must be called and set before joinChannel [2/2], and cannot be set again after joining the channel.
- The default audio route and video encoding bitrate are different in different channel profiles. For details, see setDefaultAudioRouteToSpeakerphone and setVideoEncoderConfiguration.
Parameters
- profile
-
The channel profile. See CHANNEL_PROFILE_TYPE.
Returns
- 0(ERR_OK): Success.
- < 0: Failure.
- -2(ERR_INVALID_ARGUMENT): The parameter is invalid.
- -7(ERR_NOT_INITIALIZED): The SDK is not initialized.
setClientRole [1/2]
Sets the client role.
virtual int setClientRole(CLIENT_ROLE_TYPE role) = 0;
You can call this method either before or after joining the channel to set the user role as audience or host.
If you call this method to set the user's role as the host before joining the channel and set the local video property through the setupLocalVideo method, the local video preview is automatically enabled when the user joins the channel.
- The local client: onClientRoleChanged.
- The remote client: onUserJoined or
onUserOffline(USER_OFFLINE_BECOME_AUDIENCE)
.
Parameters
- role
-
The user role. See CLIENT_ROLE_TYPE.
Returns
- 0: Success.
- < 0: Failure.
- -1: A general error occurs (no specified reason).
- -2: The parameter is invalid.
- -7: The SDK is not initialized.
setClientRole [2/2]
Sets the user role and level in an interactive live streaming channel.
virtual int setClientRole(CLIENT_ROLE_TYPE role, const ClientRoleOptions& options) = 0;
In the interactive live streaming profile, the SDK sets the user role as audience by default. You can call this method to set the user role as host.
You can call this method either before or after joining a channel.
If you call this method to set the user's role as the host before joining the channel and set the local video property through the setupLocalVideo method, the local video preview is automatically enabled when the user joins the channel.
- Calls muteLocalAudioStream and muteLocalVideoStream to change the publishing state.
- Triggers onClientRoleChanged on the local client.
- Triggers onUserJoined or onUserOffline on the remote client.
- The user role (role) determines the permissions that the SDK grants to a user, such as permission to send local streams, receive remote streams, and push streams to a CDN address.
- The user level (level) determines the level of services that a user can enjoy within the permissions of the user's role. For example, an audience member can choose to receive remote streams with low latency or ultra-low latency. User level affects the pricing of services.
Parameters
- role
- The user role in the interactive live streaming. See CLIENT_ROLE_TYPE.
- options
- The detailed options of a user, including the user level. See ClientRoleOptions.
Returns
- 0: Success.
- < 0: Failure.
- -1: A general error occurs (no specified reason).
- -2: The parameter is invalid.
- -5: The request is rejected.
- -7: The SDK is not initialized.
updateChannelMediaOptions
Updates the channel media options after joining the channel.
virtual int updateChannelMediaOptions(const ChannelMediaOptions& options) = 0;
Parameters
- options
- The channel media options. See ChannelMediaOptions.
Returns
- 0: Success.
- < 0: Failure.
- -2: The value of a member in the ChannelMediaOptions structure is invalid. For example, the token or the user ID is invalid. You need to fill in a valid parameter.
- -7: The IRtcEngine object has not been initialized. You need to initialize the IRtcEngine object before calling this method.
- -8: The internal state of the IRtcEngine object is wrong. The possible reason is that the user is not in the channel. Agora recommends using the onConnectionStateChanged callback to get whether the user is in the channel. If you receive the CONNECTION_STATE_DISCONNECTED (1) or CONNECTION_STATE_FAILED (5) state, the user is not in the channel. You need to call joinChannel [2/2] to join a channel before calling this method.
onClientRoleChanged
Occurs when the user role switches during the interactive live streaming.
virtual void onClientRoleChanged(CLIENT_ROLE_TYPE oldRole, CLIENT_ROLE_TYPE newRole, const ClientRoleOptions& newRoleOptions) { (void)oldRole; (void)newRole; (void)newRoleOptions; }
The SDK triggers this callback when the local user switches their user role by calling setClientRole [2/2] after joining the channel.
Parameters
- oldRole
- Role that the user switches from: CLIENT_ROLE_TYPE.
- newRole
- Role that the user switches to: CLIENT_ROLE_TYPE.
- newRoleOptions
-
- Since
- v4.1.0
Properties of the role that the user switches to. See ClientRoleOptions.
onClientRoleChangeFailed
Occurs when the user role switch fails in the interactive live streaming.
virtual void onClientRoleChangeFailed(CLIENT_ROLE_CHANGE_FAILED_REASON reason, CLIENT_ROLE_TYPE currentRole) { (void)reason; (void)currentRole; }
In the live broadcasting channel profile, when the local user calls setClientRole [1/2] to switch their user role after joining the channel but the switch fails, the SDK triggers this callback to report the reason for the failure and the current user role.
Parameters
- reason
- The reason for a user role switch failure. See CLIENT_ROLE_CHANGE_FAILED_REASON.
- currentRole
- Current user role. See CLIENT_ROLE_TYPE.
onError
Reports an error during SDK runtime.
virtual void onError(int err, const char* msg) { (void)err; (void)msg; }
This callback indicates that an error (concerning network or media) occurs during SDK runtime. In most cases, the SDK cannot fix the issue and resume running. The SDK requires the application to take action or informs the user about the issue.
Parameters
- err
- Error code. See ERROR_CODE_TYPE.
- msg
- The error message.
onJoinChannelSuccess
Occurs when a user joins a channel.
virtual void onJoinChannelSuccess(const char* channel, uid_t uid, int elapsed) { (void)channel; (void)uid; (void)elapsed; }
This callback notifies the application that a user joins a specified channel.
Parameters
- channel
- The channel name.
- uid
- The ID of the user who joins the channel.
- elapsed
- The time elapsed (ms) from the local user calling joinChannel [2/2] until the SDK triggers this callback.
onLeaveChannel
Occurs when a user leaves a channel.
virtual void onLeaveChannel(const RtcStats& stats) { (void)stats; }
This callback notifies the app that the user leaves the channel by calling leaveChannel [1/2] . From this callback, the app can get information such as the call duration and quality statistics.
Parameters
- stats
- The statistics of the call. See RtcStats.
onRejoinChannelSuccess
Occurs when a user rejoins the channel.
virtual void onRejoinChannelSuccess(const char* channel, uid_t uid, int elapsed) { (void)channel; (void)uid; (void)elapsed; }
When a user loses connection with the server because of network problems, the SDK automatically tries to reconnect and triggers this callback upon reconnection.
Parameters
- channel
- The channel name.
- uid
- The ID of the user who rejoins the channel.
- elapsed
- Time elapsed (ms) from the local user calling the joinChannel [1/2] or joinChannel [2/2] method until this callback is triggered.
onRequestToken
Occurs when the token expires.
virtual void onRequestToken()
When the token expires during a call, the SDK triggers this callback to remind the app to renew the token.
Once you receive this callback, generate a new token on your app server, and call joinChannel [2/2] to rejoin the channel.
Parameters
onRtcStats
Reports the statistics of the current call.
virtual void onRtcStats(const RtcStats& stats) { (void)stats; }
The SDK triggers this callback once every two seconds after the user joins the channel.
Parameters
- stats
-
Statistics of the RTC engine. See RtcStats.
onTokenPrivilegeWillExpire
Occurs when the token expires in 30 seconds.
virtual void onTokenPrivilegeWillExpire(const char* token) { (void)token; }
When the token is about to expire in 30 seconds, the SDK triggers this callback to remind the app to renew the token.
Upon receiving this callback, generate a new token on your server, and call renewToken to pass the new token to the SDK.
Parameters
- token
- The token that expires in 30 seconds.
onUserInfoUpdated
Occurs when the SDK gets the user ID and user account of the remote user.
virtual void onUserInfoUpdated(uid_t uid, const UserInfo& info) { (void)uid; (void)info; }
After a remote user joins the channel, the SDK gets the UID and user account of the remote user, caches them in a mapping table object, and triggers this callback on the local client.
Parameters
- uid
- The user ID of the remote user.
- info
- The UserInfo object that contains the user ID and user account of the remote user. See UserInfo for details.
onUserJoined
Occurs when a remote user (COMMUNICATION)/ host (LIVE_BROADCASTING) joins the channel.
virtual void onUserJoined(uid_t uid, int elapsed) { (void)uid; (void)elapsed; }
- In a communication channel, this callback indicates that a remote user joins the channel. The SDK also triggers this callback to report the existing users in the channel when a user joins the channel.
- In a live-broadcast channel, this callback indicates that a host joins the channel. The SDK also triggers this callback to report the existing hosts in the channel when a host joins the channel. Agora recommends limiting the number of hosts to 17.
- A remote user/host joins the channel by calling the joinChannel [2/2] method.
- A remote user switches the user role to the host after joining the channel.
- A remote user/host rejoins the channel after a network interruption.
Parameters
- uid
- The ID of the user or host who joins the channel.
- elapsed
- Time delay (ms) from the local user calling joinChannel [2/2] until this callback is triggered.
onUserOffline
Occurs when a remote user (in the communication profile)/ host (in the live streaming profile) leaves the channel.
virtual void onUserOffline(uid_t uid, USER_OFFLINE_REASON_TYPE reason) { (void)uid; (void)reason; }
- Leave the channel: When a user/host leaves the channel, the user/host sends a goodbye message. When this message is received, the SDK determines that the user/host leaves the channel.
- Drop offline: When no data packet of the user or host is received for a certain period of time (20 seconds for the communication profile, and more for the live broadcast profile), the SDK assumes that the user/host drops offline. A poor network connection may lead to false detections. It's recommended to use the Agora RTM SDK for reliable offline detection.
Parameters
- uid
- The ID of the user who leaves the channel or goes offline.
- reason
-
Reasons why the user goes offline: USER_OFFLINE_REASON_TYPE.