Agora C++ API Reference for All Platforms

Releases all IChannel resources.

Returns

• 0: Success.
• < 0: Failure.
  • ERR_NOT_INITIALIZED (7): The SDK is not initialized before calling this method.

Sets the channel event handler.

After setting the channel event handler, you can listen for channel events and receive the statistics of the corresponding IChannel object.

Parameters

channelEh

The event handler of the IChannel object. For details, see IChannelEventHandler.

Returns

• 0: Success.
• < 0: Failure.

Joins the channel with a user ID.

This method differs from the joinChannel method in the IRtcEngine class in the following aspects:

Note

• If you are already in a channel, you cannot rejoin it with the same uid.
• We recommend using different UIDs for different channels.
• If you want to join the same channel from different devices, ensure that the UIDs in all devices are different.
• Ensure that the app ID you use to generate the token is the same with the app ID used when creating the IChannel object.

Parameters

token	The token for authentication: In situations not requiring high security: You can use the temporary token generated at Console. For details, see Get a temporary token. In situations requiring high security: Set it as the token generated at your server. For details, see Generate a token.
info	(Optional) Additional information about the channel. This parameter can be set as null. Other users in the channel do not receive this information.
uid	The user ID. A 32-bit unsigned integer with a value ranging from 1 to (232-1). This parameter must be unique. If uid is not assigned (or set as 0), the SDK assigns a uid and reports it in the onJoinChannelSuccess callback. The app must maintain this user ID.
options	The channel media options: ChannelMediaOptions.

Returns

• 0: Success.
• < 0: Failure.
  • ERR_INVALID_ARGUMENT (-2)
  • ERR_NOT_READY (-3)
  • ERR_REFUSED (-5)

Joins the channel with a user account.

After the user successfully joins the channel, the SDK triggers the following callbacks:

• The local client: onLocalUserRegistered and onJoinChannelSuccess .
• The remote client: onUserJoined and onUserInfoUpdated , if the user joining the channel is in the Communication profile, or is a BROADCASTER in the Live Broadcast profile.

Note

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 uid of the user is set to the same parameter type.

Parameters

token	The token generated at your server: For low-security requirements: You can use the temporary token generated at Console. For details, see Get a temporary toke. For high-security requirements: Set it as the token generated at your server. For details, see Get a token.
userAccount	The user account. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as null. Supported character scopes are: All lowercase English letters: a to z. All uppercase English letters: A to Z. All numeric characters: 0 to 9. The space character. Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
options	The channel media options: ChannelMediaOptions.

Returns

• 0: Success.
• < 0: Failure.
  • ERR_INVALID_ARGUMENT (-2)
  • ERR_NOT_READY (-3)
  • ERR_REFUSED (-5)

Allows a user to leave a channel, such as hanging up or exiting a call.

After joining a channel, the user must call the leaveChannel method to end the call before joining another channel.

This method returns 0 if the user leaves the channel and releases all resources related to the call.

This method call is asynchronous, and the user has not left the channel when the method call returns. Once the user leaves the channel, the SDK triggers the onLeaveChannel callback.

A successful leaveChannel method call triggers the following callbacks:

• The local client: onLeaveChannel
• The remote client: onUserOffline , if the user leaving the channel is in the Communication channel, or is a BROADCASTER in the Live Broadcast profile.

Note

• If you call the release method immediately after the leaveChannel method, the leaveChannel process interrupts, and the onLeaveChannel callback is not triggered.
• If you call the leaveChannel method during a CDN live streaming, the SDK triggers the removePublishStreamUrl method.

Returns

• 0: Success.
• < 0: Failure.

Publishes the local stream to the channel.

You must keep the following restrictions in mind when calling this method. Otherwise, the SDK returns the ERR_REFUSED (5):

• This method publishes one stream only to the channel corresponding to the current IChannel object.
• In a Live Broadcast channel, only a broadcaster can call this method. To switch the client role, call setClientRole of the current IChannel object.
• You can publish a stream to only one channel at a time. For details on joining multiple channels, see the advanced guide Join Multiple Channels.

Returns

• 0: Success.
• < 0: Failure.
  • ERR_REFUSED (5): The method call is refused.

Stops publishing a stream to the channel.

If you call this method in a channel where you are not publishing streams, the SDK returns ERR_REFUSED (5).

Returns

• 0: Success.
• < 0: Failure.
  • ERR_REFUSED (5): The method call is refused.

Gets the channel ID of the current IChannel object.

Returns

• The channel ID of the current IChannel object, if the method call succeeds.
• The empty string "", if the method call fails.

Retrieves the current call ID.

When a user joins a channel on a client, a callId is generated to identify the call from the client. Feedback methods, such as rate and complain, must be called after the call ends to submit feedback to the SDK.

The rate and complain methods require the callId parameter retrieved from the getCallId method during a call. callId is passed as an argument into the rate and complain methods after the call ends.

Parameters

callId

The current call ID.

Returns

• 0: Success.
• < 0: Failure.

Gets a new token when the current token expires after a period of time.

The token expires after a period of time once the token schema is enabled when:

• The SDK triggers the onTokenPrivilegeWillExpire callback, or
• The onConnectionStateChanged reports CONNECTION_CHANGED_TOKEN_EXPIRED(9).

The application should call this method to get the new token. Failure to do so will result in the SDK disconnecting from the server.

Parameters

token

Pointer to the new token.

Returns

• 0: Success.
• < 0: Failure.

Enables built-in encryption with an encryption password before users join a channel.

All users in a channel must use the same encryption password. The encryption password is automatically cleared once a user leaves the channel.

If an encryption password is not specified, the encryption functionality will be disabled.

Note

• 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

Pointer to the encryption password.

Returns

• 0: Success.
• < 0: Failure.

Sets the built-in encryption mode.

The Agora SDK supports built-in encryption, which is set to the aes-128-xts mode by default. Call this method to use other encryption modes.

All users in the same channel must use the same encryption mode and password.

Refer to the information related to the AES encryption algorithm on the differences between the encryption modes.

Note

Call the setEncryptionSecret method to enable the built-in encryption function before calling this method.

Parameters

encryptionMode

The set encryption mode: "aes-128-xts": (Default) 128-bit AES encryption, XTS mode. "aes-128-ecb": 128-bit AES encryption, ECB mode. "aes-256-xts": 256-bit AES encryption, XTS mode. "": When encryptionMode is set as NULL, the encryption mode is set as "aes-128-xts" by default.

Returns

• 0: Success.
• < 0: Failure.

Registers a packet observer.

The Agora SDK allows your application to register a packet observer to receive callbacks for voice or video packet transmission.

Note

• The size of the packet sent to the network after processing should not exceed 1200 bytes, otherwise, the packet may fail to be sent.
• 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 CDN live streaming, recording or storage functions, Agora doesn't recommend calling this method.

Parameters

observer

The registered packet observer. See IPacketObserver.

Returns

• 0: Success.
• < 0: Failure.

Registers the metadata observer.

Registers the metadata observer. You need to implement the IMetadataObserver class and specify the metadata type in this method. A successful call of this method triggers the getMaxMetadataSize callback. This method enables you to add synchronized metadata in the video stream for more diversified live broadcast interactions, such as sending shopping links, digital coupons, and online quizzes.

Note

• Call this method before the joinChannel method.
• This method applies to the Live-broadcast channel profile.

Parameters

observer	The IMetadataObserver class. See the definition of IMetadataObserver for details.
type	See METADATA_TYPE. The SDK supports VIDEO_METADATA (0) only for now.

Returns

• 0: Success.
• < 0: Failure.

Sets the role of the user, such as a host or an audience (default), before joining a channel in a live broadcast.

This method can be used to switch the user role in a live broadcast after the user joins a channel.

In the Live Broadcast profile, when a user switches user roles after joining a channel, a successful setClientRole method call triggers the following callbacks:

• The local client: onClientRoleChanged
• The remote client: onUserJoined or onUserOffline (BECOME_AUDIENCE)

Note

This method applies only to the Live-broadcast profile.

Parameters

