Agora C++ API Reference for All Platforms

Namespaces | Classes | Typedefs | Enumerations | Functions | Variables
agora Namespace Reference

## Namespaces
| base
| capability
| commons
| extension
| internal
| media
| rtc
| rtm
| util

## Classes
class | agora_refptr
class | AtomicOps
struct | DataChannelConfig
struct | DataChannelInfo
class | IDataChannelObserver
class | ILocalDataChannel
struct | in_place_t
class | IRemoteDataChannel
struct | nullopt_t
class | Optional
class | RefCountedObject
class | RefCounter
class | RefCountInterface
class | RefObjectDeleter
struct | SpatialAudioParams
struct | UserDataChannelInfo
struct | UserInfo
struct | VideoLayout

## Typedefs
typedef const char * | user_id_t
typedef void * | view_t
typedef util::AList< UserInfo > | UserList

## Enumerations
enum | CHANNEL_PROFILE_TYPE { CHANNEL_PROFILE_COMMUNICATION = 0, CHANNEL_PROFILE_LIVE_BROADCASTING = 1, __deprecated = 2, __deprecated = 2, __deprecated = 2 }
enum | WARN_CODE_TYPE { WARN_INVALID_VIEW = 8, WARN_INIT_VIDEO = 16, WARN_PENDING = 20, WARN_NO_AVAILABLE_CHANNEL = 103, WARN_LOOKUP_CHANNEL_TIMEOUT = 104, WARN_LOOKUP_CHANNEL_REJECTED = 105, WARN_OPEN_CHANNEL_TIMEOUT = 106, WARN_OPEN_CHANNEL_REJECTED = 107, WARN_SWITCH_LIVE_VIDEO_TIMEOUT = 111, WARN_SET_CLIENT_ROLE_TIMEOUT = 118, WARN_OPEN_CHANNEL_INVALID_TICKET = 121, WARN_OPEN_CHANNEL_TRY_NEXT_VOS = 122, WARN_CHANNEL_CONNECTION_UNRECOVERABLE = 131, WARN_CHANNEL_CONNECTION_IP_CHANGED = 132, WARN_CHANNEL_CONNECTION_PORT_CHANGED = 133, WARN_CHANNEL_SOCKET_ERROR = 134, WARN_AUDIO_MIXING_OPEN_ERROR = 701, WARN_ADM_RUNTIME_PLAYOUT_WARNING = 1014, WARN_ADM_RUNTIME_RECORDING_WARNING = 1016, WARN_ADM_RECORD_AUDIO_SILENCE = 1019, WARN_ADM_PLAYOUT_MALFUNCTION = 1020, WARN_ADM_RECORD_MALFUNCTION = 1021, WARN_ADM_RECORD_AUDIO_LOWLEVEL = 1031, WARN_ADM_PLAYOUT_AUDIO_LOWLEVEL = 1032, WARN_ADM_WINDOWS_NO_DATA_READY_EVENT = 1040, WARN_APM_HOWLING = 1051, WARN_ADM_GLITCH_STATE = 1052, WARN_ADM_IMPROPER_SETTINGS = 1053, WARN_ADM_POP_STATE = 1055, WARN_ADM_WIN_CORE_NO_RECORDING_DEVICE = 1322, WARN_ADM_WIN_CORE_NO_PLAYOUT_DEVICE = 1323, WARN_ADM_WIN_CORE_IMPROPER_CAPTURE_RELEASE = 1324 }
enum | ERROR_CODE_TYPE { ERR_OK = 0, ERR_FAILED = 1, ERR_INVALID_ARGUMENT = 2, ERR_NOT_READY = 3, ERR_NOT_SUPPORTED = 4, ERR_REFUSED = 5, ERR_BUFFER_TOO_SMALL = 6, ERR_NOT_INITIALIZED = 7, ERR_INVALID_STATE = 8, ERR_NO_PERMISSION = 9, ERR_TIMEDOUT = 10, ERR_CANCELED = 11, ERR_TOO_OFTEN = 12, ERR_BIND_SOCKET = 13, ERR_NET_DOWN = 14, ERR_JOIN_CHANNEL_REJECTED = 17, ERR_LEAVE_CHANNEL_REJECTED = 18, ERR_ALREADY_IN_USE = 19, ERR_ABORTED = 20, ERR_INIT_NET_ENGINE = 21, ERR_RESOURCE_LIMITED = 22, ERR_INVALID_APP_ID = 101, ERR_INVALID_CHANNEL_NAME = 102, ERR_NO_SERVER_RESOURCES = 103, ERR_TOKEN_EXPIRED = 109, ERR_INVALID_TOKEN = 110, ERR_CONNECTION_INTERRUPTED = 111, ERR_CONNECTION_LOST = 112, ERR_NOT_IN_CHANNEL = 113, ERR_SIZE_TOO_LARGE = 114, ERR_BITRATE_LIMIT = 115, ERR_TOO_MANY_DATA_STREAMS = 116, ERR_STREAM_MESSAGE_TIMEOUT = 117, ERR_SET_CLIENT_ROLE_NOT_AUTHORIZED = 119, ERR_DECRYPTION_FAILED = 120, ERR_INVALID_USER_ID = 121, ERR_DATASTREAM_DECRYPTION_FAILED = 122, ERR_CLIENT_IS_BANNED_BY_SERVER = 123, ERR_ENCRYPTED_STREAM_NOT_ALLOWED_PUBLISH = 130, ERR_LICENSE_CREDENTIAL_INVALID = 131, ERR_INVALID_USER_ACCOUNT = 134, ERR_MODULE_NOT_FOUND = 157, ERR_CERT_RAW = 157, ERR_CERT_JSON_PART = 158, ERR_CERT_JSON_INVAL = 159, ERR_CERT_JSON_NOMEM = 160, ERR_CERT_CUSTOM = 161, ERR_CERT_CREDENTIAL = 162, ERR_CERT_SIGN = 163, ERR_CERT_FAIL = 164, ERR_CERT_BUF = 165, ERR_CERT_NULL = 166, ERR_CERT_DUEDATE = 167, ERR_CERT_REQUEST = 168, ERR_PCMSEND_FORMAT = 200, ERR_PCMSEND_BUFFEROVERFLOW = 201, ERR_LOAD_MEDIA_ENGINE = 1001, ERR_ADM_GENERAL_ERROR = 1005, ERR_ADM_INIT_PLAYOUT = 1008, ERR_ADM_START_PLAYOUT = 1009, ERR_ADM_STOP_PLAYOUT = 1010, ERR_ADM_INIT_RECORDING = 1011, ERR_ADM_START_RECORDING = 1012, ERR_ADM_STOP_RECORDING = 1013, ERR_VDM_CAMERA_NOT_AUTHORIZED = 1501 }
enum | LICENSE_ERROR_TYPE { LICENSE_ERR_INVALID = 1, LICENSE_ERR_EXPIRE = 2, LICENSE_ERR_MINUTES_EXCEED = 3, LICENSE_ERR_LIMITED_PERIOD = 4, LICENSE_ERR_DIFF_DEVICES = 5, LICENSE_ERR_INTERNAL = 99 }
enum | AUDIO_SESSION_OPERATION_RESTRICTION { AUDIO_SESSION_OPERATION_RESTRICTION_NONE = 0, AUDIO_SESSION_OPERATION_RESTRICTION_SET_CATEGORY = 1, AUDIO_SESSION_OPERATION_RESTRICTION_CONFIGURE_SESSION = 1 << 1, AUDIO_SESSION_OPERATION_RESTRICTION_DEACTIVATE_SESSION = 1 << 2, AUDIO_SESSION_OPERATION_RESTRICTION_ALL = 1 << 7 }

## Functions
template<typename T , typename... types>
agora_refptr< T > | make_refptr (types &&... args)
template<typename T >
agora_refptr< T > | make_refptr ()
template<typename T , typename P0 >
agora_refptr< T > | make_refptr (const P0 &p0)
const nullopt_t | nullopt (0)

## Variables
const in_place_t | in_place = {}
OPTIONAL_ENUM_CLASS | RefCountReleaseStatus { kDroppedLastRef, kOtherRefsRemained }

## Typedef Documentation

## ◆ user_id_t

typedef const char* agora::user_id_t

## ◆ view_t

typedef void* agora::view_t

## ◆ UserList

typedef util::AList<UserInfo> agora::UserList

## Enumeration Type Documentation

## ◆ CHANNEL_PROFILE_TYPE

enum agora::CHANNEL_PROFILE_TYPE

The channel profile.

Enumerator
CHANNEL_PROFILE_COMMUNICATION | 0: Communication. This profile prioritizes smoothness and applies to the one-to-one scenario.
CHANNEL_PROFILE_LIVE_BROADCASTING | 1: (Default) Live Broadcast. This profile prioritizes supporting a large audience in a live broadcast channel.
__deprecated | 2: Gaming. Deprecated: This profile is deprecated. 3: Cloud Gaming. Deprecated: This profile is deprecated. 4: Communication 1v1. Deprecated: This profile is deprecated.
__deprecated | 2: Gaming. Deprecated: This profile is deprecated. 3: Cloud Gaming. Deprecated: This profile is deprecated. 4: Communication 1v1. Deprecated: This profile is deprecated.
__deprecated | 2: Gaming. Deprecated: This profile is deprecated. 3: Cloud Gaming. Deprecated: This profile is deprecated. 4: Communication 1v1. Deprecated: This profile is deprecated.

## ◆ WARN_CODE_TYPE

enum agora::WARN_CODE_TYPE

The warning codes.

Enumerator
WARN_INVALID_VIEW | 8: The specified view is invalid. To use the video function, you need to specify a valid view.
WARN_INIT_VIDEO | 16: Fails to initialize the video function, probably due to a lack of resources. Users fail to see each other, but can still communicate with voice.
WARN_PENDING | 20: The request is pending, usually because some module is not ready, and the SDK postpones processing the request.
WARN_NO_AVAILABLE_CHANNEL | 103: No channel resources are available, probably because the server cannot allocate any channel resource.
WARN_LOOKUP_CHANNEL_TIMEOUT | 104: A timeout occurs when looking for the channel. When joining a channel, the SDK looks up the specified channel. This warning usually occurs when the network condition is too poor to connect to the server.
WARN_LOOKUP_CHANNEL_REJECTED | 105: The server rejects the request to look for the channel. The server cannot process this request or the request is illegal.
WARN_OPEN_CHANNEL_TIMEOUT | 106: A timeout occurs when opening the channel. Once the specific channel is found, the SDK opens the channel. This warning usually occurs when the network condition is too poor to connect to the server.
WARN_OPEN_CHANNEL_REJECTED | 107: The server rejects the request to open the channel. The server cannot process this request or the request is illegal.
WARN_SWITCH_LIVE_VIDEO_TIMEOUT | 111: A timeout occurs when switching the live video.
WARN_SET_CLIENT_ROLE_TIMEOUT | 118: A timeout occurs when setting the user role.
WARN_OPEN_CHANNEL_INVALID_TICKET | 121: The ticket to open the channel is invalid.
WARN_OPEN_CHANNEL_TRY_NEXT_VOS | 122: The SDK is trying connecting to another server.
WARN_CHANNEL_CONNECTION_UNRECOVERABLE | 131: The channel connection cannot be recovered.
WARN_CHANNEL_CONNECTION_IP_CHANGED | 132: The SDK connection IP has changed.
WARN_CHANNEL_CONNECTION_PORT_CHANGED | 133: The SDK connection port has changed.
WARN_CHANNEL_SOCKET_ERROR | 134: The socket error occurs, try to rejoin channel.
WARN_AUDIO_MIXING_OPEN_ERROR | 701: An error occurs when opening the file for audio mixing.
WARN_ADM_RUNTIME_PLAYOUT_WARNING | 1014: Audio Device Module: An exception occurs in the playback device.
WARN_ADM_RUNTIME_RECORDING_WARNING | 1016: Audio Device Module: A warning occurs in the recording device.
WARN_ADM_RECORD_AUDIO_SILENCE | 1019: Audio Device Module: No valid audio data is collected.
WARN_ADM_PLAYOUT_MALFUNCTION | 1020: Audio Device Module: The playback device fails to start.
WARN_ADM_RECORD_MALFUNCTION | 1021: Audio Device Module: The recording device fails to start.
WARN_ADM_RECORD_AUDIO_LOWLEVEL | 1031: Audio Device Module: The recorded audio volume is too low.
WARN_ADM_PLAYOUT_AUDIO_LOWLEVEL | 1032: Audio Device Module: The playback audio volume is too low.
WARN_ADM_WINDOWS_NO_DATA_READY_EVENT | 1040: Audio device module: An exception occurs with the audio drive. Choose one of the following solutions: Disable or re-enable the audio device. Re-enable your device. Update the sound card drive.
WARN_APM_HOWLING | 1051: Audio Device Module: The SDK detects howling.
WARN_ADM_GLITCH_STATE | 1052: Audio Device Module: The audio device is in a glitching state.
WARN_ADM_IMPROPER_SETTINGS | 1053: Audio Device Module: The settings are improper.
WARN_ADM_POP_STATE | 1055: Audio Device Module: The audio device is in a pop state.
WARN_ADM_WIN_CORE_NO_RECORDING_DEVICE | 1322: No recording device.
WARN_ADM_WIN_CORE_NO_PLAYOUT_DEVICE | 1323: Audio device module: No available playback device. You can try plugging in the audio device.
WARN_ADM_WIN_CORE_IMPROPER_CAPTURE_RELEASE | 1324: Audio device module: The capture device is released improperly. Choose one of the following solutions: Disable or re-enable the audio device. Re-enable your audio device. Update the sound card drive.

## ◆ ERROR_CODE_TYPE

enum agora::ERROR_CODE_TYPE

The error codes.

Enumerator
ERR_OK | 0: No error occurs.
ERR_FAILED | 1: A general error occurs (no specified reason).
ERR_INVALID_ARGUMENT | 2: The argument is invalid. For example, the specific channel name includes illegal characters.
ERR_NOT_READY | 3: The SDK module is not ready. Choose one of the following solutions: Check the audio device. Check the completeness of the app. Reinitialize the RTC engine.
ERR_NOT_SUPPORTED | 4: The SDK does not support this function.
ERR_REFUSED | 5: The request is rejected.
ERR_BUFFER_TOO_SMALL | 6: The buffer size is not big enough to store the returned data.
ERR_NOT_INITIALIZED | 7: The SDK is not initialized before calling this method.
ERR_INVALID_STATE | 8: The state is invalid.
ERR_NO_PERMISSION | 9: No permission. This is for internal use only, and does not return to the app through any method or callback.
ERR_TIMEDOUT | 10: An API timeout occurs. Some API methods require the SDK to return the execution result, and this error occurs if the request takes too long (more than 10 seconds) for the SDK to process.
ERR_CANCELED | 11: The request is cancelled. This is for internal use only, and does not return to the app through any method or callback.
ERR_TOO_OFTEN | 12: The method is called too often. This is for internal use only, and does not return to the app through any method or callback.
ERR_BIND_SOCKET | 13: The SDK fails to bind to the network socket. This is for internal use only, and does not return to the app through any method or callback.
ERR_NET_DOWN | 14: The network is unavailable. This is for internal use only, and does not return to the app through any method or callback.
ERR_JOIN_CHANNEL_REJECTED | 17: The request to join the channel is rejected. This error usually occurs when the user is already in the channel, and still calls the method to join the channel, for example, joinChannel().
ERR_LEAVE_CHANNEL_REJECTED | 18: The request to leave the channel is rejected. This error usually occurs when the user has already left the channel, and still calls the method to leave the channel, for example, leaveChannel.
ERR_ALREADY_IN_USE | 19: The resources have been occupied and cannot be reused.
ERR_ABORTED | 20: The SDK gives up the request due to too many requests. This is for internal use only, and does not return to the app through any method or callback.
ERR_INIT_NET_ENGINE | 21: On Windows, specific firewall settings can cause the SDK to fail to initialize and crash.
ERR_RESOURCE_LIMITED | 22: The app uses too much of the system resource and the SDK fails to allocate any resource.
ERR_INVALID_APP_ID | 101: The App ID is invalid, usually because the data format of the App ID is incorrect. Solution: Check the data format of your App ID. Ensure that you use the correct App ID to initialize the Agora service.
ERR_INVALID_CHANNEL_NAME | 102: The specified channel name is invalid. Please try to rejoin the channel with a valid channel name.
ERR_NO_SERVER_RESOURCES | 103: Fails to get server resources in the specified region. Please try to specify another region when calling initialize.
ERR_TOKEN_EXPIRED | 109: The token has expired, usually for the following reasons: Timeout for token authorization: Once a token is generated, you must use it to access the Agora service within 24 hours. Otherwise, the token times out and you can no longer use it. The token privilege expires: To generate a token, you need to set a timestamp for the token privilege to expire. For example, If you set it as seven days, the token expires seven days after its usage. In that case, you can no longer access the Agora service. The users cannot make calls, or are kicked out of the channel. Solution: Regardless of whether token authorization times out or the token privilege expires, you need to generate a new token on your server, and try to join the channel.
ERR_INVALID_TOKEN | 110: The token is invalid, usually for one of the following reasons: Did not provide a token when joining a channel in a situation where the project has enabled the App Certificate. Tried to join a channel with a token in a situation where the project has not enabled the App Certificate. The App ID, user ID and channel name that you use to generate the token on the server do not match those that you use when joining a channel. Solution: Before joining a channel, check whether your project has enabled the App certificate. If yes, you must provide a token when joining a channel; if no, join a channel without a token. When using a token to join a channel, ensure that the App ID, user ID, and channel name that you use to generate the token is the same as the App ID that you use to initialize the Agora service, and the user ID and channel name that you use to join the channel.
ERR_CONNECTION_INTERRUPTED | 111: The internet connection is interrupted. This applies to the Agora Web SDK only.
ERR_CONNECTION_LOST | 112: The internet connection is lost. This applies to the Agora Web SDK only.
ERR_NOT_IN_CHANNEL | 113: The user is not in the channel when calling the sendStreamMessage() method.
ERR_SIZE_TOO_LARGE | 114: The data size is over 1024 bytes when the user calls the sendStreamMessage() method.
ERR_BITRATE_LIMIT | 115: The bitrate of the sent data exceeds the limit of 6 Kbps when the user calls the sendStreamMessage().
ERR_TOO_MANY_DATA_STREAMS | 116: Too many data streams (over 5) are created when the user calls the createDataStream() method.
ERR_STREAM_MESSAGE_TIMEOUT | 117: A timeout occurs for the data stream transmission.
ERR_SET_CLIENT_ROLE_NOT_AUTHORIZED | 119: Switching the user role fails. Please try to rejoin the channel.
ERR_DECRYPTION_FAILED | 120: MediaStream decryption fails. The user may have tried to join the channel with a wrong password. Check your settings or try rejoining the channel.
ERR_INVALID_USER_ID | 121: The user ID is invalid.
ERR_DATASTREAM_DECRYPTION_FAILED | 122: DataStream decryption fails. The peer may have tried to join the channel with a wrong password, or did't enable datastream encryption
ERR_CLIENT_IS_BANNED_BY_SERVER | 123: The app is banned by the server.
ERR_ENCRYPTED_STREAM_NOT_ALLOWED_PUBLISH | 130: Encryption is enabled when the user calls the addPublishStreamUrl() method (CDN live streaming does not support encrypted streams).
ERR_LICENSE_CREDENTIAL_INVALID | 131: License credential is invalid
ERR_INVALID_USER_ACCOUNT | 134: The user account is invalid, usually because the data format of the user account is incorrect.
ERR_MODULE_NOT_FOUND | 157: The necessary dynamical library is not integrated. For example, if you call the enableDeepLearningDenoise but do not integrate the dynamical library for the deep-learning noise reduction into your project, the SDK reports this error code.
ERR_CERT_RAW |
ERR_CERT_JSON_PART |
ERR_CERT_JSON_INVAL |
ERR_CERT_JSON_NOMEM |
ERR_CERT_CUSTOM |
ERR_CERT_CREDENTIAL |
ERR_CERT_SIGN |
ERR_CERT_FAIL |
ERR_CERT_BUF |
ERR_CERT_NULL |
ERR_CERT_DUEDATE |
ERR_CERT_REQUEST |
ERR_PCMSEND_FORMAT |
ERR_PCMSEND_BUFFEROVERFLOW |
ERR_LOAD_MEDIA_ENGINE | 1001: Fails to load the media engine.
ERR_ADM_GENERAL_ERROR | 1005: Audio device module: A general error occurs in the Audio Device Module (no specified reason). Check if the audio device is used by another app, or try rejoining the channel.
ERR_ADM_INIT_PLAYOUT | 1008: Audio Device Module: An error occurs in initializing the playback device.
ERR_ADM_START_PLAYOUT | 1009: Audio Device Module: An error occurs in starting the playback device.
ERR_ADM_STOP_PLAYOUT | 1010: Audio Device Module: An error occurs in stopping the playback device.
ERR_ADM_INIT_RECORDING | 1011: Audio Device Module: An error occurs in initializing the recording device.
ERR_ADM_START_RECORDING | 1012: Audio Device Module: An error occurs in starting the recording device.
ERR_ADM_STOP_RECORDING | 1013: Audio Device Module: An error occurs in stopping the recording device.
ERR_VDM_CAMERA_NOT_AUTHORIZED | 1501: Video Device Module: The camera is not authorized.

## ◆ LICENSE_ERROR_TYPE

enum agora::LICENSE_ERROR_TYPE

Enumerator
LICENSE_ERR_INVALID | 1: Invalid license
LICENSE_ERR_EXPIRE | 2: License expired
LICENSE_ERR_MINUTES_EXCEED | 3: Exceed license minutes limit
LICENSE_ERR_LIMITED_PERIOD | 4: License use in limited period
LICENSE_ERR_DIFF_DEVICES | 5: Same license used in different devices at the same time
LICENSE_ERR_INTERNAL | 99: SDK internal error

## ◆ AUDIO_SESSION_OPERATION_RESTRICTION

enum agora::AUDIO_SESSION_OPERATION_RESTRICTION

The operational permission of the SDK on the audio session.

Enumerator
AUDIO_SESSION_OPERATION_RESTRICTION_NONE | 0: No restriction; the SDK can change the audio session.
AUDIO_SESSION_OPERATION_RESTRICTION_SET_CATEGORY | 1: The SDK cannot change the audio session category.
AUDIO_SESSION_OPERATION_RESTRICTION_CONFIGURE_SESSION | 2: The SDK cannot change the audio session category, mode, or categoryOptions.
AUDIO_SESSION_OPERATION_RESTRICTION_DEACTIVATE_SESSION | 4: The SDK keeps the audio session active when the user leaves the channel, for example, to play an audio file in the background.
AUDIO_SESSION_OPERATION_RESTRICTION_ALL | 128: Completely restricts the operational permission of the SDK on the audio session; the SDK cannot change the audio session.

## Function Documentation

## ◆ make_refptr() [1/3]

template<typename T , typename... types>

agora_refptr< T > agora::make_refptr | ( | types &&... | args | ) |
| inline

## ◆ make_refptr() [2/3]

template<typename T >

agora_refptr< T > agora::make_refptr | ( |  | ) |
| inline

## ◆ make_refptr() [3/3]

template<typename T , typename P0 >

agora_refptr< T > agora::make_refptr | ( | const P0 & | p0 | ) |
| inline

## ◆ nullopt()

const nullopt_t agora::nullopt | ( | 0 |  | ) |

## Variable Documentation

## ◆ in_place

const in_place_t agora::in_place = {}

## ◆ RefCountReleaseStatus

OPTIONAL_ENUM_CLASS agora::RefCountReleaseStatus { kDroppedLastRef, kOtherRefsRemained }