The common interface of NERtcEngine. More...

#import <INERtcEngine.h>

Inheritance diagram for <INERtcEngine>:

Instance Methods
(NERtcConnectionStateType)	- connectionState
	Gets the connection status. More...

(int)	- setupEngineWithContext:
	Creates an NERtcEngine instance and initializes the NERTC SDK. More...

(int)	- joinChannelWithToken:channelName:myUid:completion:
	Joins an RTC room. More...

(int)	- leaveChannel
	Leaves a room, such as hanging up or ending a call. More...

(int)	- switchChannelWithToken:channelName:completion:
	Switches to a different RTC room. More...

(int)	- enableLocalAudio:
	Enables or disables local audio capture. More...

(int)	- enableLocalVideo:
	Specifies whether to enable local video capture. More...

(int)	- enableMediaPub:withMediaType:
	Publishes or unpublishes the local audio stream. More...

(int)	- setChannelProfile:
	Sets a room scene. More...

(int)	- setLocalVideoConfig:
	Sets the video encoding profile. More...

(int)	- setAudioProfile:scenario:
	Sets the audio encoding profile. More...

(int)	- setupLocalVideoCanvas:
	Sets the local view. More...

(int)	- setupRemoteVideoCanvas:forUserID:
	Sets views for remote users. More...

(int)	- switchCamera
	Switches between the front and rear cameras. More...

(int)	- setClientRole:
	Sets the role of a user in live streaming. More...

(int)	- setParameters:
	Sets parameters for audio and video calls. More...

Detailed Description

The common interface of NERtcEngine.

Method Documentation

◆ connectionState

- (NERtcConnectionStateType) connectionState

Gets the connection status.

Returns: The current network status is returned.

◆ enableLocalAudio:

- (int) enableLocalAudio: (BOOL) enabled

Enables or disables local audio capture.

When an app joins a room, the voice module is enabled by default.
The method does not affect receiving or playing back the remote audio stream. The enableLocalAudio(NO) method is suitable for scenarios where a user wants to receive the remote audio stream without sending audio streams to other users in the room.

Note

The enableLocalAudio method is different from muteLocalAudioStream. The enableLocalAudio method is used to enable local audio capture and processing whereas the muteLocalAudioStream method is used to stop or restart pushing the local audio stream.
The method enables the internal engine. The setting remains unchanged after the leaveChannel method is called.
Starting from V4.4.0, turning on or off local audio capture does not affect the playback of music files. You can still play music files by calling startAudioMixingWithOption after you set enableLocalAudio(NO).

Parameters

enabled The option whether to enable local Audio capture.

Returns: The value returned. A value of 0 indicates that the operation is successful.

◆ enableLocalVideo:

- (int) enableLocalVideo: (BOOL) enabled

Specifies whether to enable local video capture.

Note

You can call this method before or after you join a room.
After you enable or disable local video capture, the onNERtcEngineUserVideoDidStartWithUserID or onNERtcEngineUserVideoDidStop callback is triggered on a remote client.

Parameters

enabled The option whether to enable local video capture.

Returns: The value returned. A value of 0 indicates that the operation is successful.

◆ enableMediaPub:withMediaType:

- (int) enableMediaPub:	(BOOL)	enabled
withMediaType:	(NERtcMediaPubType)	mediaType

Publishes or unpublishes the local audio stream.

When a user joins a room, the feature is enabled by default.
The method does not affect receiving or playing the remote audio stream. The enableLocalAudio(false) method is suitable for scenarios where clients only receives remote media streams and does not publish any local streams.

Note

The method controls data transmitted over the main stream
The method can be called before or after a user joins a room.

Since: V4.6.10

Parameters

enable	specifies whether to publish the local audio stream. true(default): publishes the local audio stream. false: unpublishes the local audio stream.
mediaType	media type. Audio type is supported.

Returns

0: success
Others: failure if Chinese 发布/停止本地音频。
当用户加入房间时，此功能默认为开启状态。
该方法不影响接收或播放远端音频流，enableLocalAudio(false) 适用于只下行不上行音频流的场景。

Note

该方法只控制主流。
该方法在加入房间前后均可调用。

Since: V4.6.10

Parameters

enabled	是否发布本地语音。 YES（默认）：发布本地语音，即音频上行。 NO：不发布本地语音，即停止本地音频上行。
mediaType	发布类型，暂时仅支持音频。

Returns

0：方法调用成功。
其他：方法调用失败。

◆ joinChannelWithToken:channelName:myUid:completion:

- (int) joinChannelWithToken:	(NSString *)	token
channelName:	(NSString *)	channelName
myUid:	(uint64_t)	uId
completion:	(NERtcJoinChannelCompletion)	completion

Joins an RTC room.

If the specified room does not exist when you join the room, a room with the specified name is automatically created in the server provided by CommsEase.

After you join a room by calling the relevant method supported by the SDK, users in the same room can make audio or video calls. Users that join the same room can start a group chat. Apps that use different AppKeys cannot communicate with each other.
If you join a room by calling this method, onNERtcEngineUserDidJoinWithUserID is triggered on a remote client.
If you join a room, you subscribe to the audio streams from other users in the same room by default. In this case, the data usage is billed. To unsubscribe, you can call the mute method.

