Network and Others

complain

Allows users to report call quality issues after the call ends.

virtual int complain(const char* callId, const char* description) = 0;

Call this method after the user leaves the channel.

Parameters

callId
The call ID of the current call. You can obtain it by calling getCallId.
description
(Optional) Description of the call. The string length should be less than 800 bytes.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -1: General error (no specific reason).
    • -2: Invalid parameter.
    • -7: This method is called before IRtcEngine is initialized.

enableEncryption

Enables or disables the built-in encryption feature.

virtual int enableEncryption(bool enabled, const EncryptionConfig& config) = 0;

After the user leaves the channel, the SDK automatically disables the built-in encryption feature. To enable it again, call this method before the user rejoins the channel.

Note:
  • All users in the same channel must set the same encryption configuration when calling this method.
  • Once built-in encryption is enabled, the media streaming feature is not available.

Scenario

Applicable to scenarios with high security requirements.

Timing

Call this method before joining a channel.

Parameters

enabled
Whether to enable the built-in encryption feature:
  • true: Enable built-in encryption.
  • false: (Default) Disable built-in encryption.
config
Built-in encryption configuration. See EncryptionConfig.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -2: Invalid parameter. Please pass in valid parameters.
    • -4: Incorrect encryption mode or failed to load external encryption library. Please check the enum value or reload the external encryption library.
    • -7: SDK not initialized. Please initialize the IRtcEngine instance before calling this method.

enableEncryptionEx

Enables or disables built-in encryption.

virtual int enableEncryptionEx(const RtcConnection& connection, bool enabled, const EncryptionConfig& config) = 0;

After a user leaves the channel, the SDK automatically disables built-in encryption. To enable it again, call this method before the user rejoins the channel.

Note:
  • All users in the same channel must use the same encryption configuration when calling this method.
  • Built-in encryption cannot be used together with the CDN live streaming feature.

Scenario

Applicable to multi-channel scenarios or scenarios with high security requirements.

Timing

Call this method before joining a channel.

Parameters

connection
Connection information. See RtcConnection.
enabled
Whether to enable built-in encryption:
  • true: Enable built-in encryption.
  • false: (Default) Disable built-in encryption.
config
Encryption configuration. See EncryptionConfig.

Return Values

  • 0: Success.
  • < 0: Failure.

enableWebSdkInteroperability

Enables interoperability with the Agora Web SDK (for Live Streaming only).

virtual int enableWebSdkInteroperability(bool enabled) __deprecated = 0;
Deprecated
This method is deprecated. The SDK automatically enables interoperability with the Web SDK. No need to call this method.

You can call this method to enable or disable interoperability with the Agora Web SDK. If there are Web SDK users in the channel, you must call this method; otherwise, the video of Native users will appear black on the web. This method only applies to Live Streaming. In Voice Call, interoperability is enabled by default.

Parameters

enabled
Whether to enable interoperability:
  • true: Enable interoperability.
  • false: (default) Disable interoperability.

Return Values

  • 0: Success.
  • < 0: Failure.

getCallId

Gets the current call ID.

virtual int getCallId(agora::util::AString& callId) = 0;

When a user joins a channel on the client, the SDK generates a callId to identify the call. You can call this method to get the callId and pass it to methods such as rate and complain.

Timing

Call this method after joining a channel.

Parameters

callId
Output parameter. The callId of the current call.

Return Values

  • 0: Success.
  • < 0: Failure.

getCallIdEx

Retrieves the call ID corresponding to the connection ID.

virtual int getCallIdEx(agora::util::AString& callId, const RtcConnection& connection) = 0;

When a user joins a channel on the client, the SDK generates a callId to identify the call. You can call this method to get the callId and pass it to methods such as rate and complain.

Scenario

This method is applicable in multi-channel scenarios.

Timing

Call this method after joining a channel.

Parameters

callId
Output parameter. The callId of the current call.
connection
Connection information. See RtcConnection.

Return Values

  • 0: Success.
  • < 0: Failure.

getConnectionState

Gets the current SDK connection state.

virtual CONNECTION_STATE_TYPE getConnectionState() = 0;

Timing

This method can be called before or after joining a channel.

Return Values

