This document is provided for the C++ language with the following classes:

Depending on the native platform, before calling any methods listed in this document, first call the following:

  • Android: Call create to create an RtcEngine Object.
  • iOS: Call sharedEngineWithAppId to initialize.

IRtcEngineForGaming Interface Class

Set the Channel Profile (setChannelProfile)

virtual int setChannelProfile (CHANNEL_PROFILE_TYPE profile);

This method configures the channel profile. The Agora RTCEngine needs to know what scenario the application is in to apply different methods for optimization.

  • Use one profile at the same time in the same channel.
  • This method must be called and configured before a user joins a channel because the channel profile cannot be configured when the channel is in use.
Name Description
profile

Channel profile. Choose from the following:

  • CHANNEL_PROFILE _GAME_FREEMODE=2: Free Mode
  • CHANNEL_PROFILE _GAME_COMMANDMODE=3: Command Mode
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Set the User Role (setClientRole)

virtual int setClientRole(CLIENT_ROLE_TYPE role);

This method allows you to set the user role.

This method is only applicable when the channel profile is set as the command mode when calling setChannelProfile.

Name Description
role

User role in a command-mode channel:

  • CLIENT_ROLE_BROADCASTER = 1; Host
  • CLIENT_ROLE_AUDIENCE = 2; Audience (default)

Once set, only the host in the channel can talk, not the audience.

Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Join a Channel (JoinChannel)

virtual int joinChannel(const char* token, const char* channelName, const char* optionalInfo, uid_t optionalUid);

This method allows a user 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 using different App IDs cannot call each other. Once in a call, the user must call the leaveChannel method to exit the current call before entering another channel.

A channel does not accept duplicate UIDs, such as two users with the same UID. If your app supports logging in a user from different devices at the same time, ensure that you use different UIDs. For example, if you already used the same UID, make the UIDs different by adding the respective device ID to the UID. This is not applicable if your app does not support a user logging in from different devices at the same time. In this case, when you log in a new device, you will be logged out from the other device.

Name Description
token

A Token generated by the application.

This parameter is optional if the user uses a static App ID. In this case, pass NULL as the parameter value.

If the user uses a Token, Agora issues an additional App Certificate to the application developers. The developers can then generate a user key using the algorithm and App Certificate provided by Agora for user authentication on the server.

In most circumstances, the static App ID will suffice. For added security, use a Token.

channelName

A string providing the unique channel name for the AgoraRTC session. The length must be within 64 bytes.

The following is the supported scope: a-z, A-Z, 0-9, space, !

#$%&, ()+,

-, :;<=., >?

@[], ^_, {|}, ~

optionalInfo (Optional) Additional information about the channel. Other users in the channel will not receive this information.
optionalUid

(Optional) User ID: A 32-bit unsigned integer ranging from 1 to (2^32-1). It must be unique. If not assigned (or set to 0), the SDK will assign one and return it in the onJoinChannelSuccess callback. The app needs to record and maintain the returned value as the SDK does not maintain it.

The UID is represented as a 32-bit unsigned integer in the SDK. Since unsigned integers are not supported by Java, the UID is handled as a 32-bit signed integer and larger numbers are interpreted as negative numbers in Java. If necessary, the UID can be converted to a 64-bit integer through “uid&0xffffffffL”.

Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.
    • ERR_INVALID_ARGUMENT (-2): The passed argument is invalid.
    • ERR_NOT_READY (-3): Initialization failed.

Leave a Channel (leaveChannel)

virtual int leaveChannel ();

This method allows the user to leave a channel (hang up or exit a call). After joining a channel, the user must call the leaveChannel method to end the call before joining another one. It returns 0 if the user has successfully left the channel. The leaveChannel method releases all resources related to the call.

The leaveChannel method is called asynchronously, and the user does not exit the channel when the call returns. Once the user exits the channel, the SDK triggers the onLeaveChannel callback.

Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.
    • ERR_REFUSED (-5): Failed to leave the channel (the user is not currently in a call or is in the process of leaving the channel).

Enable the Audio Mode (enableAudio)

virtual int enableAudio();

This method enables the audio mode. This function is enabled by default.

Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Disable the Audio Mode (disableAudio)

virtual int disableAudio();

This method disables the audio mode.

Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Mute the Local Audio Stream (muteLocalAudioStream)

virtual int muteLocalAudioStream(bool mute);

This method mutes/unmutes the local audio. It enables/disables sending the local audio stream to the network.

This method does not disable the microphone, and thus does not affect any recording.

Name Description
mute
  • True: Mutes the local audio.
  • False: Unmutes the local audio.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Mute all Remote Audio Streams (muteAllRemoteAudioStreams)

int muteAllRemoteAudioStreams(bool mute);

This method mutes/unmutes all remote users’ audio streams

When set to True, this method mutes audio streams without affecting the audio stream receiving process.

Name Description
mute
  • True: Mutes all received audio streams.
  • False: Unmutes all received audio streams.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Mute a Remote Audio Streams (muteRemoteAudioStream)

virtual int muteRemoteAudioStream(uid_t uid, bool mute);

This method mutes/unmutes a specified user’s audio stream.

When set to True, this method mutes the audio stream without affecting the audio stream receiving process.

Name Description
uid User ID of the user whose audio stream is to be muted.
mute
  • True: Mutes the user’s audio streams.
  • False: Unmutes the user’s audio streams.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Enable the Audio Volume Indication (enableAudioVolumeIndication)

int enableAudioVolumeIndication (int interval, int smooth);

This method enables the SDK to regularly report to the application on which user is talking and the volume of the speaker.

Name Description
interval

Time interval between two consecutive volume indications.

  • <=0: Disables the volume indication.
  • >0: Volume indication interval (ms). Recommended to set it to a minimum of 200 ms.
smooth Smoothing factor. Recommended default value is 3.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Get the SDK Version (getVersion)

virtual const char* getVersion(int* build);

This method returns the string of the version number in character format.

Name Description
build The build number.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Set a Log File (setLogFile)

virtual int setLogFile(const char* filePath);

This method specifies an SDK output log file. The log file records all the log data of the SDK’s operation. Ensure that the directory to save the log file exists and is writable.

Name Description
filePath The file path of the log file. The string of the log file is in UTF-8 code.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Set a Log Filter (setLogFilter)

virtual int setLogFilter(unsigned int filter);

This method sets the SDK output log filter. You can use either one or a combination of the filters.

Name Description
filter

Set the levels of the filters:

  • LOG_FILTER_OFF = 0;
  • LOG_FILTER_CRITICAL = 0x0008;
  • LOG_FILTER_ERROR = 0x000c;
  • LOG_FILTER_WARN = 0x000e;
  • LOG_FILTER_INFO = 0x000f;
  • LOG_FILTER_CRITICAL = 0x080f;
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Renew token (renewToken)

virtual int renewToken(const char* token);

This method updates the Token.

The token expires after a certain period of time once the Token schema is enabled when:

  • The onError callback reports the ERR_TOKEN_EXPIRED(109) error, or

  • The onRequestToken callback reports the ERR_TOKEN_EXPIRED(109) error, or

  • The user receives the onTokenPrivilegeWillExpire callback.

The application should retrieve a new token and then call this method to renew it. Failure to do so will result in the SDK disconnecting from the server.

Name Description
token Specifies the Token to be renewed.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Adjust the Recording Volume (adjustRecordingSignalVolume)

virtual int adjustRecordingSignalVolume(int volume);

This method adjusts the recording volume.

Name Description
volume

Recording volume, ranging from 0 to 400:

  • 0: Mute
  • 100: Original volume
  • 400: (Maximum) Four times the original volume with heap overflow protection
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Adjust the Playback Volume (adjustPlaybackSignalVolume)

virtual int adjustPlaybackSignalVolume(int volume);

This method adjusts the playback volume.

Name Description
volume

Playback volume, ranging from 0 to 400:

  • 0: Mute
  • 100: Original volume
  • 400: (Maximum) Four times the original volume with heap overflow protection
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Start Audio Mixing (startAudioMixing)

virtual int startAudioMixing(const char* filePath,
                                                                                                                             bool loopback,
                                                                                                                             bool replace,
                                                                                                                             int cycle,
                                                                                                                             int playTime);

This method mixes the specified local audio file with the audio stream from the microphone; or, it replaces the microphone’s audio stream with the specified local audio file. You can choose whether the other user can hear the local audio playback and specify the number of loop playbacks. This API also supports online music playback.

Call this API when you are in the channel, otherwise it may cause issues.

Name Description
filePath

Name and path of the local audio file to be mixed.

Supported audio formats: mp3, aac, m4a, 3gp, wav, and flac.

