Agora RTC Objective-C API Reference Refactor

Public Member Functions
IRtcConnection Class Referenceabstract

Inherits RefCountInterface.

## 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 | sendRdtMessage (user_id_t userId, RdtStreamType type, const char *data, size_t length, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | sendMediaControlMessage (user_id_t userId, 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
virtual int | enableMultipath (bool enable, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | setUplinkMultipathMode (MultipathMode mode, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | setDownlinkMultipathMode (MultipathMode mode, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | setPreferMultipathType (MultipathType type, aosl_ref_t ares=AOSL_REF_INVALID)=0

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

~IRtcConnection | ( |  | ) |
| inline protected

## Member Function Documentation

## ◆ connect() [1/2]

virtual int 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 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 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 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 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 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. The SDK triggers the onRenewTokenResult callback after the token is renewed.

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 getConnectionInfo | ( |  | ) |
| pure virtual

Gets the connection information.

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

## ◆ getLocalUser()

virtual ILocalUser* getLocalUser | ( |  | ) |
| pure virtual

Gets the ILocalUser object.

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

## ◆ getRemoteUsers()

virtual int 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 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 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 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 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 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 getConnId | ( |  | ) |
| pure virtual

Gets the ID of the connection.

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

## ◆ getTransportStats()

virtual RtcStats 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* getAgoraParameter | ( |  | ) |
| pure virtual

Gets the IAgoraParameter object.

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

## ◆ createDataStream()

virtual int 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 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.

## ◆ sendRdtMessage()

virtual int sendRdtMessage | ( | user_id_t | userId,
|  | RdtStreamType | type,
|  | const char * | data,
|  | size_t | length,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Send Reliable message to remote uid in channel.

Parameters

  UserId | remote user id.
  type | Reliable Data Transmission tunnel message type.
  data | The pointer to the sent data.
  length | The length of the sent data.

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

## ◆ sendMediaControlMessage()

virtual int sendMediaControlMessage | ( | user_id_t | userId,
|  | const char * | data,
|  | size_t | length,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Send Media Control Message to remote uid in channel.

Parameters

  userId | ID of the user who sends the data.
  data | The sending data.
  length | The length (byte) of the data.

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

## ◆ enableEncryption()

virtual int 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 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 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 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.

## ◆ enableMultipath()

virtual int enableMultipath | ( | bool | enable,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Enables or disables the multipath feature.

When enabled, the SDK can use multiple network paths for data transmission, which can improve the reliability and performance of the connection.

Note
  - Permission And System Required:
    - Android: Android 7.0 or later(API level 24 or later), with ACCESS_NETWORK_STATE and CHANGE_NETWORK_STATE permission.
    - IOS: IOS 12.0 or later
    - Macos: 10.14 or later
    - Windows: Windows Vista or later

Parameters

  enable | A boolean value indicating whether to enable (true) or disable (false) multipath.
  ares | A reference for asynchronous operations, defaulting to AOSL_REF_INVALID.

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

## ◆ setUplinkMultipathMode()

virtual int setUplinkMultipathMode | ( | MultipathMode | mode,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Sets the uplink multipath mode.

This method allows the user to specify the mode for uplink multipath transmission. Different modes may optimize for latency, bandwidth, or reliability.

Parameters

  mode | The desired uplink multipath mode.
  ares | A reference for asynchronous operations, defaulting to AOSL_REF_INVALID.

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

## ◆ setDownlinkMultipathMode()

virtual int setDownlinkMultipathMode | ( | MultipathMode | mode,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Sets the downlink multipath mode.

This method allows the user to specify the mode for downlink multipath transmission. Different modes may optimize for latency, bandwidth, or reliability.

Parameters

  mode | The desired downlink multipath mode.
  ares | A reference for asynchronous operations, defaulting to AOSL_REF_INVALID.

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

## ◆ setPreferMultipathType()

virtual int setPreferMultipathType | ( | MultipathType | type,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Sets the preferred multipath type.

This method allows the user to specify the preferred type of multipath transmission. The type may influence how the SDK manages network resources for optimal performance.

Parameters

  type | The preferred multipath type.
  ares | A reference for asynchronous operations, defaulting to AOSL_REF_INVALID.

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

## ◆ AddRef()

virtual void AddRef | ( |  | ) | const
| pure virtual inherited

## ◆ Release()

virtual RefCountReleaseStatus Release | ( |  | ) | const
| pure virtual inherited

## ◆ HasOneRef()

virtual bool HasOneRef | ( |  | ) | const
| pure virtual inherited