role	Sets the role of the user. See CLIENT_ROLE_TYPE.

Returns

• 0: Success.
• < 0: Failure.

Prioritizes a remote user's stream.

Use this method with the setRemoteSubscribeFallbackOption method. If the fallback function is enabled for a subscribed stream, the SDK ensures the high-priority user gets the best possible stream quality.

Note

The Agora SDK supports setting serPriority as high for one user only.

Parameters

uid	The ID of the remote user.
userPriority	Sets the priority of the remote user. See PRIORITY_TYPE.

Returns

• 0: Success.
• < 0: Failure.

Sets the sound position and gain of a remote user.

When the local user calls this method to set the sound position of a remote user, the sound difference between the left and right channels allows the local user to track the real-time position of the remote user, creating a real sense of space. This method applies to massively multiplayer online games, such as Battle Royale games.

Note

• For this method to work, enable stereo panning for remote users by calling the enableSoundPositionIndication method before joining a channel.
• This method requires hardware support. For the best sound positioning, we recommend using a stereo speaker.

Parameters

uid	The ID of the remote user.
pan	The sound position of the remote user. The value ranges from -1.0 to 1.0: 0.0: the remote sound comes from the front. -1.0: the remote sound comes from the left. 1.0: the remote sound comes from the right.
gain	Gain of the remote user. The value ranges from 0.0 to 100.0. The default value is 100.0 (the original gain of the remote user). The smaller the value, the less the gain.

Returns

• 0: Success.
• < 0: Failure.

Updates the display mode of the video view of a remote user.

After initializing the video view of a remote user, you can call this method to update its rendering and mirror modes. This method affects only the video view that the local user sees.

Note

• Call this method after calling the setupRemoteVideo method to initialize the remote video view.
• During a call, you can call this method as many times as necessary to update the display mode of the video view of a remote user.

Parameters

userId	The ID of the remote user.
renderMode	The rendering mode of the remote video view. See RENDER_MODE_TYPE.
mirrorMode	The mirror mode of the remote video view. See VIDEO_MIRROR_MODE_TYPE. Note: The SDK disables the mirror mode by default.

Returns

• 0: Success.
• < 0: Failure.

Sets whether to receive all remote audio streams by default.

You can call this method either before or after joining a channel. If you call setDefaultMuteAllRemoteAudioStreams (true) after joining a channel, the remote audio streams of all subsequent users are not received.

Note

If you want to resume receiving the audio stream, call muteRemoteAudioStream (false), and specify the ID of the remote user whose audio stream you want to receive. To receive the audio streams of multiple remote users, call muteRemoteAudioStream (false) as many times. Calling setDefaultMuteAllRemoteAudioStreams (false) resumes receiving the audio streams of subsequent users only.

Parameters

mute	Sets whether to receive/stop receiving all remote users' audio streams by default: true: Stops receiving all remote users' audio streams by default. false: (Default) Receives all remote users' audio streams by default.

Returns

• 0: Success.
• < 0: Failure.

Sets whether to receive all remote video streams by default.

You can call this method either before or after joining a channel. If you call setDefaultMuteAllRemoteVideoStreams (true) after joining a channel, the remote video streams of all subsequent users are not received.

Note

If you want to resume receiving the video stream, call muteRemoteVideoStream (false), and specify the ID of the remote user whose video stream you want to receive. To receive the video streams of multiple remote users, call muteRemoteVideoStream (false) as many times. Calling setDefaultMuteAllRemoteVideoStreams (false) resumes receiving the video streams of subsequent users only.

Parameters

mute	Sets whether to receive/stop receiving all remote users' video streams by default: true: Stop receiving all remote users' video streams by default. false: (Default) Receive all remote users' video streams by default.

Returns

• 0: Success.
• < 0: Failure.

Stops/Resumes receiving all remote users' audio streams.

Parameters

mute	Sets whether to receive/stop receiving all remote users' audio streams. true: Stops receiving all remote users' audio streams. false: (Default) Receives all remote users' audio streams.

Returns

• 0: Success.
• < 0: Failure.

Adjust the playback volume of the specified remote user.

After joining a channel, call adjustPlaybackSignalVolume to adjust the playback volume of different remote users, or adjust multiple times for one remote user.

Note

• Call this method after joining a channel.
• This method adjusts the playback volume, which is the mixed volume for the specified remote user.
• This method can only adjust the playback volume of one specified remote user at a time. If you want to adjust the playback volume of several remote users, call the method multiple times, once for each remote user.

Parameters

userId	The user ID, which should be the same as the uid of joinChannel
volume	The playback volume of the voice. The value ranges from 0 to 100: 0: Mute. 100: Original volume.

Returns

• 0: Success.
• < 0: Failure.

Stops/Resumes receiving a specified remote user's audio stream.

Note

If you called the muteAllRemoteAudioStreams method and set mute as true to stop receiving all remote users' audio streams, call the muteAllRemoteAudioStreams method and set mute as false before calling this method. The muteAllRemoteAudioStreams method sets all remote audio streams, while the muteRemoteAudioStream method sets a specified remote audio stream.

Parameters

userId	The user ID of the specified remote user sending the audio.
mute	Sets whether to receive/stop receiving a specified remote user's audio stream: true: Stops receiving the specified remote user's audio stream. false: (Default) Receives the specified remote user's audio stream.

Returns

• 0: Success.
• < 0: Failure.

Stops/Resumes receiving all video stream from a specified remote user.

Parameters

mute	Sets whether to receive/stop receiving all remote users' video streams: true: Stop receiving all remote users' video streams. false: (Default) Receive all remote users' video streams.

Returns

• 0: Success.
• < 0: Failure.

Stops/Resumes receiving the video stream from a specified remote user.

Note

If you called the muteAllRemoteVideoStreams method and set mute as true to stop receiving all remote video streams, call the muteAllRemoteVideoStreams method and set mute as false before calling this method.

Parameters

userId	The user ID of the specified remote user.
mute	Sets whether to stop/resume receiving the video stream from a specified remote user: true: Stop receiving the specified remote user's video stream. false: (Default) Receive the specified remote user's video stream.

Returns

• 0: Success.
• < 0: Failure.

Sets the remote user's video stream type received by the local user when the remote user sends dual streams.

This method allows the application to adjust the corresponding video-stream type based on the size of the video window to reduce the bandwidth and resources.

• If the remote user enables the dual-stream mode by calling the enableDualStreamMode method, the SDK receives the high-stream video by default.
• If the dual-stream mode is not enabled, the SDK receives the high-stream video by default.

The method result returns in the onApiCallExecuted callback. The SDK receives the high-stream video by default to reduce the bandwidth. If needed, users may use this method to switch to the low-stream video. By default, the aspect ratio of the low-stream video is the same as the high-stream video. Once the resolution of the high-stream video is set, the system automatically sets the resolution, frame rate, and bitrate of the low-stream video.

Parameters

userId	The ID of the remote user sending the video stream.
streamType	Sets the video-stream type. See REMOTE_VIDEO_STREAM_TYPE.

Returns

• 0: Success.
• < 0: Failure.

Sets the default video-stream type for the video received by the local user when the remote user sends dual streams.

• If the dual-stream mode is enabled by calling the enableDualStreamMode method, the user receives the high-stream video by default. The setRemoteDefaultVideoStreamType method allows the application to adjust the corresponding video-stream type according to the size of the video window, reducing the bandwidth and resources.
• If the dual-stream mode is not enabled, the user receives the high-stream video by default.

The result after calling this method is returned in the onApiCallExecuted callback. The Agora SDK receives the high-stream video by default to reduce the bandwidth. If needed, users can switch to the low-stream video through this method.

Parameters

streamType

Sets the default video-stream type. See REMOTE_VIDEO_STREAM_TYPE.

Returns

• 0: Success.
• < 0: Failure.

Creates a data stream.

Each user can create up to five data streams during the lifecycle of the IChannel.

Note

Set both the reliable and ordered parameters to true or false. Do not set one as true and the other as false.

Parameters