In live streaming, the audience can switch rooms by calling switchChannelWithToken.

Parameters

token	The certification signature used in authentication (NERTC Token). Valid values: null. You can set the value to null in the debugging mode. This poses a security risk. We recommend that you contact your business manager to change to the default safe mode before your product is officially launched. NERTC Token acquired. In safe mode, the acquired token must be specified. If the specified token is invalid, users are unable to join a room. We recommend that you use the safe mode.
channelName	The name of the room. Users that use the same name can join the same room. < br>The name must be of STRING type and must be 1 to 64 characters in length. The following 89 characters are supported: a-z, A-Z, 0-9, space, !#$%&()+-:;≤.,>? @[]^_{\|}~”
uId	The unique identifier of a user. The uId of each user in a room must unique. uId is optional, The default value is 0. If the uId is not specified (set to 0), the SDK automatically assigns a random uId and returns the uId in NERtcJoinChannelCompletion. The application layer must keep and maintain the return value. The SDK does not maintain the return value.
completion	The callback when the operation is complete.

Returns: The value returned. A value of 0 indicates that the operation is performed.

◆ leaveChannel

- (int) leaveChannel

Leaves a room, such as hanging up or ending a call.

A user must call the leaveChannel method to end the call before the user makes another call.
After you leave the room by calling the method, the onNERtcEngineDidLeaveChannelWithResult callback is triggered on the local client, and the onNERtcEngineUserDidLeaveWithUserID callback is triggered on a remote client.

Returns: The value returned. A value of 0 indicates that the operation is successful.

◆ setAudioProfile:scenario:

- (int) setAudioProfile:	(NERtcAudioProfileType)	profile
scenario:	(NERtcAudioScenarioType)	scenario

Sets the audio encoding profile.

Note: You must call this method before you call the joinChannel method. Otherwise, the settings of joinChannel do not take effect.

Parameters

profile	The sample rate, bitrate, encoding mode, and the number of channels. For more information, see `NERtcAudioProfileType`.
scenario	The type of an audio scenario. For more information, see `NERtcAudioScenarioType`.

Returns: The value returned. A value of 0 indicates that the operation is successful.

◆ setChannelProfile:

- (int) setChannelProfile: (NERtcChannelProfileType) channelProfile

Sets a room scene.

You can set a room scene for a call or live event. Different QoS policies are applied to different scenes.

Note: You must call the method before you join a room. If you have joined a room, you cannot set the room scene.

Parameters

channelProfile The room scene. For more information, see NERtcEngineEnum.NERtcChannelProfileType.

Returns: The value returned. A value of 0 indicates that the operation is successful.

◆ setClientRole:

- (int) setClientRole: (NERtcClientRole) role

Sets the role of a user in live streaming.

The method sets the role to host or audience. The permissions of a host and an audience are different.

A host has the permissions to open or close a camera, publish streams, call methods related to publishing streams in *Interactive live streaming. The status of the host is visible to the users in the room when the host joins or leaves the room.
The audience has no permissions to open or close a camera, call methods related to publishing streams in interactive live streaming, and is invisible to other users in the room when the user that has the audience role joins or leaves the room.
Note
By default, a user joins a room as a host. Before a user joins a room, the user can call this method to change the client role to the audiences. After a user joins a room, the user can call this method to switch the client role.
If the user switches the role to the audiences, the SDK automatically closes the audio and video devices.
Parameters

role The role of a user. For more information, see NERtcClientRole.

Returns
The value returned. A value of 0 indicates that the operation is successful.

◆ setLocalVideoConfig:

- (int) setLocalVideoConfig: (NERtcVideoEncodeConfiguration *) config

Sets the video encoding profile.

Note

The audio-only SDK disables this API. If you need to use the API, you can download the standard SDK from the official website of CommsEase and replace the audio-only SDK.
You can call this method before or after you join the room.
After the setting is configured. The setting takes effect the next time local video is enabled.
Each profile has a set of video parameters, such as resolution, frame rate, and bitrate. All the specified values of the parameters are the maximum values in optimal conditions. If the video engine cannot use the maximum value of resolution, frame rate, or bitrate due to unreliable network conditions, the value closest to the maximum value is used.

Parameters

config The video encoding profile. For more information, see NERtcVideoEncodeConfiguration.

Returns: The value returned. A value of 0 indicates that the operation is successful.

◆ setParameters:

- (int) setParameters: (NSDictionary *) parameters

Sets parameters for audio and video calls.

Note

You can call the method only after you join a room. When you use kNERtcKeyVideoPreferHWEncode and kNERtcKeyVideoPreferHWDecode, you must call this method before you initialize the SDK.
This method provides a technology preview or personalized features. If you want to use this API, contact technical support.

Parameters

parameters The parameters that you want to specify. For more information about the key parameters, see the definition in NERtcEngineBase.h.

Returns: The value returned. A value of 0 indicates that the operation is successful.

