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, 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 sendCustomReportMessage (const char *id, const char *category, const char *event, const char *label, int value)=0
 
virtual int getUserInfoByUserAccount (const char *userAccount, rtc::UserInfo *userInfo)=0
 
virtual int getUserInfoByUid (uid_t uid, rtc::UserInfo *userInfo)=0
 
virtual base::NtpTime getNtpTime ()=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 ( )
inlineprotected

Member Function Documentation

◆ connect()

virtual int 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 app ID.
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).

◆ disconnect()

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

◆ startLastmileProbeTest()

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

Stops the last-mile network probe test.

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

◆ renewToken()

virtual int renewToken ( const char *  token)
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
tokenThe 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]usersThe 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]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.

◆ registerObserver()

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

◆ unregisterObserver()

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

◆ registerNetworkObserver()

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

◆ unregisterNetworkObserver()

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

◆ 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

◆ 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
streamIdThe pointer to the ID of the data stream.
reliableWhether 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.
orderedWhether 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 
)
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
streamIdThe ID of the sent data stream, returned in the createDataStream method.
dataThe pointer to the sent data.
lengthThe length of the sent data.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableEncryption()

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

◆ sendCustomReportMessage()

virtual int sendCustomReportMessage ( const char *  id,
const char *  category,
const char *  event,
const char *  label,
int  value 
)
pure virtual

Reports a custom event to Agora.

Parameters
idThe custom event ID.
categoryThe category of the custom event.
eventThe custom event to report.
labelThe label of the custom event.
valueThe 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
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.

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

◆ getNtpTime()

virtual base::NtpTime getNtpTime ( )
pure virtual

Gets the NTP time.

Note
  • Returns the wallclock time which is represented using the timestamp format of the Network Time Protocol (NTP), which is in milliseconds relative to 0h UTC on 1 January 1900.
  • The returned value may not be accurate, depending on whether the connection is normal to the NTP server.
  • The returned value can be validated by base::NtpTime::Valid().
Returns
  • A NtpTime object.

◆ AddRef()

virtual void AddRef ( ) const
pure virtualinherited

◆ Release()

virtual RefCountReleaseStatus Release ( ) const
pure virtualinherited

◆ HasOneRef()

virtual bool HasOneRef ( ) const
pure virtualinherited