Public Member Functions
virtual	~IChannelEventHandler ()

virtual void	onChannelWarning (IChannel rtcChannel, int warn, const char msg)

virtual void	onChannelError (IChannel rtcChannel, int err, const char msg)

virtual void	onJoinChannelSuccess (IChannel *rtcChannel, uid_t uid, int elapsed)

virtual void	onRejoinChannelSuccess (IChannel *rtcChannel, uid_t uid, int elapsed)

virtual void	onLeaveChannel (IChannel *rtcChannel, const RtcStats &stats)

virtual void	onClientRoleChanged (IChannel *rtcChannel, CLIENT_ROLE_TYPE oldRole, CLIENT_ROLE_TYPE newRole)

virtual void	onUserJoined (IChannel *rtcChannel, uid_t uid, int elapsed)

virtual void	onUserOffline (IChannel *rtcChannel, uid_t uid, USER_OFFLINE_REASON_TYPE reason)

virtual void	onConnectionLost (IChannel *rtcChannel)

virtual void	onRequestToken (IChannel *rtcChannel)

virtual void	onTokenPrivilegeWillExpire (IChannel rtcChannel, const char token)

virtual void	onRtcStats (IChannel *rtcChannel, const RtcStats &stats)

virtual void	onNetworkQuality (IChannel *rtcChannel, uid_t uid, int txQuality, int rxQuality)

virtual void	onRemoteVideoStats (IChannel *rtcChannel, const RemoteVideoStats &stats)

virtual void	onRemoteAudioStats (IChannel *rtcChannel, const RemoteAudioStats &stats)

virtual void	onRemoteAudioStateChanged (IChannel *rtcChannel, uid_t uid, REMOTE_AUDIO_STATE state, REMOTE_AUDIO_STATE_REASON reason, int elapsed)

virtual void	onActiveSpeaker (IChannel *rtcChannel, uid_t uid)

virtual void	onVideoSizeChanged (IChannel *rtcChannel, uid_t uid, int width, int height, int rotation)

virtual void	onRemoteVideoStateChanged (IChannel *rtcChannel, uid_t uid, REMOTE_VIDEO_STATE state, REMOTE_VIDEO_STATE_REASON reason, int elapsed)

virtual void	onStreamMessage (IChannel rtcChannel, uid_t uid, int streamId, const char data, size_t length)

virtual void	onStreamMessageError (IChannel *rtcChannel, uid_t uid, int streamId, int code, int missed, int cached)

virtual void	onChannelMediaRelayStateChanged (IChannel *rtcChannel, CHANNEL_MEDIA_RELAY_STATE state, CHANNEL_MEDIA_RELAY_ERROR code)

virtual void	onChannelMediaRelayEvent (IChannel *rtcChannel, CHANNEL_MEDIA_RELAY_EVENT code)

virtual void	onRtmpStreamingStateChanged (IChannel rtcChannel, const char url, RTMP_STREAM_PUBLISH_STATE state, RTMP_STREAM_PUBLISH_ERROR errCode)

virtual void	onTranscodingUpdated (IChannel *rtcChannel)

virtual void	onStreamInjectedStatus (IChannel rtcChannel, const char url, uid_t uid, int status)

virtual void	onRemoteSubscribeFallbackToAudioOnly (IChannel *rtcChannel, uid_t uid, bool isFallbackOrRecover)

virtual void	onConnectionStateChanged (IChannel *rtcChannel, CONNECTION_STATE_TYPE state, CONNECTION_CHANGED_REASON_TYPE reason)

Detailed Description

The IChannelEventHandler class.

Constructor & Destructor Documentation

◆ ~IChannelEventHandler()

virtual agora::rtc::IChannelEventHandler::~IChannelEventHandler ( )

inlinevirtual

Member Function Documentation

◆ onChannelWarning()

virtual void agora::rtc::IChannelEventHandler::onChannelWarning	(	IChannel *	rtcChannel,
		int	warn,
		const char *	msg
	)

inlinevirtual

Reports the warning code of IChannel.

Parameters

rtcChannel	IChannel
warn	The warning code: WARN_CODE_TYPE
msg	The warning message.

◆ onChannelError()

virtual void agora::rtc::IChannelEventHandler::onChannelError	(	IChannel *	rtcChannel,
		int	err,
		const char *	msg
	)

inlinevirtual

Reports the error code of IChannel.

Parameters

rtcChannel	IChannel
err	The error code: ERROR_CODE_TYPE
msg	The error message.

◆ onJoinChannelSuccess()

virtual void agora::rtc::IChannelEventHandler::onJoinChannelSuccess	(	IChannel *	rtcChannel,
		uid_t	uid,
		int	elapsed
	)

inlinevirtual

Occurs when a user joins a channel.

This callback notifies the application that a user joins a specified channel.

Parameters

rtcChannel	IChannel
uid	The user ID. If the `uid` is not specified in the joinChannel method, the server automatically assigns a `uid`.
elapsed	Time elapsed (ms) from the local user calling joinChannel until this callback is triggered.

◆ onRejoinChannelSuccess()

virtual void agora::rtc::IChannelEventHandler::onRejoinChannelSuccess	(	IChannel *	rtcChannel,
		uid_t	uid,
		int	elapsed
	)

inlinevirtual

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

Parameters

rtcChannel	IChannel
uid	The user ID.
elapsed	Time elapsed (ms) from the local user starting to reconnect until this callback is triggered.

◆ onLeaveChannel()

virtual void agora::rtc::IChannelEventHandler::onLeaveChannel	(	IChannel *	rtcChannel,
		const RtcStats &	stats
	)

inlinevirtual

Occurs when a user leaves the channel.

This callback notifies the application that a user leaves the channel when the application calls the leaveChannel method.

The application retrieves information, such as the call duration and statistics.

Parameters

rtcChannel	IChannel
stats	The call statistics: RtcStats.

◆ onClientRoleChanged()

virtual void agora::rtc::IChannelEventHandler::onClientRoleChanged	(	IChannel *	rtcChannel,
		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.

This callback notifies the application of a user role switch when the application calls the setClientRole method.

The SDK triggers this callback when the local user switches the user role by calling the setClientRole method after joining the channel.

Parameters

rtcChannel	IChannel
oldRole	Role that the user switches from: CLIENT_ROLE_TYPE.
newRole	Role that the user switches to: CLIENT_ROLE_TYPE.

◆ onUserJoined()

virtual void agora::rtc::IChannelEventHandler::onUserJoined	(	IChannel *	rtcChannel,
		uid_t	uid,
		int	elapsed
	)

inlinevirtual

Occurs when a remote user (Communication)/ host (Live Broadcast) 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. We recommend limiting the number of hosts to 17.

The SDK triggers this callback under one of the following circumstances:

A remote user/host joins the channel by calling the joinChannel method.
A remote user switches the user role to the host by calling the setClientRole method after joining the channel.
A remote user/host rejoins the channel after a network interruption.
The host injects an online media stream into the channel by calling the addInjectStreamUrl method.

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

rtcChannel	IChannel
uid	User ID of the user or host joining the channel.
elapsed	Time delay (ms) from the local user calling the joinChannel method until the SDK triggers this callback.

◆ onUserOffline()

virtual void agora::rtc::IChannelEventHandler::onUserOffline	(	IChannel *	rtcChannel,
		uid_t	uid,
		USER_OFFLINE_REASON_TYPE	reason
	)

inlinevirtual

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

Reasons why the user is 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, the SDK assumes that the user/host drops offline. Unreliable network connections may lead to false detections, so we recommend using the Agora RTM SDK for more reliable offline detection.

Parameters

rtcChannel	IChannel
uid	User ID of the user leaving the channel or going offline.
reason	Reason why the user is offline: USER_OFFLINE_REASON_TYPE.

◆ onConnectionLost()

virtual void agora::rtc::IChannelEventHandler::onConnectionLost ( IChannel * rtcChannel )

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 the joinChannel method, whether or not it is in the channel.

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, whether or not it joins the channel.

If the SDK fails to rejoin the channel 20 minutes after being disconnected from Agora's edge server, the SDK stops rejoining the channel.

Parameters

rtcChannel IChannel

◆ onRequestToken()

virtual void agora::rtc::IChannelEventHandler::onRequestToken ( IChannel * rtcChannel )

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 the renewToken method to renew the token.

Parameters

rtcChannel IChannel

◆ onTokenPrivilegeWillExpire()

virtual void agora::rtc::IChannelEventHandler::onTokenPrivilegeWillExpire	(	IChannel *	rtcChannel,
		const char *	token
	)

inlinevirtual

Occurs when the token expires in 30 seconds.

The user becomes offline if the token used in the joinChannel method 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 the renewToken method to pass the new token to the SDK.

Parameters

rtcChannel	IChannel
token	Token that expires in 30 seconds.

◆ onRtcStats()

virtual void agora::rtc::IChannelEventHandler::onRtcStats	(	IChannel *	rtcChannel,
		const RtcStats &	stats
	)

inlinevirtual

Reports the statistics of the current call.

The SDK triggers this callback once every two seconds after the user joins the channel.

Parameters

rtcChannel	IChannel
stats	Statistics of the RtcEngine: RtcStats.

◆ onNetworkQuality()

virtual void agora::rtc::IChannelEventHandler::onNetworkQuality	(	IChannel *	rtcChannel,
		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 last mile network conditions of each user in the channel. If a channel includes multiple users, the SDK triggers this callback as many times.

Parameters

rtcChannel	IChannel
uid	User ID. The network quality of the user with this `uid` is reported. If `uid` is 0, the local network quality is reported.
txQuality	Uplink 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.
rxQuality	Downlink network quality rating of the user in terms of the packet loss rate, average RTT, and jitter of the downlink network. See QUALITY_TYPE.

◆ onRemoteVideoStats()

virtual void agora::rtc::IChannelEventHandler::onRemoteVideoStats	(	IChannel *	rtcChannel,
		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.

Parameters

rtcChannel	IChannel
stats	Statistics of the remote video stream. See RemoteVideoStats.

◆ onRemoteAudioStats()

virtual void agora::rtc::IChannelEventHandler::onRemoteAudioStats	(	IChannel *	rtcChannel,
		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.

Parameters

rtcChannel	IChannel
stats	The statistics of the received remote audio streams. See RemoteAudioStats.

◆ onRemoteAudioStateChanged()

virtual void agora::rtc::IChannelEventHandler::onRemoteAudioStateChanged	(	IChannel *	rtcChannel,
		uid_t	uid,
		REMOTE_AUDIO_STATE	state,
		REMOTE_AUDIO_STATE_REASON	reason,
		int	elapsed
	)

inlinevirtual

Occurs when the remote audio state changes.

This callback indicates the state change of the remote audio stream.

Parameters

rtcChannel	IChannel
uid	ID of the remote user whose audio state changes.
state	State of the remote audio. See REMOTE_AUDIO_STATE.
reason	The reason of the remote audio state change. See REMOTE_AUDIO_STATE_REASON.
elapsed	Time elapsed (ms) from the local user calling the joinChannel method until the SDK triggers this callback.

◆ onActiveSpeaker()

virtual void agora::rtc::IChannelEventHandler::onActiveSpeaker	(	IChannel *	rtcChannel,
		uid_t	uid
	)

inlinevirtual

Reports which user is the loudest speaker.

If the user enables the audio volume indication by calling the enableAudioVolumeIndication method, 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 the enableAudioVolumeIndication method.
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

rtcChannel	IChannel
uid	User ID of the active speaker. A `uid` of 0 represents the local user.

◆ onVideoSizeChanged()

virtual void agora::rtc::IChannelEventHandler::onVideoSizeChanged	(	IChannel *	rtcChannel,
		uid_t	uid,
		int	width,
		int	height,
		int	rotation
	)

inlinevirtual

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

Parameters

rtcChannel	IChannel
uid	User ID of the remote user or local user (0) whose video size or rotation changes.
width	New width (pixels) of the video.
height	New height (pixels) of the video.
rotation	New rotation of the video [0 to 360).

◆ onRemoteVideoStateChanged()

virtual void agora::rtc::IChannelEventHandler::onRemoteVideoStateChanged	(	IChannel *	rtcChannel,
		uid_t	uid,
		REMOTE_VIDEO_STATE	state,
		REMOTE_VIDEO_STATE_REASON	reason,
		int	elapsed
	)

inlinevirtual

Occurs when the remote video state changes.

Parameters

rtcChannel	IChannel
uid	ID of the remote user whose video state changes.
state	State of the remote video. See REMOTE_VIDEO_STATE.
reason	The reason of the remote video state change. See REMOTE_VIDEO_STATE_REASON.
elapsed	Time elapsed (ms) from the local user calling the joinChannel method until the SDK triggers this callback.

◆ onStreamMessage()

virtual void agora::rtc::IChannelEventHandler::onStreamMessage	(	IChannel *	rtcChannel,
		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.

The SDK triggers this callback when the local user receives the stream message that the remote user sends by calling the sendStreamMessage method.

Parameters

rtcChannel	IChannel
uid	User ID of the remote user sending the message.
streamId	Stream ID.
data	The data received by the local user.
length	Length of the data in bytes.

◆ onStreamMessageError()

virtual void agora::rtc::IChannelEventHandler::onStreamMessageError	(	IChannel *	rtcChannel,
		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.

The SDK triggers this callback when the local user fails to receive the stream message that the remote user sends by calling the sendStreamMessage method.

Parameters

rtcChannel	IChannel
uid	User ID of the remote user sending the message.
streamId	Stream ID.
code	Error code: ERROR_CODE_TYPE.
missed	Number of lost messages.
cached	Number of incoming cached messages when the data stream is interrupted.

◆ onChannelMediaRelayStateChanged()

virtual void agora::rtc::IChannelEventHandler::onChannelMediaRelayStateChanged	(	IChannel *	rtcChannel,
		CHANNEL_MEDIA_RELAY_STATE	state,
		CHANNEL_MEDIA_RELAY_ERROR	code
	)

inlinevirtual

Occurs when the state of the media stream relay changes.

The SDK returns the state of the current media relay with any error message.

Parameters

rtcChannel	IChannel
state	The state code in CHANNEL_MEDIA_RELAY_STATE.
code	The error code in CHANNEL_MEDIA_RELAY_ERROR.

◆ onChannelMediaRelayEvent()

virtual void agora::rtc::IChannelEventHandler::onChannelMediaRelayEvent	(	IChannel *	rtcChannel,
		CHANNEL_MEDIA_RELAY_EVENT	code
	)

inlinevirtual

Reports events during the media stream relay.

Parameters

rtcChannel	IChannel
code	The event code in CHANNEL_MEDIA_RELAY_EVENT.

◆ onRtmpStreamingStateChanged()

virtual void agora::rtc::IChannelEventHandler::onRtmpStreamingStateChanged	(	IChannel *	rtcChannel,
		const char *	url,
		RTMP_STREAM_PUBLISH_STATE	state,
		RTMP_STREAM_PUBLISH_ERROR	errCode
	)

inlinevirtual

Occurs when the state of the RTMP streaming changes.

The SDK triggers this callback to report the result of the local user calling the addPublishStreamUrl or removePublishStreamUrl method.

This callback indicates the state of the RTMP streaming. When exceptions occur, you can troubleshoot issues by referring to the detailed error descriptions in the errCode parameter.

Parameters

rtcChannel	IChannel
url	The RTMP URL address.
state	The RTMP streaming state. See: RTMP_STREAM_PUBLISH_STATE.
errCode	The detailed error information for streaming. See: RTMP_STREAM_PUBLISH_ERROR.

◆ onTranscodingUpdated()

virtual void agora::rtc::IChannelEventHandler::onTranscodingUpdated ( IChannel * rtcChannel )

inlinevirtual

Occurs when the publisher's transcoding is updated.

When the LiveTranscoding class in the setLiveTranscoding method updates, the SDK triggers the onTranscodingUpdated callback to report the update information to the local host.

Note: If you call the setLiveTranscoding method to set the LiveTranscoding class for the first time, the SDK does not trigger the onTranscodingUpdated callback.

Parameters

rtcChannel IChannel

◆ onStreamInjectedStatus()

virtual void agora::rtc::IChannelEventHandler::onStreamInjectedStatus	(	IChannel *	rtcChannel,
		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

rtcChannel	IChannel
url	The URL address of the externally injected stream.
uid	User ID.
status	State of the externally injected stream: INJECT_STREAM_STATUS.

◆ onRemoteSubscribeFallbackToAudioOnly()

virtual void agora::rtc::IChannelEventHandler::onRemoteSubscribeFallbackToAudioOnly	(	IChannel *	rtcChannel,
		uid_t	uid,
		bool	isFallbackOrRecover
	)

inlinevirtual

Occurs when the remote media stream falls back to audio-only stream due to poor network conditions or switches back to the video stream 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 remote media stream falls back to audio-only mode due to poor uplink conditions, or when the remote media stream switches back to the video after the uplink network condition improves.

Note: Once the remote 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

rtcChannel	IChannel
uid	ID of the remote user sending the stream.
isFallbackOrRecover	Whether 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.

◆ onConnectionStateChanged()

virtual void agora::rtc::IChannelEventHandler::onConnectionStateChanged	(	IChannel *	rtcChannel,
		CONNECTION_STATE_TYPE	state,
		CONNECTION_CHANGED_REASON_TYPE	reason
	)

inlinevirtual

Occurs when the connection state between the SDK and the server changes.

Parameters

rtcChannel	IChannel
state	See CONNECTION_STATE_TYPE.
reason	See CONNECTION_CHANGED_REASON_TYPE.

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~IChannelEventHandler()

Member Function Documentation

◆ onChannelWarning()

◆ onChannelError()

◆ onJoinChannelSuccess()

◆ onRejoinChannelSuccess()

◆ onLeaveChannel()

◆ onClientRoleChanged()

◆ onUserJoined()

◆ onUserOffline()

◆ onConnectionLost()

◆ onRequestToken()

◆ onTokenPrivilegeWillExpire()

◆ onRtcStats()

◆ onNetworkQuality()

◆ onRemoteVideoStats()

◆ onRemoteAudioStats()

◆ onRemoteAudioStateChanged()

◆ onActiveSpeaker()

◆ onVideoSizeChanged()

◆ onRemoteVideoStateChanged()

◆ onStreamMessage()

◆ onStreamMessageError()

◆ onChannelMediaRelayStateChanged()

◆ onChannelMediaRelayEvent()

◆ onRtmpStreamingStateChanged()

◆ onTranscodingUpdated()

◆ onStreamInjectedStatus()

◆ onRemoteSubscribeFallbackToAudioOnly()

◆ onConnectionStateChanged()