◆ setupEngineWithContext:

- (int) setupEngineWithContext: (NERtcEngineContext *) context

Creates an NERtcEngine instance and initializes the NERTC SDK.

Note

Before you call other APIs, you must first call this method to create and initialize an NERtc instance.
Apps that use the same AppKey can make audio or video calls, or perform live events in the same room.
One AppKey can be used to create only one NERtc instance. If you want to change the AppKey, you must first delete the current instance by calling the destroyEngine method, then, call this method to create a new instance.
If you do not need the NERtc instance, you can delete the instance by calling the destroyEngine method.

Parameters

context The RTC engine context object passed. For more information, see NERtcEngineContext.

Returns: The value returned. A value of 0 indicates that the operation is successful.

◆ setupLocalVideoCanvas:

- (int) setupLocalVideoCanvas: (NERtcVideoCanvas *_Nullable) canvas

Sets the local view.

This method is used to set the display information about the local video. The method is applicable only to local users. Remote users are not affected. Apps can call this API operation to associate with the view that plays local video streams. During application development, in most cases, before joining a room, you must first call this method to set the local video view after the SDK is initialized.

Note: The audio-only SDK disables this API. If you need to use the API, you can download the standard SDK from the official website of CommsEase and replace the audio-only SDK.

Parameters

canvas The video canvas. For more information, see NERtcVideoCanvas. If you want to delete the canvas, you can set the value to nil.

Returns: The value returned. A value of 0 indicates that the operation is successful.

◆ setupRemoteVideoCanvas:forUserID:

- (int) setupRemoteVideoCanvas:	(NERtcVideoCanvas *_Nullable)	canvas
forUserID:	(uint64_t)	userID

Sets views for remote users.

This method is used to associate remote users with display views and configure the rendering mode and mirror mode for remote views displayed locally. The method affects only the video screen viewed by local users.

Note

The audio-only SDK disables this API. If you need to use the API, you can download the standard SDK from the official website of CommsEase and replace the audio-only SDK.
If the user ID is not retrieved, you can set the user ID after the app receives a message delivered when the onNERtcEngineUserDidJoinWithUserID event is triggered.
To disassociate a specified user from a view, you can leave the canvas parameter empty.
After a user leaves the room, the association between a remote user and the view is cleared.

Parameters

userID	The ID of a remote user.
canvas	The video window. if you want to delete the canvas, you can set the value to nil.

Returns: The value returned. A value of 0 indicates that the operation is successful.

◆ switchCamera

- (int) switchCamera

Switches between the front and rear cameras.

Make sure that you call this method after the camera starts. For example, you can call this method after you call startPreview or joinChannel.

Note: The audio-only SDK disables this API. If you need to use the API, you can download the standard SDK from the official website of CommsEase and replace the audio-only SDK.

Returns: The value returned. A value of 0 indicates that the operation is successful.

◆ switchChannelWithToken:channelName:completion:

- (int) switchChannelWithToken:	(NSString *)	token
channelName:	(NSString *)	channelName
completion:	(NERtcJoinChannelCompletion)	completion

Switches to a different RTC room.

In live streaming, the audience can call this method to switch from the current room to another room.
After you successfully switch to the destination room, the local client receives a message sent by onNERtcEngineDidLeaveChannelWithResult. The remote user receives messages sent by onNERtcEngineUserDidLeaveWithUserID and onNERtcEngineUserDidJoinWithUserID.

Note

By default, after a room member switches to another room, the room member subscribes to audio streams from other members of the new room. In this case, data usage is charged and billing is updated. If you want to unsubscribe from the previous audio stream, you can call the subscribeRemoteAudio method.
The method applies to only live streaming. The role is the audience in the RTC room. The room scene is set to live streaming by calling the setchannelprofile method, and the role of room members is set to the audiences by calling the setClientRole method.

Parameters

token	The certification signature generated in the server and used for authentication. Valid values: null. You can set the value to null in the debugging mode. This poses a security risk. We recommend that you contact your business manager to change to the default safe mode before your product is officially launched. NERTC Token acquired. In safe mode, the acquired token must be specified. If the specified token is invalid, users are unable to join a channel. We recommend that you use the safe mode.
channelName	The room name that a user wants to switch to.
completion	The callback when the operation is complete.

Returns: The value returned. A value of 0 indicates that the operation is successful. A value that is less than 0 indicates that The operation fails.

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

exportHeaders/INERtcEngine.h

Instance Methods

Detailed Description

Method Documentation

◆ connectionState

◆ enableLocalAudio:

◆ enableLocalVideo:

◆ enableMediaPub:withMediaType:

◆ joinChannelWithToken:channelName:myUid:completion:

◆ leaveChannel

◆ setAudioProfile:scenario:

◆ setChannelProfile:

◆ setClientRole:

◆ setLocalVideoConfig:

◆ setParameters:

◆ setupEngineWithContext:

◆ setupLocalVideoCanvas:

◆ setupRemoteVideoCanvas:forUserID:

◆ switchCamera

◆ switchChannelWithToken:channelName:completion: