Agora RTC Objective-C API Reference  Refactor
Instance Methods
AgoraRtcEngineKit(Ex) Category Reference

Instance Methods

(int) - joinChannelExByToken:channelId:uid:connectionId:delegate:mediaOptions:joinSuccess:
 
(int) - updateChannelExWithMediaOptions:connectionId:
 
(int) - muteRemoteAudioStreamEx:mute:connectionId:
 
(int) - setVideoEncoderConfigurationEx:connectionId:
 
(int) - setupRemoteVideoEx:connectionId:
 
(int) - setRemoteRenderModeEx:mode:connectionId:
 
(int) - muteRemoteVideoStreamEx:mute:connectionId:
 
(BOOL) - pushExternalVideoFrame:connectionId:
 

Method Documentation

◆ joinChannelExByToken:channelId:uid:connectionId:delegate:mediaOptions:joinSuccess:

- (int) joinChannelExByToken: (NSString *_Nullable)  token
channelId: (NSString *_Nonnull)  channelId
uid: (NSUInteger)  uid
connectionId: (unsigned int *)  connectionId
delegate: (id< AgoraRtcEngineDelegate > _Nullable)  delegate
mediaOptions: (AgoraRtcChannelMediaOptions *_Nonnull)  mediaOptions
joinSuccess: (void(^)(NSString *_Nonnull channel, NSUInteger uid, NSInteger elapsed))  joinSuccessBlock 

Joins a channel.

Users in the same channel can talk to each other, and multiple users in the same channel can start a group chat. Users with different App IDs cannot call each other even if they join the same channel.

You must call the leaveChannel method to exit the current call before entering another channel. This method call is asynchronous; therefore, you can call this method in the main user interface thread.

A successful method call triggers the following callbacks:

  • The local client: didJoinChannel.
  • The remote client: didJoinedOfUid, if the user joining the channel is in the Communication profile, or is a BROADCASTER in the Live Broadcast profile.

When the connection between the client and Agora's server is interrupted due to poor network conditions, the SDK tries reconnecting to the server. When the local client successfully rejoins the channel, the SDK triggers the didRejoinChannel callback on the local client.

Note
  • When joining a channel, the SDK calls setCategory(AVAudioSessionCategoryPlayAndRecord) to set AVAudioSession to PlayAndRecord mode. When AVAudioSession is set to PlayAndRecord mode, the sound played (for example a ringtone) is interrupted. The app should not set AVAudioSession to any other mode.
  • The SDK uses the iOS's AVAudioSession shared object for audio recording and playback. Using this object may affect the SDK’s audio functions.
Parameters
tokenThe 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 you server. For details, see Generate a token.
channelIdUnique channel name for the AgoraRTC session in the string format. The string length must be less than 64 bytes. 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: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
info(Optional) Additional information about the channel. This parameter can be set to nil or contain channel related information. Other users in the channel do not receive this message.
uidUser ID. A 32-bit unsigned integer with a value ranging from 1 to (232-1). The uid must be unique. If a uid is not assigned (or set to 0), the SDK assigns and returns a uid in the callback. Your app must record and maintain the returned uid since the SDK does not do so.
connectionIdpointer to connection ID, out param
mediaOptionsAgoraRtcChannelMediaOptions Object.
joinSuccessBlockSame as didJoinChannel. We recommend you set this parameter as nil to use didJoinChannel.
  • If joinSuccessBlock is nil, the SDK triggers the didJoinChannel callback.
  • If you implement both joinSuccessBlock and didJoinChannel, joinSuccessBlock takes higher priority than didJoinChannel.
Returns
  • 0: Success.
  • < 0: Failure.

Extends class AgoraRtcEngineKit.

◆ updateChannelExWithMediaOptions:connectionId:

- (int) updateChannelExWithMediaOptions: (AgoraRtcChannelMediaOptions *_Nonnull)  mediaOptions
connectionId: (unsigned int)  connectionId 

Updates the channel media options after joining the channel.

Parameters
mediaOptionsThe channel media options: ChannelMediaOptions.
connectionIdconnection ID
Returns
  • 0: Success.
  • < 0: Failure.

Extends class AgoraRtcEngineKit.

◆ muteRemoteAudioStreamEx:mute:connectionId:

- (int) muteRemoteAudioStreamEx: (NSUInteger)  uid
mute: (BOOL)  mute
connectionId: (unsigned int)  connectionId 

Mutes a specified remote user's audio stream.

Note
When setting to YES, this method stops playing audio streams without affecting the audio stream receiving process.
Parameters
uidUser ID whose audio streams the user intends to mute.
mute* YES: Stops playing a specified user’s audio streams. NO: Resumes playing a specified user’s audio streams.
connectionIdconnection ID.
Returns
* 0: Success. <0: Failure.

Extends class AgoraRtcEngineKit.

◆ setVideoEncoderConfigurationEx:connectionId:

- (int) setVideoEncoderConfigurationEx: (AgoraVideoEncoderConfiguration *_Nonnull)  config
connectionId: (unsigned int)  connectionId 

Sets the video encoder configuration.

Each configuration profile corresponds to a set of video parameters, including the resolution, frame rate, and bitrate.

The parameters specified in this method are the maximum values under ideal network conditions. If the video engine cannot render the video using the specified parameters due to poor network conditions, the parameters further down the list are considered until a successful configuration is found.

Parameters
configThe local video encoder configuration, see #AgoraVideoEncoderConfiguration.
connectionIdconnection ID.
Returns
  • 0: Success.
  • < 0: Failure.

Extends class AgoraRtcEngineKit.

◆ setupRemoteVideoEx:connectionId:

- (int) setupRemoteVideoEx: (AgoraRtcVideoCanvas *_Nonnull)  remote
connectionId: (unsigned int)  connectionId 

Binds the remote user to the video display window, that is, sets the view for the user of the specified uid.

Usually, the application should specify the uid of the remote video in the method call before the user enters a channel. If the remote uid is unknown to the application, set it later when the application receives the [userJoinedBlock]([AgoraRtcEngineKit userJoinedBlock:]) event. If the Video Recording function is enabled, the Video Recording Service joins the channel as a dumb client, which means other clients will also receive the [didJoinedOfUid]([AgoraRtcEngineDelegate rtcEngine:didJoinedOfUid:elapsed:]) event. Your application should not bind it with the view, because it does not send any video stream. If your application cannot recognize the dumb client, bind it with the view when the [firstRemoteVideoDecodedOfUid]([AgoraRtcEngineDelegate rtcEngine:firstRemoteVideoDecodedOfUid:size:elapsed:]) event is triggered. To unbind the user with the view, set the view to null. After the user has left the channel, the SDK unbinds the remote user.

Parameters
remoteAgoraRtcVideoCanvas
connectionIdconnection ID.
Returns
* 0: Success. <0: Failure.

Extends class AgoraRtcEngineKit.

◆ setRemoteRenderModeEx:mode:connectionId:

- (int) setRemoteRenderModeEx: (NSUInteger)  uid
mode: (AgoraVideoRenderMode)  mode
connectionId: (unsigned int)  connectionId 

Configures the remote video display mode. The application can call this method multiple times to change the display mode.

Parameters
uidUser id of the user whose video streams are received.
modeAgoraVideoRenderMode
connectionIdconnection ID.
Returns
* 0: Success. <0: Failure.

Extends class AgoraRtcEngineKit.

◆ muteRemoteVideoStreamEx:mute:connectionId:

- (int) muteRemoteVideoStreamEx: (NSUInteger)  uid
mute: (BOOL)  mute
connectionId: (unsigned int)  connectionId 

Stops or resumes receiving the video stream of a specified user.

Note
Once you leave the channel, the settings in this method becomes invalid.
Parameters
uidID of the specified remote user.
muteDetermines whether to receive or stop receiving a specified video stream:
  • YES: Stop receiving the specified video stream.
  • NO: (Default) Receive the specified video stream.
connectionIdconnection ID.
Returns
  • 0: Success.
  • < 0: Failure.

Extends class AgoraRtcEngineKit.

◆ pushExternalVideoFrame:connectionId:

- (BOOL) pushExternalVideoFrame: (AgoraVideoFrame *_Nonnull)  frame
connectionId: (unsigned int)  connectionId 

Pushes the external video frame.

This method pushes the video frame using the AgoraVideoFrame class and passes it to the Agora SDK with the format parameter in AgoraVideoFormat.

Call setExternalVideoSource and set the pushMode parameter as YES before calling this method.

Note
In the Communication profile, this method does not support pushing textured video frames.
Parameters
frameVideo frame containing the SDK's encoded video data to be pushed: AgoraVideoFrame.
connectionIdconnection ID.
Returns
  • YES: Success.
  • NO: Failure.

Extends class AgoraRtcEngineKit.

◆ sendCustomReportMessageEx:category:event:label:value:connectionId:

- (int) sendCustomReportMessageEx: (NSString *_Nullable)  messageId
category: (NSString *_Nullable)  category
event: (NSString *_Nullable)  event
label: (NSString *_Nullable)  label
value: (NSInteger)  value
connectionId: (unsigned int)  connectionId 

Extends class AgoraRtcEngineKit.