Network and Others
Introduces methods related to network and other methods and callbacks.
complain
Allows a user to complain about the call quality after a call ends.
virtual int complain(const char* callId, const char* description) = 0;
This method allows users to complain about the quality of the call. Call this method after the user leaves the channel.
Parameters
- callId
- The current call ID. You can get the call ID by calling getCallId.
- description
- (Optional) A description of the call. The string length should be less than 800 bytes.
Returns
- 0: Success.
- < 0: Failure.
- -2: The parameter is invalid.
- 3: The SDK is not ready. Possible reasons include the following:
- The initialization of IRtcEngine fails. Reinitialize the IRtcEngine.
- No user has joined the channel when the method is called. Please check your code logic.
- The user has not left the channel when the rate or complain method is called. Please check your code logic.
- The audio module is disabled. The program is not complete.
createDataStream [1/2]
Creates a data stream.
virtual int createDataStream(int* streamId, bool reliable, bool ordered) = 0;
Each user can create up to five data streams during the lifecycle of IRtcEngine. The data stream will be destroyed when leaving the channel, and the data stream needs to be recreated if needed.
- Call this method after joining a channel.
- Agora does not support setting reliable as
true
and ordered astrue
.
Parameters
- streamId
- Output parameter. Pointer to the ID of the created data stream.
- reliable
-
Whether or not the data stream is reliable:
true
: The recipients receive the data from the sender within five seconds. If the recipient does not receive the data within five seconds, the SDK triggers the onStreamMessageError callback and returns an error code.false
: There is no guarantee that the recipients receive the data stream within five seconds and no error message is reported for any delay or missing data stream.
- ordered
-
Whether or not the recipients receive the data stream in the sent order:
true
: The recipients receive the data in the sent order.false
: The recipients do not receive the data in the sent order.
Returns
- 0: The data stream is successfully created.
- < 0: Failure.
createDataStream [2/2]
Creates a data stream.
virtual int createDataStream(int* streamId, DataStreamConfig& config) = 0;
Creates a data stream. Each user can create up to five data streams in a single channel.
Compared with createDataStream [1/2], this method does not support data reliability. If a data packet is not received five seconds after it was sent, the SDK directly discards the data.
Parameters
- streamId
- Output parameter. Pointer to the ID of the created data stream.
- config
- The configurations for the data stream. See DataStreamConfig.
Returns
- 0: The data stream is successfully created.
- < 0: Failure.
enableEncryption
Enables/Disables the built-in encryption.
virtual int enableEncryption(bool enabled, const EncryptionConfig& config) = 0;
In scenarios requiring high security, Agora recommends calling this method to enable the built-in encryption before joining a channel.
All users in the same channel must use the same encryption mode and encryption key. After the user leaves the channel, the SDK automatically disables the built-in encryption. To enable the built-in encryption, call this method before the user joins the channel again.
Parameters
- enabled
-
Whether to enable built-in encryption:
- true: Enable the built-in encryption.
- false: Disable the built-in encryption.
- config
- Built-in encryption configurations. See EncryptionConfig.
Returns
- 0: Success.
- < 0: Failure.
- -2: An invalid parameter is used. Set the parameter with a valid value.
- -4: The built-in encryption mode is incorrect or the SDK fails to load the external encryption library. Check the enumeration or reload the external encryption library.
- -7: The SDK is not initialized. Initialize the IRtcEngine instance before calling this method.
enableExtension
Enables/Disables an extension.
virtual int enableExtension(
const char* provider, const char* extension, bool enable=true, agora::media::MEDIA_SOURCE_TYPE type = agora::media::UNKNOWN_MEDIA_SOURCE) = 0;
To call this method, call it immediately after initializing the IRtcEngine object.
- If you want to enable multiple extensions, you need to call this method multiple times.
- The data processing order of different extensions in the SDK is determined by the order in which the extensions are enabled. That is, the extension that is enabled first will process the data first.
Parameters
- provider
- The name of the extension provider.
- extension
- The name of the extension.
- enable
-
Whether to enable the extension:
true
: Enable the extension.false
: Disable the extension.
- type
- Type of media source. See MEDIA_SOURCE_TYPE.Attention: In this method, this parameter supports only the following two settings:
- The default value is UNKNOWN_MEDIA_SOURCE.
- If you want to use the second camera to capture video, set this parameter to SECONDARY_CAMERA_SOURCE.
Returns
- 0: Success.
- < 0: Failure.
enableWebSdkInteroperability
Enables interoperability with the Agora Web SDK (applicable only in the live streaming scenarios).
virtual int enableWebSdkInteroperability(bool enabled) = 0;
- Deprecated:
- The SDK automatically enables interoperability with the Web SDK, so you no longer need to call this method.
This method enables or disables interoperability with the Agora Web SDK. If the channel has Web SDK users, ensure that you call this method, or the video of the Native user will be a black screen for the Web user.
This method is only applicable in live streaming scenarios, and interoperability is enabled by default in communication scenarios.
Parameters
- enabled
- Whether to enable interoperability with the Agora Web SDK.
true
: Enable interoperability.false
: (Default) Disable interoperability.
Returns
- 0: Success.
- < 0: Failure.
getCallId
Retrieves the call ID.
virtual int getCallId(agora::util::AString& callId) = 0;
When a user joins a channel on a client, a callId is generated to identify the call from the client. Some methods, such as rate and complain, must be called after the call ends to submit feedback to the SDK. These methods require the callId parameter.
Parameters
- callId
- Output parameter, the current call ID.
Returns
- 0: Success.
- < 0: Failure.
getErrorDescription
Gets the warning or error description.
virtual const char* getErrorDescription(int code) = 0;
Parameters
- code
- The error code or warning code reported by the SDK.
Returns
The specific error or warning description.
getExtensionProperty
Gets detailed information on the extensions.
virtual int getExtensionProperty(
const char* provider, const char* extension,
const char* key, char* value, int buf_len, agora::media::MEDIA_SOURCE_TYPE type = agora::media::UNKNOWN_MEDIA_SOURCE) = 0;
Parameters
- provider
- Output parameter. The name of the extension provider.
- extension
- Output parameter. The name of the extension.
- key
- Output parameter. The key of the extension.
- value
- Output parameter. The value of the extension key.
- type
- Source type of the extension. See MEDIA_SOURCE_TYPE.
- buf_len
- Maximum length of the JSON string indicating the extension property. The maximum value is 512 bytes.
Returns
- 0: Success.
- < 0: Failure.
getNetworkType
Gets the type of the local network connection.
virtual int getNetworkType() = 0;
- Since
- v4.0.1
You can use this method to get the type of network in use at any stage.
Returns
- ≥ 0: The method call is successful, and the local network connection type is returned.
- 0: The SDK disconnects from the network.
- 1: The network type is LAN.
- 2: The network type is Wi-Fi (including hotspots).
- 3: The network type is mobile 2G.
- 4: The network type is mobile 3G.
- 5: The network type is mobile 4G.
- 6: The network type is mobile 5G.
- < 0: The method call failed with an error code.
- -1: The network type is unknown.
getUserInfoByUid
Gets the user information by passing in the user ID.
virtual int getUserInfoByUid(uid_t uid, rtc::UserInfo* userInfo, const char* channelId = NULL, const char* localUserAccount = NULL) = 0;
After a remote user joins the channel, the SDK gets the UID and User Account of the remote user, caches them in a mapping table object, and triggers the onUserInfoUpdated callback on the local client. After receiving the callback, you can call this method to get the user account of the remote user from the UserInfo object by passing in the user ID.
Parameters
- uid
- The user ID.
- userInfo
- Input and output parameter. The UserInfo object that identifies the user information.
- Input: A UserInfo object.
- Output: A UserInfo object that contains the user account and user ID of the user.
- channelId
- The channel name. This parameter signifies the channel in which users engage in real-time audio and video interaction. Under the premise of the same App ID, users who fill in the same channel ID enter the same channel for audio and video interaction. The string length must be less than 64 bytes. Supported characters:
- All lowercase English letters: a to z.
- All uppercase English letters: A to Z.
- All numeric characters: 0 to 9.
- Space
- "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "= ", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","
- localUserAccount
- The user account of the local user.
Returns
- 0: Success.
- < 0: Failure.
getUserInfoByUserAccount
Gets the user information by passing in the User Account.
virtual int getUserInfoByUserAccount(const char* userAccount, rtc::UserInfo* userInfo, const char* channelId = NULL, const char* localUserAccount = NULL) = 0;
After a remote user joins the channel, the SDK gets the UID and User Account of the remote user, caches them in a mapping table object, and triggers the onUserInfoUpdated callback on the local client. After receiving the callback, you can call this method to get the user account of the remote user from the UserInfo object by passing in the user ID.
Parameters
- userAccount
- The user account.
- userInfo
- Input and output parameter. The UserInfo object that identifies the user information.
- Input: A UserInfo object.
- Output: A UserInfo object that contains the user account and user ID of the user.
- channelId
- The channel name. This parameter signifies the channel in which users engage in real-time audio and video interaction. Under the premise of the same App ID, users who fill in the same channel ID enter the same channel for audio and video interaction. The string length must be less than 64 bytes. Supported characters:
- All lowercase English letters: a to z.
- All uppercase English letters: A to Z.
- All numeric characters: 0 to 9.
- Space
- "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "= ", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","
- localUserAccount
- The user account of the local user.
Returns
- 0: Success.
- < 0: Failure.
getVersion
Gets the SDK version.
virtual const char* getVersion(int* build) = 0;
Parameters
- build
- The SDK build index.
Returns
The SDK version number. The format is a string.
loadExtensionProvider
Adds an extension to the SDK.
virtual int loadExtensionProvider(const char* path, bool unload_after_use = false) = 0;
Parameters
- path
- The extension library path and name. For example:
/library/libagora_segmentation_extension.dll
. - unload_after_use
- Whether to uninstall the current extension when you no longer using it:
true
: Uninstall the extension when the IRtcEngine is destroyed.false
: (Rcommended) Do not uninstall the extension until the process terminates.
Returns
- 0: Success.
- < 0: Failure.
queryInterface
Gets the pointer to the specified interface.
virtual int queryInterface(INTERFACE_ID_TYPE iid, void** inter) = 0;
Parameters
- iid
- The ID of the interface. See INTERFACE_ID_TYPE.
- inter
- Output parameter. The pointer to the specified interface.
Returns
- 0: Success.
- < 0: Failure.
rate
Allows a user to rate a call after the call ends.
virtual int rate(const char* callId,
int rating,
const char* description) = 0;
Parameters
- callId
- The current call ID. You can get the call ID by calling getCallId.
- rating
- The rating of the call. The value is between 1 (lowest score) and 5 (highest score). If you set a value out of this range, the SDK returns the -2 (
ERR_INVALID_ARGUMENT
) error. - description
- (Optional) A description of the call. The string length should be less than 800 bytes.
Returns
- 0: Success.
- < 0: Failure.
- -2 (
ERR_INVALID_ARGUMENT
). - -3 (
ERR_NOT_READY
).
- -2 (
registerExtension
Registers an extension.
virtual int registerExtension(const char* provider, const char* extension,
agora::media::MEDIA_SOURCE_TYPE type = agora::media::UNKNOWN_MEDIA_SOURCE) = 0;
- Since
- v4.1.0
Parameters
- provider
- The name of the extension provider.
- extension
- The name of the extension.
- type
- Type of media source. See MEDIA_SOURCE_TYPE.Attention: In this method, this parameter supports only the following two settings:
- The default value is UNKNOWN_MEDIA_SOURCE.
- If you want to use the second camera to capture video, set this parameter to SECONDARY_CAMERA_SOURCE.
Returns
- 0: Success.
- < 0: Failure.
registerLocalUserAccount
Registers a user account.
virtual int registerLocalUserAccount(const char* appId, const char* userAccount) = 0;
Once registered, the user account can be used to identify the local user when the user joins the channel. After the registration is successful, the user account can identify the identity of the local user, and the user can use it to join the channel.
After the user successfully registers a user account, the SDK triggers the onLocalUserRegistered callback on the local client, reporting the user ID and user account of the local user.
- Call registerLocalUserAccount to create a user account, and then call joinChannelWithUserAccount [2/2] to join the channel.
- Call the joinChannelWithUserAccount [2/2] method to join the channel.
The difference between the two ways is that the time elapsed between calling the registerLocalUserAccount method and joining the channel is shorter than directly calling joinChannelWithUserAccount [2/2].
- Ensure that you set the userAccount parameter; otherwise, this method does not take effect.
- Ensure that the userAccount is unique in the channel.
- To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure all the other users use the user ID too. The same applies to the user account. If a user joins the channel with the Agora Web SDK, ensure that the ID of the user is set to the same parameter type.
Parameters
- appId
- The App ID of your project on Agora Console.
- userAccount
-
The user account. This parameter is used to identify the user in the channel for real-time audio and video engagement. You need to set and manage user accounts yourself and ensure that each user account in the same channel is unique. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as NULL. Supported characters are (89 in total):
- The 26 lowercase English letters: a to z.
- The 26 uppercase English letters: A to Z.
- All numeric characters: 0 to 9.
- Space
- "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "= ", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","
Returns
- 0: Success.
- < 0: Failure.
registerPacketObserver
Registers a packet observer.
virtual int registerPacketObserver(IPacketObserver* observer) = 0;
Call this method registers a packet observer. When the Agora SDK triggers IPacketObserver callbacks registered by for voice or video packet transmission, you can call this method to process the packets, such as encryption and decryption.
- The size of the packet sent to the network after processing should not exceed 1200 bytes, otherwise, the SDK may fail to send the packet.
- Ensure that both receivers and senders call this method; otherwise, you may meet undefined behaviors such as no voice and black screen.
- When you use the Media Push or recording functions, Agora doesn't recommend calling this method.
- Call this method before joining a channel.
Parameters
- observer
- IPacketObserver.
Returns
- 0: Success.
- < 0: Failure.
sendCustomReportMessage
Reports customized messages.
virtual int sendCustomReportMessage(const char *id,
const char* category,
const char* event,
const char* label,
int value) = 0;
Agora supports reporting and analyzing customized messages. This function is in the beta stage with a free trial. The ability provided in its beta test version is reporting a maximum of 10 message pieces within 6 seconds, with each message piece not exceeding 256 bytes and each string not exceeding 100 bytes. To try out this function, contact support@agora.io and discuss the format of customized messages with us.
setCloudProxy
Sets the Agora cloud proxy service.
virtual int setCloudProxy(CLOUD_PROXY_TYPE proxyType) = 0;
When users' network access is restricted by a firewall, configure the firewall to allow specific IP addresses and ports provided by Agora; then, call this method to enable the cloud proxy and set the cloud proxy type with the proxyType parameter.
After successfully connecting to the cloud proxy, the SDK triggers the onConnectionStateChanged (CONNECTION_STATE_CONNECTING, CONNECTION_CHANGED_SETTING_PROXY_SERVER) callback.
To disable the cloud proxy that has been set, call the setCloudProxy (NONE_PROXY)
.
To change the cloud proxy type that has been set, call the setCloudProxy (NONE_PROXY)
first, and then call the setCloudProxy to set the proxyType you want.
- Agora recommends that you call this method before joining the channel or after leaving the channel.
- When a user is behind a firewall and uses the Force UDP cloud proxy, the services for the Media Push and cohosting across channels are not available.
- When you use the Force TCP cloud proxy, note that an error would occur when calling the startAudioMixing [2/2] method to play online music files in the HTTP protocol. The services for the Media Push and cohosting across channels use the cloud proxy with the TCP protocol.
Parameters
- proxyType
-
The type of the cloud proxy. See CLOUD_PROXY_TYPE.
This parameter is mandatory. The SDK reports an error if you do not pass in a value.
Returns
- 0: Success.
- < 0: Failure.
- -2: The parameter is invalid.
- -7: The SDK is not initialized.
setEncryptionMode
Sets the built-in encryption mode.
virtual int setEncryptionMode(const char* encryptionMode) = 0;
- Deprecated:
- Use enableEncryption instead.
The Agora SDK supports built-in encryption, which is set to the AES-128-GCM mode by default. Call this method to use other encryption modes. All users in the same channel must use the same encryption mode and secret. Refer to the information related to the AES encryption algorithm on the differences between the encryption modes.
Parameters
- encryptionMode
-
The following encryption modes:
- "
aes-128-xts
": 128-bit AES encryption, XTS mode. - "
aes-128-ecb
": 128-bit AES encryption, ECB mode. - "
aes-256-xts
": 256-bit AES encryption, XTS mode. - "
sm4-128-ecb
": 128-bit SM4 encryption, ECB mode. - "
aes-128-gcm
": 128-bit AES encryption, GCM mode. - "
aes-256-gcm
": 256-bit AES encryption, GCM mode. - "": When this parameter is set as null, the encryption mode is set as "
aes-128-gcm
" by default.
- "
Returns
- 0: Success.
- < 0: Failure.
setEncryptionSecret
Enables built-in encryption with an encryption password before users join a channel.
virtual int setEncryptionSecret(const char* secret) = 0;
- Deprecated:
- This method is deprecated. Use enableEncryption instead.
Before joining the channel, you need to call this method to set the secret parameter to enable the built-in encryption. All users in the same channel should use the same secret. The secret is automatically cleared once a user leaves the channel. If you do not specify the secret or secret is set as null, the built-in encryption is disabled.
- Do not use this method for CDN live streaming.
- For optimal transmission, ensure that the encrypted data size does not exceed the original data size + 16 bytes. 16 bytes is the maximum padding size for AES encryption.
Parameters
- secret
- The encryption password.
Returns
- 0: Success.
- < 0: Failure.
setExtensionProperty
Sets the properties of the extension.
virtual int setExtensionProperty(
const char* provider, const char* extension,
const char* key, const char* value, agora::media::MEDIA_SOURCE_TYPE type = agora::media::UNKNOWN_MEDIA_SOURCE) = 0;
After enabling the extension, you can call this method to set the properties of the extension.
Parameters
- provider
- The name of the extension provider.
- extension
- The name of the extension.
- key
- The key of the extension.
- value
- The value of the extension key.
- type
- Type of media source. See MEDIA_SOURCE_TYPE.Attention: In this method, this parameter supports only the following two settings:
- The default value is UNKNOWN_MEDIA_SOURCE.
- If you want to use the second camera to capture video, set this parameter to SECONDARY_CAMERA_SOURCE.
Returns
- 0: Success.
- < 0: Failure.
setExtensionProviderProperty
Sets the properties of the extension provider.
virtual int setExtensionProviderProperty(
const char* provider, const char* key, const char* value) = 0;
You can call this method to set the attributes of the extension provider and initialize the relevant parameters according to the type of the provider.
Call this method after enableExtension, and before enabling the audio (enableAudio/enableLocalAudio) or the video (enableVideo/enableLocalVideo).
Parameters
- provider
- The name of the extension provider.
- key
- The key of the extension.
- value
- The value of the extension key.
Returns
- 0: Success.
- < 0: Failure.
setLogFile
Sets the log file.
virtual int setLogFile(const char* filePath) = 0;
- Deprecated:
- Use the
mLogConfig
parameter in initialize method instead.
Specifies an SDK output log file. The log file records all log data for the SDK’s operation. Ensure that the directory for the log file exists and is writable.
Ensure that you call this method immediately after calling the initialize method to initialize the IRtcEngine, or the output log may not be complete.
Parameters
- filePath
- The complete path of the log files. These log files are encoded in UTF-8.
Returns
- 0: Success.
- < 0: Failure.
setLogFileSize
Sets the log file size.
virtual int setLogFileSize(unsigned int fileSizeInKBytes) = 0;
- Deprecated:
- Use the
logConfig
parameter in initialize instead.
By default, the SDK generates five SDK log files and five API call log files with the following rules:
- The SDK log files are:
agorasdk.log
,agorasdk.1.log
,agorasdk.2.log
,agorasdk.3.log
, andagorasdk.4.log
. - The API call log files are:
agoraapi.log
,agoraapi.1.log
,agoraapi.2.log
,agoraapi.3.log
, andagoraapi.4.log
. - The default size for each SDK log file is 1,024 KB; the default size for each API call log file is 2,048 KB. These log files are encoded in UTF-8.
- The SDK writes the latest logs in
agorasdk.log
oragoraapi.log
. - When
agorasdk.log
is full, the SDK processes the log files in the following order:- Delete the
agorasdk.4.log
file (if any). - Rename
agorasdk.3.log
toagorasdk.4.log
. - Rename
agorasdk.2.log
toagorasdk.3.log
. - Rename
agorasdk.1.log
toagorasdk.2.log
. - Create a new
agorasdk.log
file.
- Delete the
- The overwrite rules for the
agoraapi.log
file are the same as foragorasdk.log
.
This method is used to set the size of the agorasdk.log
file only and does not effect the agoraapi.log file
.
Parameters
- fileSizeInKBytes
-
The size (KB) of an
agorasdk.log
file. The value range is [128,20480]. The default value is 1,024 KB. If you setfileSizeInKByte
smaller than 128 KB, the SDK automatically adjusts it to 128 KB; if you setfileSizeInKByte
greater than 20,480 KB, the SDK automatically adjusts it to 20,480 KB.
Returns
- 0: Success.
- < 0: Failure.
setLogFilter
Sets the log output level of the SDK.
virtual int setLogFilter(unsigned int filter) = 0;
- Deprecated:
- Use logConfig in initialize instead.
This method sets the output log level of the SDK. You can use one or a combination of the log filter levels. The log level follows the sequence of LOG_FILTER_OFF, LOG_FILTER_CRITICAL, LOG_FILTER_ERROR, LOG_FILTER_WARN, LOG_FILTER_INFO, and LOG_FILTER_DEBUG. Choose a level to see the logs preceding that level.
If, for example, you set the log level to LOG_FILTER_WARN, you see the logs within levels LOG_FILTER_CRITICAL, LOG_FILTER_ERROR, and LOG_FILTER_WARN.
Parameters
- filter
-
The output log level of the SDK. See LOG_FILTER_TYPE.
Returns
- 0: Success.
- < 0: Failure.
setLogLevel
Sets the output log level of the SDK.
virtual int setLogLevel(commons::LOG_LEVEL level) = 0;
- Deprecated:
- This method is deprecated. Use RtcEngineContext instead to set the log output level.
Choose a level to see the logs preceding that level.
Parameters
- level
- The log level: LOG_LEVEL.
Returns
- 0: Success.
- < 0: Failure.
setParameters [1/2]
Provides technical preview functionalities or special customizations by configuring the SDK with JSON options.
virtual int setParameters(const char* parameters) = 0;
- Since
- v4.1.0
Contact technical support to get the JSON configuration method.
Parameters
- parameters
- Pointer to the set parameters in a JSON string.
Returns
- 0: Success.
- < 0: Failure.
setParameters [2/2]
Provides the technical preview functionalities or special customizations by configuring the SDK with JSON options.
virtual int setParameters(const char* parameters) = 0;
Contact technical support to get the JSON configuration method.
Parameters
- parameters
- Pointer to the set parameters in a JSON string.
Returns
- 0: Success.
- < 0: Failure.
startEchoTest [1/3]
Starts an audio call test.
virtual int startEchoTest() = 0;
- Deprecated:
- This method is deprecated, use startEchoTest [2/3] instead.
This method starts an audio call test to determine whether the audio devices (for example, headset and speaker) and the network connection are working properly. To conduct the test, the user speaks, and the recording is played back within 10 seconds. If the user can hear the recording within the interval, the audio devices and network connection are working properly.
- Call this method before joining a channel.
- After calling startEchoTest [1/3], you must call stopEchoTest to end the test. Otherwise, the app cannot perform the next echo test, and you cannot join the channel.
- In the live streaming channels, only a host can call this method.
Returns
- 0: Success.
- < 0: Failure.
startEchoTest [2/3]
Starts an audio call test.
virtual int startEchoTest(int intervalInSeconds) = 0;
- Deprecated:
- This method is deprecated as of v4.0.1. Use startEchoTest [3/3] instead.
This method starts an audio call test to determine whether the audio devices (for example, headset and speaker) and the network connection are working properly. To conduct the test, let the user speak for a while, and the recording is played back within the set interval. If the user can hear the recording within the interval, the audio devices and network connection are working properly.
- Call this method before joining a channel.
- After calling startEchoTest [2/3], you must call stopEchoTest to end the test. Otherwise, the app cannot perform the next echo test, and you cannot join the channel.
- In the live streaming channels, only a host can call this method.
Parameters
- intervalInSeconds
- The time interval (s) between when you speak and when the recording plays back. The value range is [2, 10], and the default value is 10.
Returns
- 0: Success.
- < 0: Failure.
startEchoTest [3/3]
Starts an audio and video call loop test.
virtual int startEchoTest(const EchoTestConfiguration& config) = 0;
Before joining a channel, to test whether the user's local sending and receiving streams are normal, you can call this method to perform an audio and video call loop test, which tests whether the audio and video devices and the user's upstream and downstream networks are working properly.
- Call this method before joining a channel.
- After calling this method, call stopEchoTest to end the test; otherwise, the user cannot perform the next audio and video call loop test and cannot join the channel.
- In live streaming scenarios, this method only applies to hosts.
Parameters
- config
- The configuration of the audio and video call loop test. See EchoTestConfiguration.
Returns
- 0: Success.
- < 0: Failure.
startLastmileProbeTest
Starts the last mile network probe test.
virtual int startLastmileProbeTest(const LastmileProbeConfig& config) = 0;
This method starts the last-mile network probe test before joining a channel to get the uplink and downlink last mile network statistics, including the bandwidth, packet loss, jitter, and round-trip time (RTT).
- onLastmileQuality: The SDK triggers this callback within two seconds depending on the network conditions. This callback rates the network conditions and is more closely linked to the user experience.
- onLastmileProbeResult: The SDK triggers this callback within 30 seconds depending on the network conditions. This callback returns the real-time statistics of the network conditions and is more objective.
- Before a user joins a channel, call this method to check the uplink network quality.
- In a live streaming channel, call this method to check the uplink network quality before an audience member switches to a host.
- Do not call other methods before receiving the onLastmileQuality and onLastmileProbeResult callbacks. Otherwise, the callbacks may be interrupted.
- A host should not call this method after joining a channel (when in a call).
Parameters
- config
- The configurations of the last-mile network probe test. See LastmileProbeConfig.
Returns
- 0: Success.
- < 0: Failure.
stopEchoTest
Stops the audio call test.
virtual int stopEchoTest() = 0;
Returns
- 0: Success.
-
< 0: Failure.
- -5(ERR_REFUSED): Failed to stop the echo test. The echo test may not be running.
stopLastmileProbeTest
Stops the last mile network probe test.
virtual int stopLastmileProbeTest() = 0;
Returns
- 0: Success.
- < 0: Failure.
onApiCallExecuted
Occurs when a method is executed by the SDK.
virtual void onApiCallExecuted(int err, const char* api, const char* result) { (void)err; (void)api; (void)result; }
- Deprecated:
- Deprecated as of v4.1.0. This method can neither accurately characterize the specific API method nor represent the execution result of the API.
Parameters
- err
- The error code returned by the SDK when the method call fails. If the SDK returns 0, then the method call is successful.
- api
- The method executed by the SDK.
- result
- The result of the method call.
onChannelMediaRelayStateChanged
Occurs when the state of the media stream relay changes.
virtual void onChannelMediaRelayStateChanged(CHANNEL_MEDIA_RELAY_STATE state,CHANNEL_MEDIA_RELAY_ERROR code) { }
The SDK returns the state of the current media relay with any error message.
Parameters
- state
-
The state code. See CHANNEL_MEDIA_RELAY_STATE.
- code
-
The error code of the channel media relay. See CHANNEL_MEDIA_RELAY_ERROR.
onConnectionBanned
Occurs when the connection is banned by the Agora server.
virtual void onConnectionBanned()
- Deprecated:
- Please use onConnectionStateChanged instead.
onConnectionInterrupted
Occurs when the connection between the SDK and the server is interrupted.
virtual void onConnectionInterrupted() {}
- Deprecated:
- Use onConnectionStateChanged instead.
- 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.
onConnectionLost
Occurs when the SDK cannot reconnect to Agora's edge server 10 seconds after its connection to the server is interrupted.
virtual void onConnectionLost()
The SDK triggers this callback when it cannot connect to the server 10 seconds after calling the joinChannel [2/2] method, regardless of whether it is in the channel. If the SDK fails to rejoin the channel within 20 minutes after disconnecting, the SDK will stop trying to reconnect.
onConnectionStateChanged
Occurs when the network connection state changes.
virtual void onConnectionStateChanged(CONNECTION_STATE_TYPE state, CONNECTION_CHANGED_REASON_TYPE reason) { (void)state; (void)reason; }
When the network connection state changes, the SDK triggers this callback and reports the current connection state and the reason for the change.
Parameters
- state
The current connection state. For details, see CONNECTION_STATE_TYPE.
- reason
The reason for a connection state change. For details, see CONNECTION_CHANGED_REASON_TYPE.
onEncryptionError
Reports the built-in encryption errors.
virtual void onEncryptionError(ENCRYPTION_ERROR_TYPE errorType) { (void)errorType; }
When encryption is enabled by calling enableEncryption, the SDK triggers this callback if an error occurs in encryption or decryption on the sender or the receiver side.
Parameters
- errorType
- For details about the error type, see ENCRYPTION_ERROR_TYPE.
onExtensionError
Occurs when the extension runs incorrectly.
virtual void onExtensionError(const char* provider, const char* extension, int error, const char* message) { (void)provider; (void)extension; (void)error; (void)message; }
When calling enableExtension(
fails or the extension runs in error, the extension triggers this callback and reports the error code and reason.true
)
Parameters
- provider
- The name of the extension provider.
- extension
- The name of the extension.
- error
- Error code. For details, see the extension documentation provided by the extension provider.
- message
- Reason. For details, see the extension documentation provided by the extension provider.
onExtensionEvent
The event callback of the extension.
virtual void onExtensionEvent(const char* provider, const char* extension, const char* key, const char* value) { (void)provider; (void)extension; (void)key; (void)value; }
To listen for events while the extension is running, you need to register this callback.
Parameters
- provider
- The name of the extension provider.
- extension
- The name of the extension.
- key
- The key of the extension.
- value
- The value of the extension key.
onExtensionStarted
Occurs when the extension is enabled.
virtual void onExtensionStarted(const char* provider, const char* extension) { (void)provider; (void)extension; }
After a successful call of enableExtension(
, the extension triggers this callback.true
)
Parameters
- provider
- The name of the extension provider.
- extension
- The name of the extension.
onExtensionStopped
Occurs when the extension is disabled.
virtual void onExtensionStopped(const char* provider, const char* extension) { (void)provider; (void)extension; }
After a successful call of enableExtension(
, this callback is triggered.false
)
Parameters
- provider
- The name of the extension provider.
- extension
- The name of the extension.
onLastmileProbeResult
Reports the last mile network probe result.
virtual void onLastmileProbeResult(const LastmileProbeResult& result) { (void)result; }
The SDK triggers this callback within 30 seconds after the app calls startLastmileProbeTest.
Parameters
- result
- The uplink and downlink last-mile network probe test result. See LastmileProbeResult.
onLastmileQuality
Reports the last-mile network quality of the local user.
virtual void onLastmileQuality(int quality) { (void)quality; }
This callback reports the last-mile network conditions of the local user before the user joins the channel. Last mile refers to the connection between the local device and Agora's edge server.
Before the user joins the channel, this callback is triggered by the SDK once startLastmileProbeTest is called and reports the last-mile network conditions of the local user.
Parameters
- quality
- The last-mile network quality. See QUALITY_TYPE.
onLocalUserRegistered
Occurs when the local user registers a user account.
virtual void onLocalUserRegistered(uid_t uid, const char* userAccount) { (void)uid; (void)userAccount; }
After the local user successfully calls registerLocalUserAccount to register the user account or calls joinChannelWithUserAccount [2/2] to join a channel, the SDK triggers the callback and informs the local user's UID and User Account.
Parameters
- uid
- The ID of the local user.
- userAccount
- The user account of the local user.
onNetworkQuality
Reports the last mile network quality of each user in the channel.
virtual void onNetworkQuality(uid_t uid, int txQuality, int rxQuality) { (void)uid; (void)txQuality; (void)rxQuality; }
This callback reports the last mile network conditions of each user in the channel. Last mile refers to the connection between the local device and Agora's edge server.
The SDK triggers this callback once every two seconds. If a channel includes multiple users, the SDK triggers this callback as many times.
UNKNOWN
when the user is not sending a stream; rxQuality is UNKNOWN
when the user is not receiving a stream.Parameters
- uid
-
The user ID. The network quality of the user with this user ID is reported.
- txQuality
- Uplink network quality rating of the user in terms of the transmission bit rate, packet loss rate, average RTT (Round-Trip Time) and jitter of the uplink network. This parameter is a quality rating helping you understand how well the current uplink network conditions can support the selected video encoder configuration. 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_BROADCASTING 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 packet loss rate, average RTT, and jitter of the downlink network. See QUALITY_TYPE.
onNetworkTypeChanged
Occurs when the local network type changes.
virtual void onNetworkTypeChanged(NETWORK_TYPE type) { (void)type; }
This callback occurs when the connection state of the local user changes. You can get the connection state and reason for the state change in this callback. When the network connection is interrupted, this callback indicates whether the interruption is caused by a network type change or poor network conditions.
Parameters
- type
-
The type of the local network connection. See NETWORK_TYPE.
onPermissionError
Occurs when the SDK cannot get the device permission.
virtual void onPermissionError(PERMISSION_TYPE permissionType) { (void)permissionType; }
When the SDK fails to get the device permission, the SDK triggers this callback to report which device permission cannot be got.
Parameters
- permissionType
- The type of the device permission. See PERMISSION_TYPE.
onProxyConnected
Reports the proxy connection state.
virtual void onProxyConnected(const char* channel, uid_t uid, PROXY_TYPE proxyType, const char* localProxyIp, int elapsed) { (void)channel; (void)uid; (void)proxyType; (void)localProxyIp; (void)elapsed; }
You can use this callback to listen for the state of the SDK connecting to a proxy. For example, when a user calls setCloudProxy and joins a channel successfully, the SDK triggers this callback to report the user ID, the proxy type connected, and the time elapsed fromthe user calling joinChannel [1/2] until this callback is triggered.
Parameters
- channel
- The channel name.
- uid
- The user ID.
- proxyType
- The proxy type connected. See CLOUD_PROXY_TYPE.
- localProxyIp
- Reserved for future use.
- elapsed
- The time elapsed (ms) from the user calling joinChannel [1/2] until this callback is triggered.
onReceiveAudioPacket
Occurs when the local user receives an audio packet.
virtual bool onReceiveAudioPacket(Packet& packet) = 0;
Parameters
- packet
- The received audio packet, see Packet.
Returns
true
: The audio packet is received successfully.false
: The audio packet is discarded.
onReceiveVideoPacket
Occurs when the local user receives a video packet.
virtual bool onReceiveVideoPacket(Packet& packet) = 0;
Parameters
- packet
- The received video packet, see Packet.
Returns
true
: The video packet is received successfully.false
: The video packet is discarded.
onSendAudioPacket
Occurs when the local user sends an audio packet.
virtual bool onSendAudioPacket(Packet& packet) = 0;
Parameters
- packet
- The sent audio packet, see Packet.
Returns
true
: The audio packet is sent successfully.false
: The audio packet is discarded.
onSendVideoPacket
Occurs when the local user sends a video packet.
virtual bool onSendVideoPacket(Packet& packet) = 0;
Parameters
- packet
- The sent video packet, see Packet.
Returns
true
: The video packet is sent successfully.false
: The video packet is discarded.
onStreamMessage
Occurs when the local user receives the data stream from the remote user.
virtual void onStreamMessage(uid_t userId, int streamId, const char* data, size_t length, uint64_t sentTs) { (void)userId; (void)streamId; (void)data; (void)length; (void)sentTs; }
The SDK triggers this callback when the local user receives the stream message that the remote user sends by calling the sendStreamMessage method.
Parameters
- userId
- The ID of the remote user sending the message.
- streamId
- The stream ID of the received message.
- data
- received data.
- length
- The data length (byte).
- sentTs
- The time when the data stream is sent.
onStreamMessageError
Occurs when the local user does not receive the data stream from the remote user.
virtual void onStreamMessageError(uid_t userId, int streamId, int code, int missed, int cached) { (void)userId; (void)streamId; (void)code; (void)missed; (void)cached; }
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
- userId
- The ID of the remote user sending the message.
- streamId
- The stream ID of the received message.
- code
- The error code.
- missed
- The number of lost messages.
- cached
- Number of incoming cached messages when the data stream is interrupted.
onUplinkNetworkInfoUpdated
Occurs when the uplink network information changes.
virtual void onUplinkNetworkInfoUpdated(const UplinkNetworkInfo& info) { (void)info; }
The SDK triggers this callback when the uplink network information changes.
Parameters
- info
- The uplink network information. See UplinkNetworkInfo.
Packet
Definition of Packet.
struct Packet {
const unsigned char* buffer;
unsigned int size;
Packet() : buffer(NULL), size(0) {}
};
Attributes
- buffer
-
The buffer address of the sent or received data.
Attention: Agora recommends setting buffer to a value larger than 2048 bytes. Otherwise, you may encounter undefined behaviors (such as crashes). - size
- The buffer size of the sent or received data.