Agora Server Gateway SDK C++ API Reference
Public Member Functions | Protected Member Functions | List of all members
agora::rtc::IRtcConnection Class Referenceabstract

#include <NGIAgoraRtcConnection.h>

Public Member Functions

virtual int connect (const char *token, const char *channelId, user_id_t userId)=0
 
virtual int disconnect ()=0
 
virtual int startLastmileProbeTest (const LastmileProbeConfig &config)=0
 
virtual int stopLastmileProbeTest ()=0
 
virtual int renewToken (const char *token)=0
 
virtual TConnectionInfo getConnectionInfo ()=0
 
virtual ILocalUsergetLocalUser ()=0
 
virtual int getRemoteUsers (UserList &users)=0
 
virtual int getUserInfo (user_id_t userId, agora::UserInfo &userInfo)=0
 
virtual int registerObserver (IRtcConnectionObserver *observer, void(*safeDeleter)(IRtcConnectionObserver *)=NULL)=0
 
virtual int unregisterObserver (IRtcConnectionObserver *observer)=0
 
virtual int registerNetworkObserver (INetworkObserver *observer, void(*safeDeleter)(INetworkObserver *)=NULL)=0
 
virtual int unregisterNetworkObserver (INetworkObserver *observer)=0
 
virtual conn_id_t getConnId ()=0
 
virtual RtcStats getTransportStats ()=0
 
virtual agora::base::IAgoraParametergetAgoraParameter ()=0
 
virtual int createDataStream (int *streamId, bool reliable, bool ordered, bool sync)=0
 
virtual int sendStreamMessage (int streamId, const char *data, size_t length)=0
 
virtual int enableEncryption (bool enabled, const EncryptionConfig &config)=0
 
virtual int getUserInfoByUserAccount (const char *userAccount, rtc::UserInfo *userInfo)=0
 
virtual int getUserInfoByUid (uid_t uid, rtc::UserInfo *userInfo)=0
 

Protected Member Functions

 ~IRtcConnection ()
 

Detailed Description

The IRtcConnection class.

You can use this class for managing the connection between your app and an Agora Channel.

Once connected, your app gets an AgoraLocalUser object for publishing and subscribing to media streams in the Agora Channel.

Connecting to a channel is done asynchronously, and your app can listen for the connection states or events through IRtcConnectionObserver. IRtcConnection also monitors remote users in the channel. The SDK notifies your app when a remote user joins or leaves the channel.

Constructor & Destructor Documentation

◆ ~IRtcConnection()

agora::rtc::IRtcConnection::~IRtcConnection ( )
inlineprotected

Member Function Documentation

◆ connect()

virtual int agora::rtc::IRtcConnection::connect ( const char *  token,
const char *  channelId,
user_id_t  userId 
)
pure virtual

Connects to an Agora channel.

When the method call succeeds, the connection state changes from CONNECTION_STATE_DISCONNECTED(1) to CONNECTION_STATE_CONNECTING(2).

Depending on the whether the connection succeeds or not, the connection state changes to either CONNECTION_STATE_CONNECTED(3) or CONNECTION_STATE_FAILED(5). The SDK also triggers onConnected or onDisconnected to notify you of the state change.

Parameters
tokenThe RTC token. See Authenticate Your Users with Tokens.
channelIdThe channel name. It must be in the string format and not exceed 64 bytes in length. 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: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
userIdThe ID of the local user. If you do not specify a user ID or set userId as null, the SDK returns a user ID in the onConnected callback. Your app must record and maintain the userId since the SDK does not do so.
Returns
  • 0: Success.
  • < 0: Failure.
    • -2(ERR_INVALID_ARGUMENT): The argument that you pass is invalid.
    • -8(ERR_INVALID_STATE): The current connection state is not CONNECTION_STATE_DISCONNECTED(1).

◆ createDataStream()

virtual int agora::rtc::IRtcConnection::createDataStream ( int *  streamId,
bool  reliable,
bool  ordered,
bool  sync 
)
pure virtual

Creates a data stream.

Each user can create up to five data streams in a single channel.

