Agora C++ API Reference for All Platforms

Public Member Functions | Protected Member Functions | List of all members
agora::rtc::IRtcConnection Class Referenceabstract

Inherits agora::RefCountInterface.

Inherited by agora::rtc::IRtcConnectionEx.

## Public Member Functions
virtual int | connect (const char *token, const char *channelId, const char *info, user_id_t userId, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | connect (const TConnectSettings &settings, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | disconnect (aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | startLastmileProbeTest (const LastmileProbeConfig &config, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | stopLastmileProbeTest (aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | renewToken (const char *token, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual TConnectionInfo | getConnectionInfo ()=0
virtual ILocalUser * | getLocalUser ()=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, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | unregisterObserver (IRtcConnectionObserver *observer)=0
virtual int | registerNetworkObserver (INetworkObserver *observer, void(*safeDeleter)(INetworkObserver *)=NULL, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | unregisterNetworkObserver (INetworkObserver *observer)=0
virtual conn_id_t | getConnId ()=0
virtual RtcStats | getTransportStats ()=0
virtual agora::base::IAgoraParameter * | getAgoraParameter ()=0
virtual int | createDataStream (int *streamId, bool reliable, bool ordered, bool sync)=0
virtual int | sendStreamMessage (int streamId, const char *data, size_t length, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | enableEncryption (bool enabled, const EncryptionConfig &config, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | sendCustomReportMessage (const char *id, const char *category, const char *event, const char *label, int value, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | getUserInfoByUserAccount (const char *userAccount, rtc::UserInfo *userInfo)=0
virtual int | getUserInfoByUid (uid_t uid, rtc::UserInfo *userInfo)=0
Public Member Functions inherited from agora::RefCountInterface
virtual void | AddRef () const =0
virtual RefCountReleaseStatus | Release () const =0
virtual bool | HasOneRef () const =0

## Protected Member Functions
| ~IRtcConnection ()
Protected Member Functions inherited from agora::RefCountInterface
virtual | ~RefCountInterface ()

## 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 | ( |  | ) |
| inline protected

## Member Function Documentation

## ◆ connect() [1/2]

virtual int agora::rtc::IRtcConnection::connect | ( | const char * | token,
|  | const char * | channelId,
|  | const char * | info,
|  | user_id_t | userId,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| 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

  token | The app ID.
  channelId | The 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: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
  userId | The 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).

## ◆ connect() [2/2]

virtual int agora::rtc::IRtcConnection::connect | ( | const TConnectSettings & | settings,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| 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

  settings | The settings of connecting.

## ◆ disconnect()

virtual int agora::rtc::IRtcConnection::disconnect | ( | aosl_ref_t | ares = `AOSL_REF_INVALID` | ) |
| 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.

## ◆ startLastmileProbeTest()

virtual int agora::rtc::IRtcConnection::startLastmileProbeTest | ( | const LastmileProbeConfig & | config,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| 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

  config | The configurations of the last-mile network probe test. See LastmileProbeConfig.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ stopLastmileProbeTest()

virtual int agora::rtc::IRtcConnection::stopLastmileProbeTest | ( | aosl_ref_t | ares = `AOSL_REF_INVALID` | ) |
| pure virtual

Stops the last-mile network probe test.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ renewToken()

virtual int agora::rtc::IRtcConnection::renewToken | ( | const char * | token,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Renews the token.

The token expires after a certain period of time. When the onError 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 channel.

Parameters

  token | The pointer to the new token.

## ◆ 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.

## ◆ 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] | users | The reference to the UserList object, which contains the information of all users in the channel.

Returns
  - 0: Success.
  - < 0: 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] | userId | ID of the user whose information you want to get.
  [out] | userInfo | The reference to the UserInfo object, which contains the information of the specified user.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ registerObserver()

virtual int agora::rtc::IRtcConnection::registerObserver | ( | IRtcConnectionObserver * | observer,
|  | void(*)(IRtcConnectionObserver *) | safeDeleter = `NULL`,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

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

Parameters

  observer | The pointer to the IRtcConnectionObserver object.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ unregisterObserver()

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

Releases the registered IRtcConnectionObserver object.

Parameters

  observer | The pointer to the IRtcConnectionObserver object created by the registerObserver method.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ registerNetworkObserver()

virtual int agora::rtc::IRtcConnection::registerNetworkObserver | ( | INetworkObserver * | observer,
|  | void(*)(INetworkObserver *) | safeDeleter = `NULL`,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Registers an network observer object.

Parameters

  observer | The pointer to the INetworkObserver object.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ unregisterNetworkObserver()

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

Releases the registered INetworkObserver object.

Parameters

  observer | The pointer to the INetworkObserver object created by the registerNetworkObserver method.

Returns
  - 0: Success.
  - < 0: 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.

## ◆ 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.

## ◆ getAgoraParameter()

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

Gets the IAgoraParameter object.

Returns
  - The pointer to the IAgoraParameter object.
  - A null pointer: Failure.

Implemented in agora::rtc::IRtcConnectionEx.

## ◆ 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 during the lifecycle of an RTC connection.

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

Parameters

  streamId | The pointer to the ID of the data stream.
  reliable | Whether to guarantee the receivers receive the data stream within five seconds: `true`: Guarantee that the receivers receive the data stream within five seconds. If the receivers do not receive the data stream within five seconds, the SDK reports an error to the application. `false`: Do not guarantee that the receivers receive the data stream within five seconds and the SDK does not report any error message for data stream delay or missing.
  ordered | Whether the receivers receive the data stream in the order of sending: `true`: The receivers receive the data stream in the order of sending. `false`: The receivers do not receive the data stream in the order of sending.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ sendStreamMessage()

virtual int agora::rtc::IRtcConnection::sendStreamMessage | ( | int | streamId,
|  | const char * | data,
|  | size_t | length,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Sends data stream messages to all users in a channel.

Note
  This method has the following restrictions:
  - Up to 30 packets can be sent per second in a channel with a maximum size of 1 kB for each packet.
  - Each client can send up to 6 kB of data per second.
  - Each user can have up to five data streams simultaneously.

Parameters

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

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ enableEncryption()

virtual int agora::rtc::IRtcConnection::enableEncryption | ( | bool | enabled,
|  | const EncryptionConfig & | config,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| 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 RTMP streaming function.

Parameters

  enabled | Whether to enable the built-in encryption: true: Enable the built-in encryption. false: Disable the built-in encryption.
  config | Configurations of built-in encryption schemas. See EncryptionConfig.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ sendCustomReportMessage()

virtual int agora::rtc::IRtcConnection::sendCustomReportMessage | ( | const char * | id,
|  | const char * | category,
|  | const char * | event,
|  | const char * | label,
|  | int | value,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Reports a custom event to Agora.

Parameters

  id | The custom event ID.
  category | The category of the custom event.
  event | The custom event to report.
  label | The label of the custom event.
  value | The value of the custom event.

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

  | userAccount | The user account of the user.
  [in,out] | userInfo | A 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.

## ◆ 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

  | uid | The ID of the remote user.
  [in,out] | userInfo | A 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.