streamId	The ID of the created data stream.
reliable	Sets whether or not the recipients are guaranteed to receive the data stream from the sender within five seconds: true: The recipients receive the data stream from the sender within five seconds. If the recipient does not receive the data stream within five seconds, an error is reported to the application. 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	Sets whether or not the recipients receive the data stream in the sent order: true: The recipients receive the data stream in the sent order. false: The recipients do not receive the data stream in the sent order.

Returns

• Returns 0: Success.
• < 0: Failure.

Sends data stream messages to all users in a channel.

The SDK has the following restrictions on this method:

• Up to 30 packets can be sent per second in a channel with each packet having a maximum size of 1 kB.
• Each client can send up to 6 kB of data per second.
• Each user can have up to five data streams simultaneously.

A successful sendStreamMessage method call triggers the onStreamMessage callback on the remote client, from which the remote user gets the stream message.

A failed sendStreamMessage method call triggers the onStreamMessage callback on the remote client.

Note

This method applies only to the Communication profile or to the hosts in the Live-broadcast profile. If an audience in the Live-broadcast profile calls this method, the audience may be switched to a host.

Parameters

streamId	The ID of the sent data stream, returned in the createDataStream method.
data	The sent data.
length	The length of the sent data.

Returns

• 0: Success.
• < 0: Failure.

Publishes the local stream to a specified CDN live RTMP address. (CDN live only.)

The SDK returns the result of this method call in the onStreamPublished callback.

The addPublishStreamUrl method call triggers the onRtmpStreamingStateChanged callback on the local client to report the state of adding a local stream to the CDN.

Note

• Ensure that the user joins the channel before calling this method.
• Ensure that you enable the RTMP Converter service before using this function. See Prerequisites.
• This method adds only one stream RTMP URL address each time it is called.

Parameters

url	The CDN streaming URL in the RTMP format. The maximum length of this parameter is 1024 bytes. The RTMP URL address must not contain special characters, such as Chinese language characters.
transcodingEnabled	Sets whether transcoding is enabled/disabled: true: Enable transcoding. To transcode the audio or video streams when publishing them to CDN live, often used for combining the audio and video streams of multiple hosts in CDN live. If you set this parameter as true, ensure that you call the setLiveTranscoding method before this method. false: Disable transcoding.

Returns

• 0: Success.
• < 0: Failure.
  • ERR_INVALID_ARGUMENT (2): The RTMP URL address is NULL or has a string length of 0.
  • ERR_NOT_INITIALIZED (7): You have not initialized IChannel when publishing the stream.

Removes an RTMP stream from the CDN.

This method removes the RTMP URL address (added by the addPublishStreamUrl method) from a CDN live stream. The SDK returns the result of this method call in the onStreamUnpublished callback.

The removePublishStreamUrl method call triggers the onRtmpStreamingStateChanged callback on the local client to report the state of removing an RTMP stream from the CDN.

Note

• This method removes only one RTMP URL address each time it is called.
• The RTMP URL address must not contain special characters, such as Chinese language characters.

Parameters

url	The RTMP URL address to be removed. The maximum length of this parameter is 1024 bytes.

Returns

• 0: Success.
• < 0: Failure.

Sets the video layout and audio settings for CDN live. (CDN live only.)

The SDK triggers the onTranscodingUpdated callback when you call the setLiveTranscoding method to update the transcoding setting.

Note

• Ensure that you enable the RTMP Converter service before using this function. See Prerequisites.
• If you call the setLiveTranscoding method to set the transcoding setting for the first time, the SDK does not trigger the onTranscodingUpdated callback.

Parameters

transcoding

Sets the CDN live audio/video transcoding settings. See LiveTranscoding.

Returns

• 0: Success.
• < 0: Failure.

Adds a voice or video stream URL address to a live broadcast.

The onStreamPublished callback returns the inject status. If this method call is successful, the server pulls the voice or video stream and injects it into a live channel. This is applicable to scenarios where all audience members in the channel can watch a live show and interact with each other.

The addInjectStreamUrl method call triggers the following callbacks:

• The local client:
  • onStreamInjectedStatus , with the state of the injecting the online stream.
  • onUserJoined (uid: 666), if the method call is successful and the online media stream is injected into the channel.

• The remote client:

  • onUserJoined (uid: 666), if the method call is successful and the online media stream is injected into the channel.

  Note

  • Ensure that you enable the RTMP Converter service before using this function. See Prerequisites.
  • This method applies to the Native SDK v2.4.1 and later.
  • This method applies to the Live-Broadcast profile only.
  • You can inject only one media stream into the channel at the same time.

  Parameters

  url	The URL address to be added to the ongoing live broadcast. Valid protocols are RTMP, HLS, and HTTP-FLV. Supported audio codec type: AAC. Supported video codec type: H264 (AVC).
  config	The InjectStreamConfig object that contains the configuration of the added voice or video stream.

  Returns

  • 0: Success.
  • < 0: Failure.
    • ERR_INVALID_ARGUMENT (2): The injected URL does not exist. Call this method again to inject the stream and ensure that the URL is valid.
    • ERR_NOT_READY (3): The user is not in the channel.
    • ERR_NOT_SUPPORTED (4): The channel profile is not live broadcast. Call the setChannelProfile method and set the channel profile to live broadcast before calling this method.
    • ERR_NOT_INITIALIZED (7): The SDK is not initialized. Ensure that the IChannel object is initialized before calling this method.

Removes the voice or video stream URL address from a live broadcast.

This method removes the URL address (added by the addInjectStreamUrl method) from the live broadcast.

Note

If this method is called successfully, the SDK triggers the onUserOffline callback and returns a stream uid of 666.

Parameters

url	Pointer to the URL address of the added stream to be removed.

Returns

• 0: Success.
• < 0: Failure.

Starts to relay media streams across channels.

After a successful method call, the SDK triggers the onChannelMediaRelayStateChanged and onChannelMediaRelayEvent callbacks, and these callbacks return the state and events of the media stream relay.

• If the onChannelMediaRelayStateChanged callback returns RELAY_STATE_RUNNING (2) and RELAY_OK (0), and the onChannelMediaRelayEvent callback returns RELAY_EVENT_PACKET_SENT_TO_DEST_CHANNEL (4), the broadcaster starts sending data to the destination channel.
• If the onChannelMediaRelayStateChanged callback returns RELAY_STATE_FAILURE (3), an exception occurs during the media stream relay.

Note

• Call this method after the joinChannel method.
• This method takes effect only when you are a broadcaster in a Live-broadcast channel.
• After a successful method call, if you want to call this method again, ensure that you call the stopChannelMediaRelay method to quit the current relay.
• Contact sales.nosp@m.-us@.nosp@m.agora.nosp@m..io before implementing this function.
• We do not support string user accounts in this API.

Parameters

configuration

The configuration of the media stream relay: ChannelMediaRelayConfiguration.

Returns

• 0: Success.
• < 0: Failure.

Updates the channels for media stream relay.

After a successful startChannelMediaRelay method call, if you want to relay the media stream to more channels, or leave the current relay channel, you can call the updateChannelMediaRelay method.

After a successful method call, the SDK triggers the onChannelMediaRelayEvent callback with the RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL (7) state code.

Note

Call this method after the startChannelMediaRelay method to update the destination channel.

Parameters

configuration

The media stream relay configuration: ChannelMediaRelayConfiguration.

Returns

• 0: Success.
• < 0: Failure.

Stops the media stream relay.

Once the relay stops, the broadcaster quits all the destination channels.

After a successful method call, the SDK triggers the onChannelMediaRelayStateChanged callback. If the callback returns RELAY_STATE_IDLE (0) and RELAY_OK (0), the broadcaster successfully stops the relay.

Note

If the method call fails, the SDK triggers the onChannelMediaRelayStateChanged callback with the RELAY_ERROR_SERVER_NO_RESPONSE (2) or RELAY_ERROR_SERVER_CONNECTION_LOST (8) state code. You can leave the channel by calling the leaveChannel method, and the media stream relay automatically stops.

Returns

• 0: Success.
• < 0: Failure.

Gets the current connection state of the SDK.

Returns

CONNECTION_STATE_TYPE.