Note
  • Agora does not support setting reliable as true and ordered as false.
  • Do not set the ordered parameter as true if you need the receiver to receive the data packet immediately.
  • When you set the data packet to synchronize with the audio, then if the data packet delay is within the audio delay, the SDK triggers the onStreamMessage callback when the synchronized audio packet is played out. Do not set the sync parameter as true if you need the receiver to receive the data packet immediately. Agora recommends that you set the sync parameter to true only when you need to implement specific functions, for example, lyric synchronization.
Parameters
streamIdOutput parameter. A pointer to the ID of the created data stream.
reliableWhether or not the data stream is reliable:
  • true: The recipients receive the data from the sender within five seconds.
  • 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.
orderedWhether 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 stream in the sent order.
syncWhether to synchronize the data packet with the published audio packet.
  • true: Synchronize the data packet with the audio packet.
  • false: Do not synchronize the data packet with the audio packet.
Returns
  • 0: Success.
  • < 0: Failure.

◆ disconnect()

virtual int agora::rtc::IRtcConnection::disconnect ( )
pure virtual

Disconnects from the Agora channel.

Once your app successful disconnects from the channel, the connection state changes to CONNECTION_STATE_DISCONNECTED(1). You are also notified with the callback onDisconnected.

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

◆ enableEncryption()

virtual int agora::rtc::IRtcConnection::enableEncryption ( bool  enabled,
const EncryptionConfig config 
)
pure virtual

Enables/Disables the built-in encryption.

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. Once all users leave the channel, the encryption key of this channel is automatically cleared.

Note
If you enable the built-in encryption, you cannot use the CDN streaming function.
Parameters
enabledWhether to enable the built-in encryption:
  • true: Enable the built-in encryption.
  • false: Disable the built-in encryption.
configConfigurations of built-in encryption schemas. See EncryptionConfig.
Returns
  • 0: Success.
  • < 0: Failure.

◆ getAgoraParameter()

virtual agora::base::IAgoraParameter * agora::rtc::IRtcConnection::getAgoraParameter ( )
pure virtual

Gets the IAgoraParameter object.

Returns

◆ getConnectionInfo()

virtual TConnectionInfo agora::rtc::IRtcConnection::getConnectionInfo ( )
pure virtual

Gets the connection information.

Returns
  • The pointer to the TConnectionInfo object: Success.
  • A null pointer: Failure.

◆ getConnId()

virtual conn_id_t agora::rtc::IRtcConnection::getConnId ( )
pure virtual

Gets the ID of the connection.

Returns
  • The connection ID: Success.
  • A null pointer: Failure.

◆ getLocalUser()

virtual ILocalUser * agora::rtc::IRtcConnection::getLocalUser ( )
pure virtual

Gets the ILocalUser object.

Returns
  • The pointer to the ILocalUser object: Success.
  • A null pointer: Failure.

◆ getRemoteUsers()

virtual int agora::rtc::IRtcConnection::getRemoteUsers ( UserList users)
pure virtual

Gets the information of all the remote users in the channel.

After a user successfully connects to the channel, you can also get the information of this remote user with the onUserJoined callback.

Parameters
[out]usersThe reference to the UserList object, which contains the information of all users in the channel.
Returns
  • 0: Success.
  • < 0: Failure.

◆ getTransportStats()

virtual RtcStats agora::rtc::IRtcConnection::getTransportStats ( )
pure virtual

Gets the transportation statistics of the RTC connection.

Returns
  • The pointer to RtcStats: Success.
  • A null pointer: Failure.

◆ getUserInfo()

virtual int agora::rtc::IRtcConnection::getUserInfo ( user_id_t  userId,
agora::UserInfo userInfo 
)
pure virtual

Gets the information of a specified remote user in the channel.

Parameters
[in]userIdID of the user whose information you want to get.
[out]userInfoThe reference to the UserInfo object, which contains the information of the specified user.
Returns
  • 0: Success.
  • < 0: Failure.

◆ getUserInfoByUid()

virtual int agora::rtc::IRtcConnection::getUserInfoByUid ( uid_t  uid,
rtc::UserInfo userInfo 
)
pure virtual

Gets the user information by user ID, which is in integer format.

Parameters
uidThe ID of the remote user.
[in,out]userInfoA UserInfo object that identifies the user:
  • Input: A userInfo object.
  • Output: A userInfo object that contains the user account and user ID of the user.