loopback
  • True: Only the local user can hear the remix or the replaced audio stream.
  • False: Both users can hear the remix or the replaced audio stream.
replace
  • True: The content of the local audio file replaces the audio stream from the microphone.
  • False: Mix the content of the local audio file with the audio stream from the microphone.
cycle

Number of loop playbacks:

  • Positive integer: Number of loop playbacks.
  • -1: Infinite loop.
playTime

Start time (ms) of the audio file to play.

0 means from the beginning.

Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Stop Audio Mixing (stopAudioMixing)

virtual int stopAudioMixing()

This method stops audio mixing. Call this API when you are in the channel.

Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Pause Audio Mixing (pauseAudioMixing)

virtual int pauseAudioMixing()

This method pauses mixing the specified local audio with the microphone input. Call this API when you are in the channel.

Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Resume Audio Mixing (resumeAudioMixing)

virtual int resumeAudioMixing()

This method resumes mixing the specified local audio with the microphone input. Call this API when you are in the channel.

Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Adjust Audio Mixing Volume (adjustAudioMixingVolume)

virtual int adjustAudioMixingVolume(int volume)

This method adjusts the volume during the audio mixing. Call this API when you are in the channel.

Name Description
volume Volume ranging from 0 to 100. By default, 100 is the original volume.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Get the Audio Mixing Duration (getAudioMixingDuration)

virtual int getAudioMixingDuration();

This method gets the duration (ms) of the audio mixing. Call this API when you are in the channel.

Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Get the Current Audio Position (getAudioMixingCurrentPosition)

virtual int getAudioMixingCurrentPosition();

This method gets the playback position (ms) of the audio. Call this API when you are in the channel.

Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Start an Audio Recording (startAudioRecording)

virtual int startAudioRecording (const char* filePath);

This method starts an audio recording. The SDK allows recording during a call, which supports either one of the following two formats:

  • .wav: Large file size with high sound fidelity OR

  • .aac: Small file size with low sound fidelity

Ensure that the directory to save the recording file exists and is writable. This method is usually called after joining a channel. The recording automatically stops when the leaveChannel method is called.

Name Description
filePath The full file path of the recording file. The string of the file name is UTF-8 code.
Return Value
  • 0: Method call succeeded
  • <0: Method call failed

Stop an Audio Recording (stopAudioRecording)

virtual int stopAudioRecording ();

This method stops recording on the client.

Call this method before calling leaveChannel, otherwise the recording automatically stops when the leaveChannel method is called.

Name Description
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Set the Customized Callback (setEventHandler)

virtual void setEventHandler(IGamingRtcEngineEventHandler* handler);

This method sets the customized callback for the SDK after the SDK is initialized.

Get the Audio Effect Manager (getAudioEffectManager)

virtual IAudioEffectManager* getAudioEffectManager();

This method gets the IAudioEffectManager object associated with the current RtcEngine.

Trigger an SDK Event (poll)

virtual int poll();

This method triggers an SDK event according to vertical synchronization, such as onUpdate(Cocos2d).

IAudioEffectManager Interface Class

Set to Voice-only Mode (setVoiceOnlyMode)

virtual int setVoiceOnlyMode(bool enable);

This method sets to voice-only mode (transmit the audio stream only), and the other streams will be ignored; for example the sound of the keyboard strokes.

Name Description
enable

True: Enables voice-only mode.

False: Disables voice-only mode.

Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Set the Voice Position of the Remote User (setRemoteVoicePosition)

virtual int setRemoteVoicePosition(uid_t uid, double pan, double gain);

Sets the voice position of the remote user.

This API is valid only for earphones, and is invalid when the speakerphone is enabled.

Name Description
uid User ID of the remote user.
pan

Sets whether to change the spatial position of the audio effect. The range is [-1, 1]:

  • 0: The audio effect shows right ahead.
  • -1: The audio effect shows on the left.
  • 1: The audio effect shows on the right.
gain

Sets whether to change the volume of a single audio effect. The range is [0.0, 100.0].

The default value is 100.0. The smaller the value, the lower the volume.

Set the Local Voice Pitch (setLocalVoicePitch)

int SetLocalVoicePitch (double pitch);

This method changes the voice pitch of the local speaker.

Name Description
uid User ID of the remote user.
pitch Voice frequency in the range of [0.5, 2.0]. The default value is 1.0.
Return Value
  • 0: Method call succeeded.
  • <0: Method call failed.

Get the Audio Effect Volume (getEffectsVolume)

virtual double getEffectsVolume();

This method gets the volume of the audio effects from 0.0 to 1.0.

Set the Audio Effect Volume (setEffectsVolume)

virtual int setEffectsVolume(double volume);

This method sets the volume of the audio effects.

Name Description
volume The value ranges from 0.0 to 100.0. 100.0 is the default value.

Play the Audio Effect (playEffect)

virtual int playEffect (int soundId,
                        const char* filePath,
                        bool loop,
                        double pitch,
                        double pan,
                        double gain);

This method plays the audio effect.

Name Description
soundId ID of the audio effect. Each audio effect has a unique ID. [1]
filePath Absolute path of the audio effect file.
loop

Sets whether to play the audio effect in loops:

  • True: Yes, it will be played in loops
  • False: No (default)
pitch

Sets whether to change the volume of the audio effect.

The range is [0.5, 2] with 1.0 as the default value, which means no need to change the volume.

The smaller the value, the lower the volume.

pan

Sets whether to change the spatial position of the audio effect. The range is [-1, 1]:

  • 0: The audio effect shows right ahead.
  • -1: The audio effect shows on the left.
  • 1: The audio effect shows on the right.
gain

Sets whether to change the volume of a single audio effect. The range is [0.0, 100.0].

The default value is 100.0. The smaller the value, the lower the volume.

[1] If the audio effect is loaded into the memory through preloadEffect, ensure that the soundId set is the same as in preloadEffect.

Stop Playing the Audio Effect (stopEffect)

virtual int stopEffect(int soundId);

This method stops playing a specific audio effect.

Name Description
soundId ID of the audio effect. Each audio effect has a unique ID.

Stop Playing all Audio Effects (stopAllEffects)

virtual int stopAllEffects();

This method stops playing all the audio effects.

Preload an Audio Effect (preloadEffect)

virtual int preloadEffect(int soundId, const char* filePath);

This method preloads a specific audio effect file (a compressed audio file) to the memory.

Name Description
soundId ID of the audio effect. Each audio effect has a unique ID.
filePath Absolute path of the audio effect file.

Release the Audio Effect (unloadEffect)

virtual int unloadEffect(int soundId);

This method releases the specific preloaded audio effect from the memory.

Name Description
soundId ID of the audio effect. Each audio effect has a unique ID.

Pause the Audio Effect (pauseEffect)

virtual int pauseEffect(int soundId);

This method pauses the specific audio effect.

Name Description
soundId ID of the audio effect. Each audio effect has a unique ID.

Pause all Audio Effects (pauseAllEffects)

virtual int pauseAllEffects();

This method pauses all the audio effects.

Resume the Audio Effect (resumeEffect)

virtual int resumeEffect(int soundId);

This method resumes playing a specific audio effect.

Name Description
soundId ID of the audio effect. Each audio effect has a unique ID.

Resume all Audio Effects (resumeAllEffects)

virtual int resumeAllEffects();

This method resumes all the audio effects.

IGamingRtcEngineEventHandler Interface Class

Join Channel Callback (onJoinChannelSuccess)

virtual void onJoinChannelSuccess (const char* channel, uid_t uid, int elapsed);

This callback indicates that the user has successfully joined the specified channel.

Name Description
channel Channel name.
uid

User ID.

If the uid is specified in the joinChannel method, it returns the specified ID; if not, it returns an ID that is automatically assigned by the Agora server.

elapsed Time elapsed (ms) from calling joinChannel until this event occurs.

Rejoin Channel Callback (onRejoinChannelSuccess)

virtual void onRejoinChannelSuccess(const char* channel, uid_t uid, int elapsed);

When the client loses connection with the server because of network problems, the SDK automatically attempts to reconnect, and then triggers this callback method upon reconnection.

Name Description
channel Channel name.
uid User ID.
elapsed Time elapsed (ms) from calling joinChannel until this event occurs.

Warning Occurred Callback (onWarning)

virtual void onWarning(int warn, const char* msg);

This callback method indicates that some warning occurred during SDK runtime. In most cases, the application can ignore the warnings reported by the SDK, because the SDK can usually fix the issue and resume running. For instance, the SDK may report an ERR_OPEN_CHANNEL_TIMEOUT warning upon disconnection with the server and attempts to reconnect.

For detailed warning codes, see Error Codes and Warning Codes.

Name Description
warn The warning code.
msg The warning message.

Error Occurred Callback (onError)

virtual void onError(int err, const char* msg);

This callback indicates that a network or media error occurred during the SDK runtime.

In most cases, reporting an error means that the SDK cannot fix the issue and resume running, and therefore requires actions from the application or simply informs the user on the issue. For instance, the SDK reports an ERR_START_CALL error when failing to initialize a call. In this case, the application informs the user that the call initialization failed, and calls the leaveChannel method to exit the channel.

For detailed error codes, see Error Codes and Warning Codes.

Name Description
err The error code.
msg The error message.

Audio Quality Callback (onAudioQuality)

virtual void onAudioQuality(uid_t uid, int quality, unsigned short delay, unsigned short lost);

During a call, this callback is triggered once every two seconds to report on the audio quality of the current call.

Name Description
uid User ID of the speaker.
quality

Rating of the audio quality:

  • QUALITY_EXCELLENT(1)
  • QUALITY_GOOD(2)
  • QUALITY_POOR(3)
  • QUALITY_BAD(4)
  • QUALITY_VBAD(5)
delay Time delay (ms).
lost Packet loss rate.

Audio Volume Indication Callback (onAudioVolumeIndication)

virtual void onAudioVolumeIndication (const AudioVolumeInfo* speakers, unsigned int speakerNumber, int totalVolume);

This callback indicates who is talking and the speaker’s volume. By default the indication is disabled. If needed, use the enableAudioVolumeIndication method to configure it.

Name Description
speakers

The speakers (array). Each speaker ():

  • uid: User ID of the speaker.
  • volume: Volume of the speaker between 0 (lowest volume) to 255 (highest volume).
speakerNumber Total number of speakers.
totalVolume Total volume after audio mixing between 0 (lowest volume) to 255 (highest volume).

Leave Channel Callback (onLeaveChannel)

virtual void onLeaveChannel(const RtcStats& stat);

When the application calls the leaveChannel method, the SDK uses this callback to notify the application that the user has successfully left the channel. With this callback function, the application retrieves information such as the call duration and the statistics of the data received/transmitted by the SDK.

Name Description
stat

Statistics about the call.

  • duration: Call duration (s).
  • txBytes: Total number of bytes transmitted.
  • rxBytes: Total number of bytes received.
  • txKBitRate: Transmission bitrate (kbit/s).
  • rxKBitRate: Receive bitrate (kbit/s).
struct RtcStats {
                unsigned int duration;
                unsigned int txBytes;
                unsigned int rxBytes;
                unsigned short txKBitRate;
                unsigned short rxKBitRate;
        };

Audio Mixing Playback Finished (onAudioMixingFinished)

virtual void onAudioMixingFinished();

Channel Network Quality Callback (onNetworkQuality)

virtual void onNetworkQuality(uid_t uid, int txQuality, int rxQuality);

This callback is triggered every 2 seconds to update the application on the network quality in a communication or live broadcast channel.

Name Description
uid

User ID. It reports on the network quality of the user with this UID.

If uid is 0, it reports the local network quality.

txQuality

The transmission quality of the user:

  • QUALITY_EXCELLENT(1)
  • QUALITY_GOOD(2)
  • QUALITY_POOR(3)
  • QUALITY_BAD(4)
  • QUALITY_VBAD(5)
  • QUALITY_DOWN(6)
rxQuality

The receiving quality of the user:

  • QUALITY_EXCELLENT(1)
  • QUALITY_GOOD(2)
  • QUALITY_POOR(3)
  • QUALITY_BAD(4)
  • QUALITY_VBAD(5)
  • QUALITY_DOWN(6)

Other User Joined Channel Callback (onUserJoined)

virtual void onUserJoined(uid_t uid, int elapsed);

This callback method notifies the application that another user has joined the channel. If there are other users in the channel when that user joins, the SDK also reports to the application on the existing users who are already in the channel.

Only the hosts will receive this callback, not the audience, after you set the user role by calling setClientRole.

Name Description
uid User ID.
elapsed Time delay (ms) from calling joinChannel until this callback is triggered.

Other User Offline Callback (onUserOffline)

virtual void onUserOffline(uid_t uid, USER_OFFLINE_REASON_TYPE reason);

This callback notifies the application that a user has left the channel or gone offline.

The SDK reads the timeout data to determine if a user has left the channel (or has gone offline). If no data package is received from the user in 15 seconds, the SDK assumes the user is offline. Sometimes a weak network connection may lead to false detections; therefore, it is recommend to use signaling for reliable offline detection.

Name Description
uid User ID.
reason

This callback is triggered when:

  • USER_OFFLINE_QUIT: A user has quit the call.
  • USER_OFFLINE_DROPPED: The SDK timed out and has dropped offline because it has not received a data package within a certain period of time. If a user quits the call and the message is not passed to the SDK (due to an unreliable channel), the SDK assumes the event has timed out.

Other User Muted Audio Callback (onUserMuteAudio)

virtual void onUserMuteAudio(uid_t uid, bool muted);

This callback indicates that some other user has muted/unmuted his/her audio streams.

Name Description
uid User ID of the remote user.
muted
  • True: The remote user has muted his/her audio.
  • False: The remote user has unmuted his/her audio.

Audio Route Changed Callback (onAudioRouteChanged)

virtual void onAudioRouteChanged(AUDIO_ROUTE_TYPE routing);

The SDK notifies the application that the audio route has switched to an earpiece, speakerphone, headset, or bluetooth device.

API Call Executed (onApiCallExecuted)

virtual void onApiCallExecuted(const char* api, int error);
Name Description
api The API name.
error
  • 0: The API is executed successfully.
  • <0: Failed to execute the API.

Connection Lost Callback (onConnectionLost)

virtual void onConnectionLost();

When the connection between the SDK and server is lost, the onConnectionInterrupted callback is triggered and the SDK reconnects automatically. If reconnection fails within a certain period or time (10 seconds by default), the callback onConnectionLost is triggered.The SDK continues to reconnect until the application calls leaveChannel.

Connection Interrupted Callback (rtcEngineConnectionDidInterrupted)

virtual void onConnectionInterrupted ();

This callback indicates that the connection is lost between the SDK and the server. Once the connection is lost, the SDK tries to reconnect it repeatedly until the application calls leaveChannel.

Data Stream Received Callback (onStreamMessage)

virtual void onStreamMessage(uid_t uid, int streamID, const char* data, size_t length);

This callback indicates the local user has received the data stream from the other user within five seconds.

Name Description
uid User ID of the remote user who sends the message.
data Message data received by the recipients.
length Message length in bytes (frame rate)

Data Stream Sent Failure Callback (onStreamMessageError)

virtual void onStreamMessageError(uid_t uid, int streamId, int code, int missed, int cached);

This callback indicates that the local user has not received the data stream from the other user within five seconds.

Name Description
uid User ID
streamId Stream ID
code

ERR_OK = 0, No error

For error code descriptions, see Error Codes and Warning Codes

missed Number of lost messages
cached Number of incoming cached messages when the data stream is interrupted

Token Expired Callback (onRequestToken)

virtual void onRequestToken();

When a Token is specified by calling joinChannel, if the SDK lost connection with the Agora server due to network issues, the Token may expire after a certain period of time and a new Token may be required to reconnect to the server.

This callback notifies the application the need to generate a new Token, and calls renewToken to renew the Token.

This function was previously provided when the callback reported onError(): ERR_TOKEN_EXPIRED(109), ERR_INVALID_TOKEN(110). Starting from v1.7.3, the old method still works, but it is recommended to use this callback.

Client Role Changed Callback (onClientRoleChanged)

virtual void onClientRoleChanged(CLIENT_ROLE_TYPE oldRole,CLIENT_ROLE_TYPE newRole)

When you set the channel profile as Live Broadcast when calling setChannelProfile,this callback is triggered when there is any role change in the channel.

Name Description
oldRole The role that you switched from
newRole The role that you are now in
enum CLIENT_ROLE_TYPE
{
    CLIENT_ROLE_BROADCASTER = 1,
    CLIENT_ROLE_AUDIENCE = 2,
};

User Video Muted Callback (OnUserMuteVideo)

virtual void OnUserMuteVideo (uint uid, bool muted);

This callback indicates that some other user has paused/resumed his/her video streams.

Currently, this callback returns invalid when the number of users in a channel exceeds 20, which will be improved in the future.

Name Description
uid User ID.
muted
  • True: The remote user mute the video
  • False: The remote user unmute the video

Error Codes

See Error Codes and Warning Codes.