agora::rtc::IRtcEngineHandler Interface Class

The SDK uses the agora::rtc::IEventHandler interface class to send callback event notifications to the application, and the application inherits the methods of this interface class to retrieve these event notifications. All methods in this interface class have their (empty) default implementations, and the application can inherit only some of the required events instead of all of them. In the callback methods, the application should avoid time-consuming tasks or calling blocking APIs, for example, SendMessage, otherwise the SDK may not work properly.

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.

Rejoin Channel Callback (onRejoinChannelSuccess)

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

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

Warning Occurred Callback (onWarning)

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

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

Error Occurred Callback (onError)

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

This callback indicates that a network or media error occurred during the runtime of the SDK. 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 failed to initialize a call. In this case, the application informs the user that the call initialization failed and in the same time it also calls the leaveChannel method to exit the channel.

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 2 seconds to report on the audio quality of the current call.

Audio Volume Indication Callback (onAudioVolumeIndication)

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

This callback indicates who is speaking and the speaker’s volume.

By default the indication is disabled. If needed, use the enableAudioVolumeIndication() method to configure it.

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 data received/transmitted by the SDK.

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.

Note: This callback method is valid only when the channel profile is set to free-talk mode.

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.

Note: The SDK reads the timeout data to determine if a user has left the channel (or has gone offline) or not. If no data package is received from the user in 15 seconds, the SDK takes it as the user being offline. Sometimes a weak network connection may lead to false detection, therefore we recommend using signaling for reliable offline detection.

Note: This callback method is valid only when the channel profile is set to free-talk mode.

Call Session Statistics Callback (onRtcStats)

virtual void onRtcStats(const RtcStats& stat)

The SDK updates the application on the statistics of the current call session once every 2 seconds.

Local Video Statistics Callback (onLocalVideoStat)

virtual void onLocalVideoStat(const LocalVideoStats& stats)

The SDK updates the application on the statistics about uploading local video streams once every 2 seconds. The definition of LocalVideoStats is listed as follows：

struct LocalVideoStats {

int sentBitrate;

int sentFrameRate;

};

Remote Video Statistics Callback (onRemoteVideoStat)

virtual void onRemoteVideoStat(const RemoteVideoStats& stats)

The SDK updates the application on the statistics about receiving remote video streams once every 2 seconds. The definition of RemoteVideoStats is listed as follows:

struct RemoteVideoStats {

uid_t uid;

int delay;

int width;

int height;

int receivedBitrate;

int receivedFrameRate;

};

First Local Video Frame Received and Displayed Callback (onFirstLocalVideoFrame)

virtual void onFirstLocalVideoFrame(int width, int height, int elapsed)

This callback is triggered when the first local video frame is displayed on the video window.

Frist Remote Video Frame Received and Decoded Callback (onFirstRemoteVideoDecoded)

virtual void onFirstRemoteVideoDecoded(uid_t uid, int width, int height, int elapsed)

This callback is triggered upon receiving and successfully decoding the first frame of the remote video. The application can configure the user view settings in this callback.

First Remote Video Frame Received and Displayed Callback (onFirstRemoteVideoFrame)

virtual void onFirstRemoteVideoFrame(uid_t uid, int width, int height, int elapsed, int elapsed)

This method is triggered upon displaying the first frame of the remote video on the user’s video window. The application can retrieve the data of time elapsed from user joining the channel until the first video frame is displayed.

Audio Device State Changed Callback (onAudioDeviceStateChanged)

virtual void onAudioDeviceStateChanged(const char* deviceId, int deviceType, int deviceState)

This callback notifies the application that the system’s audio device state has been changed, for example, a headset is unplugged from the device.

Network Quality Callback (onNetworkQuality)

virtual void onNetworkQuality(int quality)

This callback reports on network quality. It is triggered once every 2 seconds during a call. When not in a call and the network test is enabled (by calling enableNetworkTest), this callback function is triggered irregularly to update the application on the current network connection quality.

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.

Note: This callback method is valid only when the channel profile is set to free-talk mode.

Other User Paused/Resumed Video Callback (onUserMuteVideo)

virtual void onUserMuteVideo(uid_t uid, bool muted)

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

Note: This callback method is valid only when the channel profile is set to free-talk mode.

Other User Enabled/Disabled Video Callback(onUserEnableVideo)

virtual void onUserEnableVideo(uid_t uid, bool enabled)

This callback indicates that other users enabled/disabled the video function. Once the video function is disabled, the users cannot see any video from themselves or from other users.

Camera Ready Callback (onCameraReady)

virtual void onCameraReady()

This callback indicates that the camera is opened and ready to capture video. If failed to open the camera, handle the error in the onError() method.

Video Stopped Callback (onVideoStopped)

virtual void onVideoStopped()

This callback indicates that the video is stopped. The application can use this callback to change the configuration of the view (for example, displaying other pictures on the view) after the video stops.

Connection Interrupted Callback (rtcEngineConnectionDidInterrupted)

virtual void onConnectionInterrupted ()

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

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 the reconnection fails within a certain period (10 seconds by default), the callback onConnectionLost is triggered。The SDK continues to reconnect until the application calls leaveChannel.

Recording Service Status Refreshed Callback (onRefreshRecordingServiceStatus)

virtual void onRefreshRecordingServiceStatus(int status) {

    (void)status;}

This callback returns the status code after executing the refreshRecordingServiceStatus method successfully.

Recording Started/Ended/Status Returned Callback (onApiCallExecuted)

virtual void onApiCallExecuted(const char* api, int error) {

    (void)api;

    (void)error;

}

This callback returns the status code after a successful or unsuccessful execution of the startRecordingService or stopRecordingService method. It also returns the status code after an unsuccessful execution of the refreshRecordingServiceStatus method.