Returns
  • 0: Success.
  • < 0: Failure.

◆ getUserInfoByUserAccount()

virtual int agora::rtc::IRtcConnection::getUserInfoByUserAccount ( const char *  userAccount,
rtc::UserInfo userInfo 
)
pure virtual

Gets the user information by user account, which is in string format.

Parameters
userAccountThe user account of the user.
[in,out]userInfoA UserInfo object that identifies the user:
  • Input: A userInfo object.
  • Output: A userInfo object that contains the user account and user ID of the user.
Returns
  • 0: Success.
  • < 0: Failure.

◆ registerNetworkObserver()

virtual int agora::rtc::IRtcConnection::registerNetworkObserver ( INetworkObserver observer,
void(*)(INetworkObserver *)  safeDeleter = NULL 
)
pure virtual

Registers an network observer object.

Parameters
observerThe pointer to the INetworkObserver object.
Returns
  • 0: Success.
  • < 0: Failure.

◆ registerObserver()

virtual int agora::rtc::IRtcConnection::registerObserver ( IRtcConnectionObserver observer,
void(*)(IRtcConnectionObserver *)  safeDeleter = NULL 
)
pure virtual

Registers an RTC connection observer. You can call this method only after creating an IRtcConnection object.

Parameters
observerThe pointer to the IRtcConnectionObserver object.
Returns
  • 0: Success.
  • < 0: Failure.

◆ renewToken()

virtual int agora::rtc::IRtcConnection::renewToken ( const char *  token)
pure virtual

Renews the token.

The token expires after a certain period of time.

When the onTokenPrivilegeWillExpire callback reports ERR_TOKEN_EXPIRED(109), you must generate a new token from the server and then call this method to renew it. Otherwise, the SDK disconnects from the Agora RTC channel.

Parameters
tokenThe pointer to the new token.

◆ sendStreamMessage()

virtual int agora::rtc::IRtcConnection::sendStreamMessage ( int  streamId,
const char *  data,
size_t  length 
)
pure virtual

Sends data stream messages.

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 method call triggers the onStreamMessage callback on the remote client, from which the remote user gets the stream message.

Note
  • Ensure that you call createDataStream to create a data channel before calling this method.
  • In live streaming scenarios, this method only applies to hosts.
Parameters
streamIdThe data stream ID. You can get the data stream ID by calling createDataStream.
dataThe message to be sent.
lengthThe length of the data.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startLastmileProbeTest()

virtual int agora::rtc::IRtcConnection::startLastmileProbeTest ( const LastmileProbeConfig config)
pure virtual

Starts the last-mile network probe test.

Call this method before connecting to the channel to get the uplink and downlink last-mile network statistics, including the bandwidth, packet loss, jitter, and round-trip time (RTT).

After you enable the last-mile network probe test, the SDK triggers the following callbacks:

  • 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 reports the real-time statistics of the network conditions and is more objective.
Note
  • Do not call any other method before receiving the onLastmileQuality and onLastmileProbeResult callbacks. Otherwise, the callbacks may be interrupted.
  • In the live-broadcast profile, a host should not call this method after connecting to a channel.
Parameters
configThe configurations of the last-mile network probe test. See LastmileProbeConfig.
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopLastmileProbeTest()

virtual int agora::rtc::IRtcConnection::stopLastmileProbeTest ( )
pure virtual

Stops the last-mile network probe test.

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

◆ unregisterNetworkObserver()

virtual int agora::rtc::IRtcConnection::unregisterNetworkObserver ( INetworkObserver observer)
pure virtual

Releases the registered INetworkObserver object.

Parameters
observerThe pointer to the INetworkObserver object created by the registerNetworkObserver method.
Returns
  • 0: Success.
  • < 0: Failure.

◆ unregisterObserver()

virtual int agora::rtc::IRtcConnection::unregisterObserver ( IRtcConnectionObserver observer)
pure virtual

Releases the registered IRtcConnectionObserver object.

Parameters
observerThe pointer to the IRtcConnectionObserver object created by the registerObserver method.
Returns
  • 0: Success.
  • < 0: Failure.

The documentation for this class was generated from the following file: