Public Member Functions

virtual ~IRtcEngineEventHandler ()
 
virtual void onWarning (int warn, const char *msg)
 
virtual void onError (int err, const char *msg)
 
virtual void onJoinChannelSuccess (const char *channel, uid_t uid, int elapsed)
 
virtual void onRejoinChannelSuccess (const char *channel, uid_t uid, int elapsed)
 
virtual void onLeaveChannel (const RtcStats &stats)
 
virtual void onClientRoleChanged (CLIENT_ROLE_TYPE oldRole, CLIENT_ROLE_TYPE newRole)
 
virtual void onUserJoined (uid_t uid, int elapsed)
 
virtual void onUserOffline (uid_t uid, USER_OFFLINE_REASON_TYPE reason)
 
virtual void onLastmileQuality (int quality)
 
virtual void onConnectionInterrupted ()
 
virtual void onConnectionLost ()
 
virtual void onConnectionBanned ()
 
virtual void onApiCallExecuted (int err, const char *api, const char *result)
 
virtual void onRequestToken ()
 
virtual void onTokenPrivilegeWillExpire (const char *token)
 
virtual void onAudioQuality (uid_t uid, int quality, unsigned short delay, unsigned short lost)
 
virtual void onRtcStats (const RtcStats &stats)
 
virtual void onNetworkQuality (uid_t uid, int txQuality, int rxQuality)
 
virtual void onLocalVideoStats (const LocalVideoStats &stats)
 
virtual void onRemoteVideoStats (const RemoteVideoStats &stats)
 
virtual void onRemoteAudioStats (const RemoteAudioStats &stats)
 
virtual void onAudioVolumeIndication (const AudioVolumeInfo *speakers, unsigned int speakerNumber, int totalVolume)
 
virtual void onActiveSpeaker (uid_t uid)
 
virtual void onVideoStopped ()
 
virtual void onFirstLocalVideoFrame (int width, int height, int elapsed)
 
virtual void onFirstRemoteVideoDecoded (uid_t uid, int width, int height, int elapsed)
 
virtual void onFirstRemoteVideoFrame (uid_t uid, int width, int height, int elapsed)
 
virtual void onUserMuteAudio (uid_t uid, bool muted)
 
virtual void onUserMuteVideo (uid_t uid, bool muted)
 
virtual void onUserEnableVideo (uid_t uid, bool enabled)
 
virtual void onAudioDeviceStateChanged (const char *deviceId, int deviceType, int deviceState)
 
virtual void onAudioDeviceVolumeChanged (MEDIA_DEVICE_TYPE deviceType, int volume, bool muted)
 
virtual void onCameraReady ()
 
virtual void onCameraFocusAreaChanged (int x, int y, int width, int height)
 
virtual void onCameraExposureAreaChanged (int x, int y, int width, int height)
 
virtual void onAudioMixingFinished ()
 
virtual void onRemoteAudioMixingBegin ()
 
virtual void onRemoteAudioMixingEnd ()
 
virtual void onAudioEffectFinished (int soundId)
 
virtual void onVideoDeviceStateChanged (const char *deviceId, int deviceType, int deviceState)
 
virtual void onVideoSizeChanged (uid_t uid, int width, int height, int rotation)
 
virtual void onRemoteVideoStateChanged (uid_t uid, REMOTE_VIDEO_STATE state)
 
virtual void onUserEnableLocalVideo (uid_t uid, bool enabled)
 
virtual void onStreamMessage (uid_t uid, int streamId, const char *data, size_t length)
 
virtual void onStreamMessageError (uid_t uid, int streamId, int code, int missed, int cached)
 
virtual void onMediaEngineLoadSuccess ()
 
virtual void onMediaEngineStartCallSuccess ()
 
virtual void onFirstLocalAudioFrame (int elapsed)
 
virtual void onFirstRemoteAudioFrame (uid_t uid, int elapsed)
 
virtual void onStreamPublished (const char *url, int error)
 
virtual void onStreamUnpublished (const char *url)
 
virtual void onTranscodingUpdated ()
 
virtual void onStreamInjectedStatus (const char *url, uid_t uid, int status)
 
virtual void onLocalPublishFallbackToAudioOnly (bool isFallbackOrRecover)
 
virtual void onRemoteSubscribeFallbackToAudioOnly (uid_t uid, bool isFallbackOrRecover)
 
virtual void onRemoteAudioTransportStats (uid_t uid, unsigned short delay, unsigned short lost, unsigned short rxKBitRate)
 
virtual void onRemoteVideoTransportStats (uid_t uid, unsigned short delay, unsigned short lost, unsigned short rxKBitRate)
 
virtual void onMicrophoneEnabled (bool enabled)
 
virtual void onConnectionStateChanged (CONNECTION_STATE_TYPE state, CONNECTION_CHANGED_REASON_TYPE reason)
 

Detailed Description

The SDK uses the IRtcEngineEventHandler interface class to send callbacks to the application. The application inherits the methods of this interface class to retrieve these callbacks.

All methods in this interface class have default (empty) implementations. Therefore, the application can only inherit some required events. In the callbacks, avoid time-consuming tasks or calling blocking APIs, such as the SendMessage method, otherwise, the SDK may not work properly.

Constructor & Destructor Documentation

◆ ~IRtcEngineEventHandler()

virtual agora::rtc::IRtcEngineEventHandler::~IRtcEngineEventHandler ( )
inlinevirtual

Member Function Documentation

◆ onWarning()

virtual void agora::rtc::IRtcEngineEventHandler::onWarning ( int  warn,
const char *  msg 
)
inlinevirtual

Reports a warning during SDK runtime.

In most cases, the application can ignore the warning reported by the SDK because the SDK can usually fix the issue and resume running. For example, when losing connection with the server, the SDK may report WARN_LOOKUP_CHANNEL_TIMEOUT and automatically try to reconnect.

Parameters
warnWarning code: WARN_CODE_TYPE.
msgPointer to the warning message.

◆ onError()

virtual void agora::rtc::IRtcEngineEventHandler::onError ( int  err,
const char *  msg 
)
inlinevirtual

Reports an error 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.

For example, the SDK reports an ERR_START_CALL error when failing to initialize a call. The application informs the user that the call initialization failed and invokes the leaveChannel method to leave the channel.

Parameters
errError code: ERROR_CODE_TYPE.
msgPointer to the error message.

◆ onJoinChannelSuccess()

virtual void agora::rtc::IRtcEngineEventHandler::onJoinChannelSuccess ( const char *  channel,
uid_t  uid,
int  elapsed 
)
inlinevirtual

Occurs when a user joins a specified channel.

The channel name assignment is based on channelName specified in the joinChannel method.

If the uid is not specified when joinChannel is called, the server automatically assigns a uid.

Parameters
channelPointer to the channel name.
uidUser ID.
elapsedTime elapsed (ms) from the user calling joinChannel until the SDK triggers this callback.

◆ onRejoinChannelSuccess()

virtual void agora::rtc::IRtcEngineEventHandler::onRejoinChannelSuccess ( const char *  channel,
uid_t  uid,
int  elapsed 
)
inlinevirtual

Occurs when a user rejoins the channel after disconnection due to network problems.

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
channelPointer to the channel name.
uidUser ID.
elapsedTime elapsed (ms) from starting to reconnect until the SDK triggers this callback.

◆ onLeaveChannel()

virtual void agora::rtc::IRtcEngineEventHandler::onLeaveChannel ( const RtcStats stats)
inlinevirtual

Occurs when a user leaves the channel.

When the application calls the leaveChannel method, this callback notifies the application that the user leaves the channel.

With this callback, the application retrieves information, such as the call duration and statistics.

Parameters
statsPointer to the statistics of the call: RtcStats.

◆ onClientRoleChanged()

virtual void agora::rtc::IRtcEngineEventHandler::onClientRoleChanged ( CLIENT_ROLE_TYPE  oldRole,
CLIENT_ROLE_TYPE  newRole 
)
inlinevirtual

Occurs when the user role switches in a live broadcast. For example, from a host to an audience or vice versa.

Parameters
oldRoleRole that the user switches from: CLIENT_ROLE_TYPE.
newRoleRole that the user switches to: CLIENT_ROLE_TYPE.

◆ onUserJoined()

virtual void agora::rtc::IRtcEngineEventHandler::onUserJoined ( uid_t  uid,
int  elapsed 
)
inlinevirtual

Occurs when a user or host joins the channel.

  • Communication profile: This callback notifies the application that another user joins the channel. If other users are already in the channel, the SDK also reports to the application on the existing users.
  • Live-broadcast profile: This callback notifies the application that the host joins the channel. If other hosts are already in the channel, the SDK also reports to the application on the existing hosts. Agora recommends limiting the number of hosts to 17.
Note
In the live broadcast profile:
  • The host receives this callback when another host joins the channel.
  • The audience in the channel receives this callback when a new host joins the channel.
  • When a web application joins the channel, the SDK triggers this callback as long as the web application publishes streams.
Parameters
uidID of the user or host who joins the channel.
elapsedTime delay (ms) from the user calling joinChannel or setClientRole (host) until the SDK triggers this callback.

◆ onUserOffline()

virtual void agora::rtc::IRtcEngineEventHandler::onUserOffline ( uid_t  uid,
USER_OFFLINE_REASON_TYPE  reason 
)
inlinevirtual

Occurs when a remote user (Communication)/host (Live Broadcast) leaves the channel.

There are two reasons for users to be offline:

  • Leave the channel: When the user/host leaves the channel, the user/host sends a goodbye message. When the message is received, the SDK assumes 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. Unreliable network connections may lead to false detections, so Agora recommends using a signaling system for more reliable offline detection.
Parameters
uidID of the user who leaves the channel or goes offline.
reasonReason why the user goes offline: USER_OFFLINE_REASON_TYPE.

◆ onLastmileQuality()

virtual void agora::rtc::IRtcEngineEventHandler::onLastmileQuality ( int  quality)
inlinevirtual

Reports the last mile network quality of the local user once every two seconds before the user joins the channel.

Last mile refers to the connection between the local device and Agora's edge server. After the application calls the enableLastmileTest method, this callback reports once every two seconds the uplink and downlink last mile network conditions of the local user before the user joins the channel.

Parameters
qualityNetwork quality: QUALITY_TYPE.

◆ onConnectionInterrupted()

virtual void agora::rtc::IRtcEngineEventHandler::onConnectionInterrupted ( )
inlinevirtual
Deprecated:
Occurs when the connection between the SDK and the server is interrupted.

Deprecated as of v2.3.2. Replaced by onConnectionStateChanged(CONNECTION_STATE_RECONNECTING, CONNECTION_CHANGED_INTERRUPTED).

The SDK triggers this callback when it loses connection with the server for more than four seconds after the connection is established.

After triggering this callback, the SDK tries reconnecting to the server. You can use this callback to implement pop-up reminders.

This callback is different from onConnectionLost:

  • The SDK triggers the onConnectionInterrupted callback when it loses connection with the server for more than four seconds after it successfully joins the channel.
  • The SDK triggers the onConnectionLost callback when it loses connection with the server for more than 10 seconds, regardless of whether it joins the channel or not.

For both callbacks, the SDK tries to reconnect to the server until the application calls leaveChannel.

◆ onConnectionLost()

virtual void agora::rtc::IRtcEngineEventHandler::onConnectionLost ( )
inlinevirtual

Occurs when the SDK cannot reconnect to Agora's edge server 10 seconds after its connection to the server is interrupted.

The SDK triggers this callback when it cannot connect to the server 10 seconds after calling joinChannel, regardless of whether it is in the channel or not.

This callback is different from onConnectionInterrupted:

  • The SDK triggers the onConnectionInterrupted callback when it loses connection with the server for more than four seconds after it successfully joins the channel.
  • The SDK triggers the onConnectionLost callback when it loses connection with the server for more than 10 seconds, regardless of whether it joins the channel or not.

For both callbacks, the SDK tries to reconnect to the server until the application calls leaveChannel.

◆ onConnectionBanned()

virtual void agora::rtc::IRtcEngineEventHandler::onConnectionBanned ( )
inlinevirtual
Deprecated:
Deprecated as of v2.3.2. Replaced by onConnectionStateChanged(CONNECTION_STATE_FAILED, CONNECTION_CHANGED_BANNED_BY_SERVER).

Occurs when your connection is banned by the Agora Server.

◆ onApiCallExecuted()

virtual void agora::rtc::IRtcEngineEventHandler::onApiCallExecuted ( int  err,
const char *  api,
const char *  result 
)
inlinevirtual

Occurs when a method is executed by the SDK.

Parameters
errThe error code (ERROR_CODE_TYPE) returned by the SDK when the method fails. If the SDK returns 0, then the SDK is called successfully.
apiPointer to the method executed by the SDK.
resultPointer to the result of the method call.

◆ onRequestToken()

virtual void agora::rtc::IRtcEngineEventHandler::onRequestToken ( )
inlinevirtual

Occurs when the token expires.

After a token is specified by calling the joinChannel method, if the SDK losses 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 to generate a new token. Call renewToken to renew the token.

In previous SDKs, this notification was provided in the onError callback as the ERR_TOKEN_EXPIRED and ERR_INVALID_TOKEN errors. Starting from the Agora SDK v1.7.3, the old method is still valid, but it is recommended to use the onRequestToken callback.

◆ onTokenPrivilegeWillExpire()

virtual void agora::rtc::IRtcEngineEventHandler::onTokenPrivilegeWillExpire ( const char *  token)
inlinevirtual

Occurs when the token expires in 30 seconds.

The user becomes offline if the token used in joinChannel expires. The SDK triggers this callback 30 seconds before the token expires to remind the application to get a new token. Upon receiving this callback, generate a new token on the server and call renewToken to pass the new token to the SDK.

Parameters
tokenPointer to the token that expires in 30 seconds.

◆ onAudioQuality()

virtual void agora::rtc::IRtcEngineEventHandler::onAudioQuality ( uid_t  uid,
int  quality,
unsigned short  delay,
unsigned short  lost 
)
inlinevirtual
Deprecated:
Reports the statistics of the audio stream from each remote user/host.

Deprecated as of v2.3.2. Use onRemoteAudioStats instead.

The SDK triggers this callback once every two seconds to report the audio quality of each remote user/host sending an audio stream. If a channel has multiple users/hosts sending audio streams, the SDK triggers this callback as many times.

Parameters
uidUser ID of the speaker.
qualityAudio quality of the user: QUALITY_TYPE
delayTime delay (ms) of the audio packet from the sender to the receiver, including the time delay from audio sampling pre-processing, transmission, and the jitter buffer.
lostPacket loss rate (%) of the audio packet sent from the sender to the receiver.

◆ onRtcStats()

virtual void agora::rtc::IRtcEngineEventHandler::onRtcStats ( const RtcStats stats)
inlinevirtual

Reports the statistics of the current call session once every two seconds.

Parameters
statsPointer to the RTC engine statistics: RtcStats.

◆ onNetworkQuality()

virtual void agora::rtc::IRtcEngineEventHandler::onNetworkQuality ( uid_t  uid,
int  txQuality,
int  rxQuality 
)
inlinevirtual

Reports the last mile network quality of each user in the channel once every two seconds.

Last mile refers to the connection between the local device and Agora's edge server. This callback reports once every two seconds the uplink last mile network conditions of each user in the channel. If a channel includes multiple users, then this callback will be triggered as many times.

Parameters
uidUser ID. The network quality of the user with this uid is reported. If uid is 0, the local network quality is reported.
txQualityUplink transmission quality rating of the user in terms of the transmission bitrate, packet loss rate, average RTT (Round-Trip Time), and jitter of the uplink network. txQuality is a quality rating helping you understand how well the current uplink network conditions can support the selected VideoEncoderConfiguration. For example, a 1000 Kbps uplink network may be adequate for video frames with a resolution of 640 × 480 and a frame rate of 15 fps in the Live Broadcast profile, but may be inadequate for resolutions higher than 1280 × 720. See QUALITY_TYPE.
rxQualityDownlink network quality rating of the user in terms of the packet loss rate, average RTT, and jitter of the downlink network. See QUALITY_TYPE.

◆ onLocalVideoStats()

virtual void agora::rtc::IRtcEngineEventHandler::onLocalVideoStats ( const LocalVideoStats stats)
inlinevirtual

Reports the statistics of the uploading local video streams once every two seconds.

Parameters
statsPointer to the statistics of the uploading local video streams: LocalVideoStats

◆ onRemoteVideoStats()

virtual void agora::rtc::IRtcEngineEventHandler::onRemoteVideoStats ( const RemoteVideoStats stats)
inlinevirtual

Reports the statistics of the video stream from each remote user/host.

The SDK triggers this callback once every two seconds for each remote user/host. If a channel includes multiple remote users, the SDK triggers this callback as many times.

This callback reports statistics more closely linked to the real-user experience of the video transmission quality than the statistics that the onRemoteVideoTransportStats callback reports.

Schemes such as FEC (Forward Error Correction) or retransmission counter the frame loss rate. Hence, users may find the overall video quality acceptable even when the packet loss rate is high.

Parameters
statsPointer to the statistics of the received remote video streams. See: RemoteVideoStats.

◆ onRemoteAudioStats()

virtual void agora::rtc::IRtcEngineEventHandler::onRemoteAudioStats ( const RemoteAudioStats stats)
inlinevirtual

Reports the statistics of the audio stream from each remote user/host.

This callback replaces the onAudioQuality callback.

The SDK triggers this callback once every two seconds for each remote user/host. If a channel includes multiple remote users, the SDK triggers this callback as many times.

This callback reports statistics more closely linked to the real-user experience of the audio transmission quality than the statistics that the onRemoteAudioTransportStats callback reports. This callback reports more about media layer statistics such as the frame loss rate, while the onRemoteAudioTransportStats callback reports more about the transport layer statistics such as the packet loss rate.

Schemes such as FEC (Forward Error Correction) or retransmission counter the frame loss rate. Hence, users may find the overall audio quality acceptable even when the packet loss rate is high.

Parameters
statsPointer to the statistics of the received remote audio streams. See: RemoteAudioStats.

◆ onAudioVolumeIndication()

virtual void agora::rtc::IRtcEngineEventHandler::onAudioVolumeIndication ( const AudioVolumeInfo speakers,
unsigned int  speakerNumber,
int  totalVolume 
)
inlinevirtual

Reports which users are speaking and the speakers' volume.

This callback reports the ID and volume of the loudest speakers at the moment in the channel.

This callback is disabled by default and can be enabled by the enableAudioVolumeIndication method.

The local user has a dedicated onAudioVolumeIndication callback; all remote speakers share a separate onAudioVolumeIndication callback.

  • For the local user's callback, the speakers array has uid = 0 and volume = totalVolume, and speakerNumber = 1 regardless of whether the local user speaks or not.
  • For the remote speakers' callback, the speakers array includes the user ID and volume of the loudest speakers in the channel.
Note
  • Calling the muteLocalAudioStream method affects the SDK's behavior:
    • If the local user calls the muteLocalAudioStream method, the SDK stops triggering the local user's callback.
    • 15 seconds after a remote speaker calls the muteLocalAudioStream method, the remote speakers' callback excludes this remote user's information; 15 seconds after all remote users call the muteLocalAudioStream method, the SDK stops triggering the remote speakers' callback.
  • An empty speakers array in the onAudioVolumeIndication callback suggests that no remote user is speaking at the moment.
Parameters
speakersA pointer to the array that contains the user ID and volume information for each speaker: AudioVolumeInfo.
speakerNumberTotal number of speakers.
totalVolumeTotal volume after audio mixing. The value ranges between 0 (lowest volume) and 255 (highest volume).

◆ onActiveSpeaker()

virtual void agora::rtc::IRtcEngineEventHandler::onActiveSpeaker ( uid_t  uid)
inlinevirtual

Reports which user is the loudest speaker.

If the user enables the audio volume indication by calling enableAudioVolumeIndication, this callback returns the uid of the active speaker detected by the audio volume detection module of the SDK.

Note
  • To receive this callback, you need to call enableAudioVolumeIndication.
  • This callback returns the user ID of the user with the highest voice volume during a period of time, instead of at the moment.
Parameters
uidUser ID of the active speaker. A uid of 0 represents the local user.

◆ onVideoStopped()

virtual void agora::rtc::IRtcEngineEventHandler::onVideoStopped ( )
inlinevirtual

Occurs when the video stops playing.

The application can use this callback to change the configuration of the view (for example, displaying other pictures in the view) after the video stops playing.

◆ onFirstLocalVideoFrame()

virtual void agora::rtc::IRtcEngineEventHandler::onFirstLocalVideoFrame ( int  width,
int  height,
int  elapsed 
)
inlinevirtual

Occurs when the engine receives and renders the first local video frame on the video window.

Parameters
widthWidth (pixels) of the first local video frame.
heightHeight (pixels) of the first local video frame.
elapsedTime elapsed (ms) from the local user calling joinChannel until the SDK triggers this callback. If startPreview is called before joinChannel, then elapsed is the time elapsed from startPreview until the SDK triggers this callback.

◆ onFirstRemoteVideoDecoded()

virtual void agora::rtc::IRtcEngineEventHandler::onFirstRemoteVideoDecoded ( uid_t  uid,
int  width,
int  height,
int  elapsed 
)
inlinevirtual

Occurs when the engine receives and decodes the first video frame from a specific remote user.

The application can configure the user view settings in this callback.

Parameters
uidUser ID of the remote user sending the video stream.
widthWidth (pixels) of the video stream.
heightHeight (pixels) of the video stream.
elapsedTime elapsed (ms) from the remote user calling joinChannel until the SDK triggers this callback.

◆ onFirstRemoteVideoFrame()

virtual void agora::rtc::IRtcEngineEventHandler::onFirstRemoteVideoFrame ( uid_t  uid,
int  width,
int  height,
int  elapsed 
)
inlinevirtual

Occurs when the first remote video frame is rendered.

The SDK triggers this callback when the first frame of the remote video is displayed in the user’s video window. The application can retrieve the time elapsed from a user joining the channel until the first video frame is displayed.

Parameters
uidUser ID of the remote user sending the video stream.
widthWidth (pixels) of the video frame.
heightHeight (pixels) of the video stream.
elapsedTime elapsed (ms) from the remote user calling joinChannel until the SDK triggers this callback.

◆ onUserMuteAudio()

virtual void agora::rtc::IRtcEngineEventHandler::onUserMuteAudio ( uid_t  uid,
bool  muted 
)
inlinevirtual

Occurs when a remote user's audio stream is muted/unmuted.

Note
This callback returns invalid when the number of users in a channel exceeds 20.
Parameters
uidID of the remote user.
mutedWhether the remote user's audio stream is muted/unmuted:
  • true: Muted.
  • false: Unmuted.

◆ onUserMuteVideo()

virtual void agora::rtc::IRtcEngineEventHandler::onUserMuteVideo ( uid_t  uid,
bool  muted 
)
inlinevirtual

Occurs when a remote user's video stream playback pauses/resumes.

Note
This callback returns invalid when the number of users in a channel exceeds 20.
Parameters
uidUser ID of the remote user.
mutedWhether the remote user's video stream playback is paused/resumed:
  • true: Paused.
  • false: Resumed.

◆ onUserEnableVideo()

virtual void agora::rtc::IRtcEngineEventHandler::onUserEnableVideo ( uid_t  uid,
bool  enabled 
)
inlinevirtual

Occurs when a specific remote user enables/disables the video module.

Once the video module is disabled, the remote user can only use a voice call. The remote user cannot send or receive any video from other users.

Note
This callback returns invalid when the number of users in a channel exceeds 20.
Parameters
uidUser ID of the remote user.
enabledWhether the remote user enables/disables the video module:
  • true: Enable. The remote user can enter a video session.
  • false: Disable. The remote user can only enter a voice session, and cannot send or receive any video stream.

◆ onAudioDeviceStateChanged()

virtual void agora::rtc::IRtcEngineEventHandler::onAudioDeviceStateChanged ( const char *  deviceId,
int  deviceType,
int  deviceState 
)
inlinevirtual

Occurs when the audio device state changes.

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

Parameters
deviceIdPointer to the device ID.
deviceTypeDevice type: MEDIA_DEVICE_TYPE.
deviceStateDevice state: MEDIA_DEVICE_STATE_TYPE.

◆ onAudioDeviceVolumeChanged()

virtual void agora::rtc::IRtcEngineEventHandler::onAudioDeviceVolumeChanged ( MEDIA_DEVICE_TYPE  deviceType,
int  volume,
bool  muted 
)
inlinevirtual

Occurs when the volume of the playback device, microphone, or application changes.

Parameters
deviceTypeDevice type: MEDIA_DEVICE_TYPE.
volumeVolume of the device. The value ranges between 0 and 255.
muted
  • true: The audio device is muted.
  • false: The audio device is not muted.

◆ onCameraReady()

virtual void agora::rtc::IRtcEngineEventHandler::onCameraReady ( )
inlinevirtual

Occurs when the camera turns on and is ready to capture the video.

If the camera fails to turn on, fix the error reported in the onError callback.

◆ onCameraFocusAreaChanged()

virtual void agora::rtc::IRtcEngineEventHandler::onCameraFocusAreaChanged ( int  x,
int  y,
int  width,
int  height 
)
inlinevirtual

Occurs when the camera focus area changes.

Parameters
xx coordinate of the changed camera focus area.
yy coordinate of the changed camera focus area.
widthWidth of the changed camera focus area.
heightHeight of the changed camera focus area.

◆ onCameraExposureAreaChanged()

virtual void agora::rtc::IRtcEngineEventHandler::onCameraExposureAreaChanged ( int  x,
int  y,
int  width,
int  height 
)
inlinevirtual

Occurs when the camera exposure area changes.

Parameters
xx coordinate of the changed camera exposure area.
yy coordinate of the changed camera exposure area.
widthWidth of the changed camera exposure area.
heightHeight of the changed camera exposure area.

◆ onAudioMixingFinished()

virtual void agora::rtc::IRtcEngineEventHandler::onAudioMixingFinished ( )
inlinevirtual

Occurs when the audio mixing file playback finishes.

You can start an audio mixing file playback by calling the startAudioMixing method. The SDK triggers this callback when the audio mixing file playback finishes.

If the startAudioMixing method call fails, an error code returns in the onError callback.

◆ onRemoteAudioMixingBegin()

virtual void agora::rtc::IRtcEngineEventHandler::onRemoteAudioMixingBegin ( )
inlinevirtual

Occurs when a remote user starts audio mixing.

When a remote user calls startAudioMixing to play the background music, the SDK reports this callback.

◆ onRemoteAudioMixingEnd()

virtual void agora::rtc::IRtcEngineEventHandler::onRemoteAudioMixingEnd ( )
inlinevirtual

Occurs when a remote user finishes audio mixing.

◆ onAudioEffectFinished()

virtual void agora::rtc::IRtcEngineEventHandler::onAudioEffectFinished ( int  soundId)
inlinevirtual

Occurs when the local audio effect playback finishes.

You can start a local audio effect file playback by calling the playEffect method. The SDK triggers this callback when the local audio effect file playback finishes.

Parameters
soundIdID of the local audio effect. Each local audio effect has a unique ID.

◆ onVideoDeviceStateChanged()

virtual void agora::rtc::IRtcEngineEventHandler::onVideoDeviceStateChanged ( const char *  deviceId,
int  deviceType,
int  deviceState 
)
inlinevirtual

Occurs when the video device state changes.

Note
On a Windows device with an external camera for video capturing, the video disables once the external camera is unplugged.
Parameters
deviceIdPointer to the device ID of the video device that changes state.
deviceTypeDevice type: MEDIA_DEVICE_TYPE.
deviceStateDevice state: MEDIA_DEVICE_STATE_TYPE.

◆ onVideoSizeChanged()

virtual void agora::rtc::IRtcEngineEventHandler::onVideoSizeChanged ( uid_t  uid,
int  width,
int  height,
int  rotation 
)
inlinevirtual

Occurs when the video size or rotation of a specified user changes.

Parameters
uidUser ID of the remote user or local user (0) whose video size or rotation changes.
widthNew width (pixels) of the video.
heightNew height (pixels) of the video.
rotationNew rotation of the video [0 to 360).

◆ onRemoteVideoStateChanged()

virtual void agora::rtc::IRtcEngineEventHandler::onRemoteVideoStateChanged ( uid_t  uid,
REMOTE_VIDEO_STATE  state 
)
inlinevirtual

Occurs when the remote video state changes.

Note
The SDK triggers this callback when the time interval between two video frames ≥ 600 ms.
Parameters
uidID of the user whose video state changes.
stateState of the remote video: Playing normally or frozen. See REMOTE_VIDEO_STATE.

◆ onUserEnableLocalVideo()

virtual void agora::rtc::IRtcEngineEventHandler::onUserEnableLocalVideo ( uid_t  uid,
bool  enabled 
)
inlinevirtual

Occurs when a specified remote user enables/disables the local video capturing function.

This callback is only applicable to the scenario when the user only wants to watch the remote video without sending any video stream to the other user.

Parameters
uidUser ID of the remote user.
enabledWhether the specified remote user enables/disables the local video capturing function:
  • true: Enable. Other users in the channel can see the video of this remote user.
  • false: Disable. Other users in the channel can no longer receive the video stream from this remote user, while this remote user can still receive the video streams from other users.

◆ onStreamMessage()

virtual void agora::rtc::IRtcEngineEventHandler::onStreamMessage ( uid_t  uid,
int  streamId,
const char *  data,
size_t  length 
)
inlinevirtual

Occurs when the local user receives the data stream from the remote user within five seconds.

Parameters
uidUser ID of the remote user sending the message.
streamIdStream ID.
dataPointer to the data received by the local user.
lengthLength of the data in bytes.

◆ onStreamMessageError()

virtual void agora::rtc::IRtcEngineEventHandler::onStreamMessageError ( uid_t  uid,
int  streamId,
int  code,
int  missed,
int  cached 
)
inlinevirtual

Occurs when the local user does not receive the data stream from the remote user within five seconds.

Parameters
uidUser ID of the remote user sending the message.
streamIdStream ID.
codeError code: ERROR_CODE_TYPE.
missedNumber of lost messages.
cachedNumber of incoming cached messages when the data stream is interrupted.

◆ onMediaEngineLoadSuccess()

virtual void agora::rtc::IRtcEngineEventHandler::onMediaEngineLoadSuccess ( )
inlinevirtual

Occurs when the media engine loads.

◆ onMediaEngineStartCallSuccess()

virtual void agora::rtc::IRtcEngineEventHandler::onMediaEngineStartCallSuccess ( )
inlinevirtual

Occurs when the media engine call starts.

◆ onFirstLocalAudioFrame()

virtual void agora::rtc::IRtcEngineEventHandler::onFirstLocalAudioFrame ( int  elapsed)
inlinevirtual

Occurs when the engine sends the first local audio frame.

Parameters
elapsedTime elapsed (ms) from the local user calling joinChannel until the SDK triggers this callback.

◆ onFirstRemoteAudioFrame()

virtual void agora::rtc::IRtcEngineEventHandler::onFirstRemoteAudioFrame ( uid_t  uid,
int  elapsed 
)
inlinevirtual

Occurs when the engine receives the first audio frame from a specific remote user.

Parameters
uidUser ID of the remote user.
elapsedTime elapsed (ms) from the remote user calling joinChannel until the SDK triggers this callback.

◆ onStreamPublished()

virtual void agora::rtc::IRtcEngineEventHandler::onStreamPublished ( const char *  url,
int  error 
)
inlinevirtual

Occurs when a stream is published. (CDN live only.)

Parameters
urlPointer to the URL address, to which the publisher publishes the stream.
errorError code: ERROR_CODE_TYPE. Main errors include:

◆ onStreamUnpublished()

virtual void agora::rtc::IRtcEngineEventHandler::onStreamUnpublished ( const char *  url)
inlinevirtual

Occurs when a stream is unpublished. (CDN live only.)

This callback notifies the host that the CDN live stream is unpublished.

Parameters
urlPointer to the URL address, from which the publisher unpublishes the stream.

◆ onTranscodingUpdated()

virtual void agora::rtc::IRtcEngineEventHandler::onTranscodingUpdated ( )
inlinevirtual

Occurs when the publisher's transcoding is updated.

◆ onStreamInjectedStatus()