If the method call succeeds, returns the current connection state. See CONNECTION_STATE_TYPE.

getConnectionStateEx

Gets the current connection state of the SDK.

virtual CONNECTION_STATE_TYPE getConnectionStateEx(const RtcConnection& connection) = 0;

Scenario

This method applies to multi-channel scenarios.

Timing

You can call this method before or after joining a channel.

Parameters

connection
Connection information. See RtcConnection.

Return Values

Current connection state. See CONNECTION_STATE_TYPE.

getCurrentMonotonicTimeInMs

Gets the SDK's current monotonic time.

virtual int64_t getCurrentMonotonicTimeInMs() = 0;

In custom video or audio capture scenarios, to ensure audio-video sync, call this method to get the SDK's current monotonic time (in milliseconds) and pass it into the timestamp parameter of the captured VideoFrame or AudioFrame. Monotonic time refers to a time sequence that increases monotonically over time.

Timing

You can call this method before or after joining a channel.

Return Values

  • ≥ 0: Success. Returns the SDK's current monotonic time in milliseconds.
  • < 0: Failure.

getErrorDescription

getErrorDescription: gets the warning or error description.

virtual const char* getErrorDescription(int code) = 0;

Parameters

code
Error code reported by the SDK.

Return Values

  • On success, returns the description string corresponding to the error code.
  • On failure, returns an empty string.

getNetworkType

Gets the local network connection type.

virtual int getNetworkType() = 0;
Note: You can call the getNetworkType method before or after joining a channel.

Return Values

  • 0: Success. Returns the local network connection type.
    • 0: SDK is disconnected from the network.
    • 1: LAN.
    • 2: Wi-Fi (including hotspot).
    • 3: Mobile 2G.
    • 4: Mobile 3G.
    • 5: Mobile 4G.
    • 6: Mobile 5G.
  • < 0: Failure.
    • -1: Unknown network type.

getNtpWallTimeInMs

Gets the current NTP (Network Time Protocol) time.

virtual uint64_t getNtpWallTimeInMs() = 0;

In real-time chorus scenarios, especially when multiple receivers experience inconsistent downlink due to network issues, you can call this method to get the current NTP time as a reference to align lyrics and music across receivers for synchronized chorus.

Return Values

If the method call succeeds, returns the current NTP time as a Unix timestamp in milliseconds.

getVersion

Gets the SDK version number.

virtual const char* getVersion(int* build) = 0;

Parameters

build
Output parameter that represents the build index of the SDK.

Return Values

  • On success, returns the SDK version string.
  • On failure, returns an empty string.

isFeatureAvailableOnDevice

Checks whether the current device supports the specified advanced feature.

virtual bool isFeatureAvailableOnDevice(FeatureType type) = 0;
Since
Available since v4.3.0.

You can use this method to determine whether the current device meets the performance requirements for using advanced features such as virtual background and beauty effects, thereby avoiding performance degradation or feature unavailability on low-end devices. Based on the return result, you can decide whether to display or enable the corresponding feature button, or prompt the user if the device performance is insufficient.

Parameters

type
The type of advanced feature. See FeatureType.

Return Values

  • true: The current device supports the specified feature.
  • false: The current device does not support the specified feature.

queryDeviceScore

Queries the device score.

virtual int queryDeviceScore() = 0;

In high-definition or ultra-high-definition video scenarios, you can call this method to query the device score. If the returned score is low (e.g., below 60), it is recommended to lower the video resolution to avoid affecting the video experience. Different business scenarios may have different minimum requirements for device scores. For specific recommendations, contact technical support.

Return Values

  • On success, returns the current device score in the range [0, 100]. A higher score indicates better device performance. Most devices have scores between 60 and 100.
  • < 0: Failure.

queryInterface

Gets the pointer to the specified interface.

virtual int queryInterface(INTERFACE_ID_TYPE iid, void** inter) = 0;

Parameters

iid
Interface ID. See INTERFACE_ID_TYPE.
inter
Output parameter that represents the pointer to the specified interface.

Return Values

  • 0: Success.
  • < 0: Failure.

rate

Allows users to rate the call after it ends.

virtual int rate(const char* callId, int rating, const char* description) = 0;
Note: Make sure to call this method after leaving the channel.

Parameters

callId
The ID of the current call. You can obtain it by calling getCallId.
rating
Rating value, ranging from 1 (lowest) to 5 (highest).
description
(Optional) Description of the call. The string length should be less than 800 bytes.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -1: General error (no specific reason).
    • -2: Invalid parameter.

registerPacketObserver

Registers a packet observer.

virtual int registerPacketObserver(IPacketObserver* observer) = 0;

Call this method to register a packet observer. When the Agora SDK triggers the IPacketObserver callback for voice or video packet transmission, you can use this method to process packets, such as encryption or decryption.

Note:
  • The size of the packet sent to the network after processing must not exceed 1200 bytes, otherwise the SDK may fail to send the packet.
  • Make sure both the sender and receiver call this method; otherwise, undefined behavior such as no audio or black screen may occur.
  • Agora does not recommend calling this method when using media streaming or recording features.
  • Call this method before joining a channel.

Parameters

observer
Packet observer. See IPacketObserver.

Return Values

  • 0: Success.
  • < 0: Failure.

sendCustomReportMessage

Sends a custom report message.

virtual int sendCustomReportMessage(const char* id, const char* category, const char* event, const char* label, int value) = 0;

This feature is in testing. It supports sending and analyzing custom messages and is currently available for free trial. In the test version, up to 10 messages can be sent within 6 seconds, each message no more than 256 bytes, and each string no more than 100 bytes. To try this feature, please contact sales to discuss the custom message format.

Parameters

id
The unique identifier of the message.
category
The category of the message.
event
The event name.
label
The message label.
value
The value of the message.

Return Values

  • 0: Success.
  • < 0: Failure.

sendCustomReportMessageEx

Supports reporting and analyzing custom messages.

virtual int sendCustomReportMessageEx(const char* id, const char* category, const char* event, const char* label, int value, const RtcConnection& connection) = 0;

This feature is currently in the testing phase and is available for free trial. In the test version, you can report up to 10 messages within 6 seconds. Each message must not exceed 256 bytes, and each string must not exceed 100 bytes. To try this feature, contact sales and discuss the format of the custom messages with us.

Scenario

This method applies to multi-channel scenarios.

Parameters

id
The unique identifier of the custom message.
category
The category of the custom message.
event
The event name of the custom message.
label
The label of the custom message.
value
The value of the custom message.
connection
RtcConnection object. See RtcConnection.

Return Values

  • 0: Success.
  • < 0: Failure.

setAVSyncSource

Sets audio-video synchronization at the sender side.

virtual int setAVSyncSource(const char* channelId, uid_t uid) = 0;

Users may use two separate devices to send audio and video streams respectively. To ensure audio-video sync at the receiver side, you can call this method on the video sender and pass in the channel name and user ID of the audio sender. The SDK adjusts the video stream based on the audio stream's timestamp, ensuring sync even if the two devices use different uplink networks (e.g., Wi-Fi and 4G).

Note: Agora recommends calling this method before joining a channel.

Parameters

channelId
Channel name of the audio sender.
uid
User ID of the audio sender.

Return Values

  • 0: Success.
  • < 0: Failure.

setCloudProxy

Sets the cloud proxy service.

virtual int setCloudProxy(CLOUD_PROXY_TYPE proxyType) = 0;
Since
Added in v3.3.0.

When a user's network access is restricted by a firewall, you need to configure the firewall to allow access to specific IP addresses and ports provided by Agora, then call this method to enable the cloud proxy and set the proxy type using the proxyType parameter. After successfully connecting to the cloud proxy, the SDK triggers the onConnectionStateChanged callback with state CONNECTION_STATE_CONNECTING and reason CONNECTION_CHANGED_SETTING_PROXY_SERVER. To disable an already set cloud proxy, call setCloudProxy(NONE_PROXY). To change the cloud proxy type, first call setCloudProxy(NONE_PROXY), then call setCloudProxy again to set a new proxyType.

Note:
  • It is recommended to call this method before joining a channel.
  • When the user is behind a firewall and using forced UDP cloud proxy, CDN streaming and cross-channel media relay are not available.
  • When using forced TCP cloud proxy, calling startAudioMixing to play online music files over HTTP will result in an error. CDN streaming and cross-channel media relay use TCP-based cloud proxy.

Related Callbacks

After successfully connecting to the cloud proxy, the SDK triggers the onConnectionStateChanged callback with state CONNECTION_STATE_CONNECTING and reason CONNECTION_CHANGED_SETTING_PROXY_SERVER.

Parameters

proxyType
Cloud proxy type. See CLOUD_PROXY_TYPE.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -2: Invalid parameter.
    • -7: SDK not initialized.

setLocalAccessPoint

Configures access to the Agora private media server access module.

virtual int setLocalAccessPoint(const LocalAccessPointConfiguration& config) = 0;

After successfully deploying the Agora private media server and integrating the 4.x RTC SDK in the intranet client, you can call this method to specify the local access point and assign the access module to the SDK.

Note: This method only takes effect after deploying the Agora hybrid cloud solution. Contact sales for more details and to deploy the hybrid cloud.

Timing

You must call this method before joining a channel.

Parameters

config
Local access point configuration. See LocalAccessPointConfiguration.

Return Values

  • 0: Success.
  • < 0: Failure.

setLogFile

Sets the SDK log output file path.

virtual int setLogFile(const char* filePath) = 0;
Deprecated
This method is deprecated. Use the context parameter in initialize to set the log file path instead.

Specifies the file path for SDK log output. The log file records all log data during SDK operation. You must call this method immediately after calling initialize, otherwise the log output may be incomplete.

Note: Make sure the directory for the log file exists and has write permissions.

Timing

You must call this method immediately after calling initialize, otherwise the log output may be incomplete.

Parameters

filePath
The full path of the log file, encoded in UTF-8.

Return Values

  • 0: Success.
  • < 0: Failure.

setLogFileSize

Sets the log file size.

virtual int setLogFileSize(unsigned int fileSizeInKBytes) = 0;
Deprecated
This method is deprecated. Use the logConfig parameter in initialize to set the log file size instead.
By default, the SDK generates five SDK log files and five API call log files, as follows:
  • SDK log files: agorasdk.log, agorasdk.1.log, agorasdk.2.log, agorasdk.3.log, and agorasdk.4.log.
  • API call log files: agoraapi.log, agoraapi.1.log, agoraapi.2.log, agoraapi.3.log, and agoraapi.4.log.
  • Each log file has a default size of 2,048 KB and uses UTF-8 encoding.
  • The SDK writes the latest logs to agorasdk.log or agoraapi.log.
  • When agorasdk.log is full, the SDK handles the log files in the following order:
    1. Delete agorasdk.4.log (if it exists).
    2. Rename agorasdk.3.log to agorasdk.4.log.
    3. Rename agorasdk.2.log to agorasdk.3.log.
    4. Rename agorasdk.1.log to agorasdk.2.log.
    5. Create a new agorasdk.log file.
  • The rotation rule for agoraapi.log is the same as for agorasdk.log.
Note: This method only sets the size of the agorasdk.log file and does not affect the agoraapi.log file.

Parameters

fileSizeInKBytes
The size of the agorasdk.log file in KB. The valid range is [128, 20480]. The default value is 2,048 KB. If the value is less than 128 KB, the SDK automatically adjusts it to 128 KB; if the value is greater than 20,480 KB, the SDK adjusts it to 20,480 KB.

Return Values

  • 0: Success.
  • < 0: Failure.

setLogFilter

Sets the SDK log output level.

virtual int setLogFilter(unsigned int filter) = 0;
Deprecated
This method is deprecated. Use the logConfig parameter in initialize to set the log filter level instead.

You can use one or more log filter levels in combination to set the SDK log output level. The log levels are ordered as LOG_FILTER_OFF, LOG_FILTER_CRITICAL, LOG_FILTER_ERROR, LOG_FILTER_WARN, LOG_FILTER_INFO, and LOG_FILTER_DEBUG. When you select a level, logs of that level and higher will be output. For example, if you set the log level to LOG_FILTER_WARN, you will see logs of LOG_FILTER_CRITICAL, LOG_FILTER_ERROR, and LOG_FILTER_WARN.

Parameters

filter
The SDK log output level. See LOG_FILTER_TYPE.

Return Values

  • 0: Success.
  • < 0: Failure.

setLogLevel

Sets the SDK log level.

virtual int setLogLevel(commons::LOG_LEVEL level) = 0;
Deprecated
This method is deprecated. Use the context parameter in initialize to set the log level instead.

Select a log level to view logs of that level and above.

Parameters

level
The log level. See LOG_LEVEL.

Return Values

  • 0: Success.
  • < 0: Failure.

setParameters

Provides technical preview features or special customization for the SDK via JSON configuration.

virtual int setParameters(const char* parameters) = 0;

Contact technical support to obtain the JSON configuration method.

Parameters

parameters
Pointer to a set of parameters in JSON string format.

Return Values

  • 0: Success.
  • < 0: Failure.

setRemoteSubscribeFallbackOption

Sets the fallback option for the subscribed video stream based on network conditions.

virtual int setRemoteSubscribeFallbackOption(STREAM_FALLBACK_OPTIONS option) = 0;

Unstable networks affect the audio and video quality in video calls or live interactive streaming. You can set option to STREAM_FALLBACK_OPTION_VIDEO_STREAM_LOW or STREAM_FALLBACK_OPTION_AUDIO_ONLY. When the downlink network cannot support both audio and video, the SDK automatically switches the video from high-quality to low-quality, or disables video to ensure audio quality. The SDK continuously monitors network conditions and resumes audio and video subscription when the network improves.

Related Callbacks

When the subscribed video stream falls back to audio-only or recovers from audio-only to audio and video, the SDK triggers the onRemoteSubscribeFallbackToAudioOnly callback.

Parameters

option
The fallback option for the subscribed stream. See STREAM_FALLBACK_OPTIONS.

Return Values

  • 0: Success.
  • < 0: Failure.

startEchoTest

Starts the audio and video call loop test.

virtual int startEchoTest(const EchoTestConfiguration& config) = 0;
You can call this method to perform an audio and video call loop test to check whether the local audio and video devices and the uplink and downlink network are working properly. After the test starts, speak or face the camera, and the audio or video will be played back after about two seconds.
  • If the audio plays back correctly, the audio device and network are working properly.
  • If the video plays back correctly, the video device and network are working properly.
Note:
  • When calling this method in a channel, make sure no audio or video stream is being published.
  • After calling this method, you must call stopEchoTest to end the test. Otherwise, you cannot perform another loop test or join a channel.
  • In a live broadcast scenario, this method is only applicable to the broadcaster role.

Timing

You can call this method before or after joining a channel.

Parameters

config
The configuration for the audio and video call loop test. See EchoTestConfiguration.

Return Values

  • 0: Success.
  • < 0: Failure.

startLastmileProbeTest

Starts the last-mile network probe test.

virtual int startLastmileProbeTest(const LastmileProbeConfig& config) = 0;
Call sequence: Do not call other methods before receiving the onLastmileQuality and onLastmileProbeResult callbacks, or these callbacks may be interrupted. Related callbacks: After successfully calling this method, the SDK triggers the following two callbacks in sequence:
  • onLastmileQuality: Triggered within about two seconds based on network conditions. This callback evaluates network quality and is closer to user experience.
  • onLastmileProbeResult: Triggered within about 30 seconds based on network conditions. This callback returns real-time statistics of the network condition, providing a more objective view.

Parameters

config
The configuration for the last-mile network probe test. See LastmileProbeConfig.

Return Values

  • 0: Success.
  • < 0: Failure.

stopEchoTest

Stops the audio call test.

virtual int stopEchoTest() = 0;

After calling startEchoTest, you must call this method to end the test. Otherwise, you cannot perform another loop test or join a channel.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -5 (ERR_REFUSED): Failed to stop the echo test, possibly not running.

stopLastmileProbeTest

Stops the last-mile network probe test.

virtual int stopLastmileProbeTest() = 0;

Return Values

  • 0: Success.
  • < 0: Failure.

onConnectionBanned

Callback triggered when the connection is banned by the Agora server.

virtual void onConnectionBanned() __deprecated {}
Deprecated
This method is deprecated. Use onConnectionStateChanged instead.

onConnectionInterrupted

onConnectionInterrupted callback.

virtual void onConnectionInterrupted() __deprecated {}
Deprecated
This method is deprecated. Use onConnectionStateChanged instead.

This callback is triggered when the SDK loses connection to the server for more than 4 seconds after establishing a connection. After triggering, the SDK attempts to reconnect. You can use this callback to implement a popup reminder.

Note: The difference between onConnectionInterrupted and onConnectionLost is as follows:
  • onConnectionInterrupted is triggered when the SDK loses connection to the server for more than 4 seconds after successfully joining a channel.
  • onConnectionLost is triggered when the SDK loses connection to the server for more than 10 seconds, regardless of whether it has joined a channel.
If the SDK fails to rejoin the channel within 20 minutes after losing connection to the Agora edge server, it stops trying to reconnect.

Trigger Timing

Triggered when the SDK loses connection to the server for more than 4 seconds.

onConnectionLost

onConnectionLost callback. Triggered when the SDK fails to reconnect to the Agora edge server within 10 seconds after the connection is lost.

virtual void onConnectionLost() {}

After calling joinChannel, if the SDK loses connection to the Agora edge server and fails to reconnect within 10 seconds, this callback is triggered. It is triggered regardless of whether the user is in a channel. If reconnection fails within 20 minutes, the SDK stops trying to rejoin the channel.

Trigger Timing

Occurs when the SDK fails to reconnect to the Agora edge server within 10 seconds after the connection is lost.

onConnectionStateChanged

Callback triggered when the network connection state changes.

virtual void onConnectionStateChanged(CONNECTION_STATE_TYPE state, CONNECTION_CHANGED_REASON_TYPE reason)

This callback is triggered when the network connection state changes, reporting the current connection state and the reason for the change.

Parameters

state
The current connection state. See CONNECTION_STATE_TYPE.
reason
The reason for the connection state change. See CONNECTION_CHANGED_REASON_TYPE.

onEncryptionError

Callback for reporting built-in encryption errors.

virtual void onEncryptionError(ENCRYPTION_ERROR_TYPE errorType)

After calling enableEncryption to enable encryption, if an error occurs during encryption or decryption on the sender or receiver side, the SDK triggers this callback.

Parameters

errorType
The type of error. See ENCRYPTION_ERROR_TYPE.

onLastmileProbeResult

Callback for uplink and downlink last-mile network probe results.

virtual void onLastmileProbeResult(const LastmileProbeResult& result)

After calling startLastmileProbeTest, the SDK triggers this callback within 30 seconds.

Parameters

result
Uplink and downlink last-mile network probe test result. See LastmileProbeResult.

onLastmileQuality

Callback reporting the last-mile network quality of the local user.

virtual void onLastmileQuality(int quality) { (void)quality; }

This callback is triggered before joining a channel to report the network quality between the local user and the Agora edge server (i.e., last-mile network condition). After calling startLastmileProbeTest, the SDK triggers this callback.

Parameters

quality
Last-mile network quality. See QUALITY_TYPE.

onMultipathStats

Callback for multipath transmission statistics.

virtual void onMultipathStats(const MultipathStats& stats)
Since
Added since v4.6.0.

Trigger Timing

This callback is triggered after you set enableMultipath to true to enable multipath transmission.

Parameters

stats
Multipath transmission statistics. See MultipathStats.

onNetworkQuality

Reports the last-mile network quality of each user in the channel.

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

This callback reports the last-mile network condition of each user in the channel. Last-mile refers to the connection between the local device and the Agora edge server. The SDK triggers this callback every two seconds. If there are multiple users in the channel, the SDK triggers this callback multiple times. This callback reflects network quality by sending and receiving broadcast packets within the channel. To avoid broadcast storms and excessive data transmission, this callback reports the network quality of up to 4 remote users simultaneously by default.

Note: txQuality is UNKNOWN when the user is not sending a stream; rxQuality is UNKNOWN when the user is not receiving a stream.

Parameters

uid
User ID. Specifies the user whose network quality is being reported. A value of 0 indicates the local user.
txQuality
User's uplink network quality rating, evaluated based on uplink transmission bitrate, packet loss rate, average round-trip time (RTT), and jitter. This rating helps determine if the current uplink can support the selected video encoder configuration. For example, a 1000 Kbps uplink may support a 640 × 480 resolution at 15 fps but may not support resolutions higher than 1280 × 720. See QUALITY_TYPE.
rxQuality
User's downlink network quality rating, evaluated based on downlink packet loss rate, average RTT, and jitter. See QUALITY_TYPE.

onNetworkTypeChanged

Callback triggered when the local network type changes.

virtual void onNetworkTypeChanged(NETWORK_TYPE type)

You can use this callback to get the connection state and the reason for its change. When the network is disconnected, this callback helps determine whether the disconnection is due to a change in network type or poor network conditions.

Parameters

type
The type of local network connection. See NETWORK_TYPE.

onPermissionError

Reports when the SDK fails to obtain device permissions.

virtual void onPermissionError(PERMISSION_TYPE permissionType)

This callback is triggered when the SDK fails to obtain device permissions, and it reports the type of permission that could not be obtained.

Parameters

permissionType
The type of device permission. See PERMISSION_TYPE.

onPermissionGranted

Callback triggered when a permission is granted.

virtual void onPermissionGranted(agora::rtc::PERMISSION_TYPE permissionType) {}

Parameters

permissionType
Permission type. See PERMISSION_TYPE.

onProxyConnected

Proxy connection status callback.

virtual void onProxyConnected(const char* channel, uid_t uid, PROXY_TYPE proxyType, const char* localProxyIp, int elapsed)

onProxyConnected is used to monitor the SDK's connection status to the proxy. When the user calls setCloudProxy and successfully joins a channel, the SDK triggers this callback to report the user ID, proxy type, and time elapsed (ms) from calling joinChannel to the callback.

Parameters

channel
Channel name.
uid
User ID.
proxyType
Type of proxy connected. See PROXY_TYPE.
localProxyIp
Reserved parameter, not currently used.
elapsed
Time elapsed (ms) from calling joinChannel to this callback being triggered.

onReceiveAudioPacket

Callback triggered when the local user receives an audio packet.

virtual bool onReceiveAudioPacket(Packet& packet) = 0;

Parameters

packet
The received audio packet. See Packet.

Return Values

true: Audio packet received successfully. false: Audio packet is discarded.

onReceiveVideoPacket

Callback triggered when the local user receives a video packet.

virtual bool onReceiveVideoPacket(Packet& packet) = 0;

Parameters

packet
The received video packet. See Packet.

Return Values

true: Video packet received successfully. false: Video packet is discarded.

onRemoteSubscribeFallbackToAudioOnly

Callback triggered when the remote media stream switches between audio and video due to network changes.

virtual void onRemoteSubscribeFallbackToAudioOnly(uid_t uid, bool isFallbackOrRecover)
If you call setRemoteSubscribeFallbackOption and set option to STREAM_FALLBACK_OPTION_AUDIO_ONLY, the SDK triggers this callback in the following cases:
  • The subscribed video stream is downgraded to audio-only due to poor downlink network conditions.
  • The subscribed stream recovers to video when the network improves.
Note: When the remote media stream switches to a low-quality video stream due to weak network, you can monitor the switch between high-quality and low-quality video streams via the onRemoteVideoStats callback.

Parameters

uid
Remote user ID.
isFallbackOrRecover
Whether the media stream switched due to network changes:
  • true: The subscribed media stream was downgraded to audio-only due to poor network conditions.
  • false: The subscribed media stream recovered to video after the network improved.

onSendAudioPacket

Callback triggered when the local user sends an audio packet.

virtual bool onSendAudioPacket(Packet& packet) = 0;

Parameters

packet
The audio packet to be sent. See Packet.

Return Values

true: Audio packet sent successfully. false: Audio packet is discarded.

onSendVideoPacket

Callback triggered when the local user sends a video packet.

virtual bool onSendVideoPacket(Packet& packet) = 0;

Parameters

packet
The video packet to be sent. See Packet.

Return Values

true: Video packet sent successfully. false: Video packet is discarded.

onUplinkNetworkInfoUpdated

Callback triggered when uplink network information changes.

virtual void onUplinkNetworkInfoUpdated(const UplinkNetworkInfo& info)
Note: This callback applies only when pushing externally encoded H.264 video data to the SDK.

Parameters

info
Uplink network information. See UplinkNetworkInfo.