virtual void agora::rtc::IRtcEngineEventHandler::onStreamInjectedStatus ( const char *  url,
uid_t  uid,
int  status 
)
inlinevirtual

Occurs when a voice or video stream URL address is added to a live broadcast.

Parameters
urlPointer to the URL address of the externally injected stream.
uidUser ID.
statusState of the externally injected stream: INJECT_STREAM_STATUS.

◆ onLocalPublishFallbackToAudioOnly()

virtual void agora::rtc::IRtcEngineEventHandler::onLocalPublishFallbackToAudioOnly ( bool  isFallbackOrRecover)
inlinevirtual

Occurs when the locally published media stream falls back to an audio-only stream due to poor network conditions or switches back to the video after the network conditions improve.

If you call setLocalPublishFallbackOption and set option as STREAM_FALLBACK_OPTION_AUDIO_ONLY, the SDK triggers this callback when the locally published stream falls back to audio-only mode due to poor uplink conditions, or when the audio stream switches back to the video after the uplink network condition improves.

Parameters
isFallbackOrRecoverWhether the locally published stream falls back to audio-only or switches back to the video:
  • true: The locally published stream falls back to audio-only due to poor network conditions.
  • false: The locally published stream switches back to the video after the network conditions improve.

◆ onRemoteSubscribeFallbackToAudioOnly()

virtual void agora::rtc::IRtcEngineEventHandler::onRemoteSubscribeFallbackToAudioOnly ( uid_t  uid,
bool  isFallbackOrRecover 
)
inlinevirtual

Occurs when the remotely subscribed media stream falls back to audio-only due to poor network conditions or switches back to the video after the network conditions improve.

If you call setRemoteSubscribeFallbackOption and set option as STREAM_FALLBACK_OPTION_AUDIO_ONLY, the SDK triggers this callback when the remotely subscribed media stream falls back to audio-only mode due to poor uplink conditions, or when the remotely subscribed media stream switches back to the video after the uplink network condition improves.

Note
Once the remotely subscribed media stream switches to the low stream due to poor network conditions, you can monitor the stream switch between a high and low stream in the RemoteVideoStats callback.
Parameters
uidID of the remote user sending the stream.
isFallbackOrRecoverWhether the remotely subscribed media stream falls back to audio-only or switches back to the video:
  • true: The remotely subscribed media stream falls back to audio-only due to poor network conditions.
  • false: The remotely subscribed media stream switches back to the video stream after the network conditions improved.

◆ onRemoteAudioTransportStats()

virtual void agora::rtc::IRtcEngineEventHandler::onRemoteAudioTransportStats ( uid_t  uid,
unsigned short  delay,
unsigned short  lost,
unsigned short  rxKBitRate 
)
inlinevirtual

Reports the transport-layer statistics of each remote audio stream.

This callback reports the transport-layer statistics, such as the packet loss rate and network time delay, once every two seconds after the local user receives an audio packet from a remote user.

Parameters
uidUser ID of the remote user sending the audio packet.
delayNetwork time delay (ms) from the remote user sending the audio packet to the local user.
lostPacket loss rate (%) of the audio packet sent from the remote user.
rxKBitRateReceived bitrate (Kbps) of the audio packet sent from the remote user.

◆ onRemoteVideoTransportStats()

virtual void agora::rtc::IRtcEngineEventHandler::onRemoteVideoTransportStats ( uid_t  uid,
unsigned short  delay,
unsigned short  lost,
unsigned short  rxKBitRate 
)
inlinevirtual

Reports the transport-layer statistics of each remote video stream.

This callback reports the transport-layer statistics, such as the packet loss rate and network time delay, once every two seconds after the local user receives a video packet from a remote user.

Parameters
uidUser ID of the remote user sending the video packet.
delayNetwork time delay (ms) from the remote user sending the video packet to the local user.
lostPacket loss rate (%) of the video packet sent from the remote user.
rxKBitRateReceived bitrate (Kbps) of the video packet sent from the remote user.

◆ onMicrophoneEnabled()

virtual void agora::rtc::IRtcEngineEventHandler::onMicrophoneEnabled ( bool  enabled)
inlinevirtual

Occurs when the microphone is enabled/disabled.

Parameters
enabledWhether the microphone is enabled/disabled:
  • true: Enabled.
  • false: Disabled.

◆ onConnectionStateChanged()

virtual void agora::rtc::IRtcEngineEventHandler::onConnectionStateChanged ( CONNECTION_STATE_TYPE  state,
CONNECTION_CHANGED_REASON_TYPE  reason 
)
inlinevirtual

Occurs when the connection state of the SDK to the server is changed.

Parameters
stateSee CONNECTION_STATE_TYPE.
reasonSee CONNECTION_CHANGED_REASON_TYPE.