AgoraRtcService Class Reference

Inherits from NSObject
Declared in AgoraRtcService.h

+ certificate:

认证 SDK。

+ (int)certificate:(NSString *_Nonnull)certificate

Parameters

certificate

Agora 颁发给开发者的 Certificate。

Return Value

  • 0: 方法调用成功。
  • -1: 方法调用失败并返回错误码、设置 errno。

Discussion

启用了 Agora License 机制后，安装了 Agora SDK 的设备只有通过 Certificate 验证才能加入 Agora 频道、使用数据传输功能。

Note: 该方法仅用于 Agora License 机制。如不使用 license，可忽略该方法。

Declared In

AgoraRtcService.h

+ initWithAppId:uid:events:logDirectory:

初始化 Agora RTSA service。

+ (int)initWithAppId:(NSString *_Nonnull)appId uid:(uint32_t)uid events:(id<AgoraRtcServiceEvents> _Nonnull)events logDirectory:(NSString *_Nullable)logDirectory

Parameters

appId

Agora 为 App 开发者签发的 App ID。了解获取 App ID。
uid

用户 ID，32 位整型，取值范围为 1 到 232 - 1。0 是无效的 uid。如果将 uid 设为 0，系统将自动分配一个 UID。
events

用于处理 Agora SDK 事件的一系列回调。
logDirectory

用于存放 Agora SDK 日志的目录地址。如果 logDirectory 被设为 nil，则日志目录位于：

  • iOS：当前应用程序的 documents 目录
  • macOS：~/Documents/
  • Android：/sdcard/
  • Ubuntu：应用程序的当前工作目录
  • Embedded：应用程序的当前工作目录

Return Value

  • 0: 方法调用成功。
  • -1: 方法调用失败并返回错误码、设置 errno。

Discussion

@note

  • 每条进程只能初始化一次。
  • 该方法使用 int 型的 UID 进行初始化，也可以调用 initWithAppId(uname) 方法使用 String 型用户名进行初始化。
  • SDK 每次初始化时会在指定的目录下自动创建一个新文件夹（随机命名），用于存放此次运行的日志。SDK 不负责回收上一次初始化时创建的文件夹。为了避免日志占用过多空间，建议每次初始化之前先清空日志文件夹。

Declared In

AgoraRtcService.h

+ initWithAppId:uname:events:logDirectory:

使用 String 型用户名初始化 Agora RTSA service。

+ (int)initWithAppId:(NSString *_Nonnull)appId uname:(NSString *_Nonnull)uname events:(id<AgoraRtcServiceEvents> _Nonnull)events logDirectory:(NSString *_Nullable)logDirectory

Parameters

appId

Agora 为 App 开发者签发的 App ID。了解获取 App ID。
uname

用户名，该参数为必填，最大不超过 255 字节，不可设为 nil。请确保用户名的唯一性。以下为支持的字符集范围（共 89 个字符）：

  • 26 个小写英文字母 a-z
  • 26 个大写英文字母 A-Z
  • 10 个数字 0-9
  • 空格
  • “!”, “#”, “$”, “%”, “&”, “(”, “)”, “+”, “-”, “:”, “;”, “<”, “=”, “.”, “>”, “?”, “@”, “[”, “]”, “^”, “_”, “ {”, “}”, “|”, “~”, “,”
events

用于处理 Agora SDK 事件的一系列回调。
logDirectory

用于存放 Agora SDK 日志的目录。如果 sdk_log_dir 设为 nil，则默认日志目录位于：

  • iOS: 当前应用程序的 documents 目录
  • macOS: ~/Documents/
  • Android: /sdcard/
  • Ubuntu: 应用程序的当前工作目录
  • Embedded: 应用程序的当前工作目录

Return Value

  • 0: 方法调用成功。
  • -1: 方法调用失败并返回错误码、设置 errno。

Discussion

初始化成功后，SDK 会触发 rtcServiceDidRegisterLocalUser 回调向本端报告该 uname 对应的 uid。

本端加入频道后，SDK 会通知频道内的所有远端用户本端的 uname 和 uid，并在远端触发 rtcServiceDidRegisterRemoteUser 回调。

@note

  • 每条进程只能初始化一次。
  • 为保证传输质量，请确保同一频道内使用同一类型的数据标识用户身份，即同一频道内需要统一使用 uid 或 uname。
  • SDK 每次初始化时会在指定的目录下自动创建一个新文件夹（随机命名），用于存放此次运行的日志。SDK 不负责回收上一次初始化时创建的文件夹。为了避免日志占用过多空间，建议每次初始化之前先清空日志文件夹。

Declared In

AgoraRtcService.h

+ setLogLevel:

设置 Agora SDK 的日志输出等级。

+ (int)setLogLevel:(int)level

Parameters

level

日志等级，取值范围为 [0, 6]。

Return Value

  • 0: 方法调用成功。
  • -1: 方法调用失败并返回错误码、设置 errno。

Discussion

设置一个级别后，你可以看到该级别及之前所有级别的日志信息。

Declared In

AgoraRtcService.h

+ configLogWithPerFileSize:rollCount:

配置 Agora SDK 的日志文件。

+ (int)configLogWithPerFileSize:(int)perFileSize rollCount:(int)rollCount

Parameters

perFileSize

每份日志文件的大小（字节）。取值范围为 [10000, 1000000]。
rollCount

日志文件数。取值范围为 [1, 100]。

Return Value

  • 0: 方法调用成功。
  • -1: 方法调用失败并返回错误码、设置 errno。

Declared In

AgoraRtcService.h

+ joinChannel:tokenBytes:

加入频道。

+ (int)joinChannel:(NSString *_Nonnull)channelName tokenBytes:(NSData *_Nullable)tokenBytes

Parameters

channelName

频道名，长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）：

  • 26 个小写英文字母 a-z
  • 26 个大写英文字母 A-Z
  • 10 个数字 0-9
  • 空格
  • “!”, “#”, “$”, “%”, “&”, “(”, “)”, “+”, “-”, “:”, “;”, “<”, “=”, “.”, “>”, “?”, “@”, “[”, “]”, “^”, “_”, “ {”, “}”, “|”, “~”, “,”
tokenBytes

用于鉴权的 Token。Agora 提供两种鉴权机制：App ID 和 token。

  • 如果开发者启用 App ID 作为鉴权机制，可以将 token 设为 NULL。
  • 如果开发者启用 Token 作为鉴权机制，Agora 还会给开发者分发一个 App Certificate，并结合 Token 的算法在 App 的服务器端生成 Token。与 App ID 相比，Token 适用于安全要求较高的开发环境。

Return Value

  • 0: 方法调用成功。
  • -1: 方法调用失败并返回错误码、设置 errno。

Discussion

该方法让用户加入指定频道。

Note: 你可以同时加入多个频道，所有你加入的频道都能接收到你发送的音视频数据。

Declared In

AgoraRtcService.h

+ renewTokenOfChannel:tokenBytes:

更新指定频道或全部频道的 Token。

+ (int)renewTokenOfChannel:(NSString *_Nullable)channelName tokenBytes:(NSData *_Nonnull)tokenBytes

Parameters

channelName

频道名。如果为所有加入的频道，则设为 nil。
tokenBytes

用于鉴权的 Token。

Return Value

  • 0: 方法调用成功。
  • -1: 方法调用失败并返回错误码、设置 errno。

Discussion

Note: Token 的使用可以提高生产环境下应用程序的安全性。

Declared In

AgoraRtcService.h

+ muteLocalAudioOfChannel:mute:

暂停／恢复发送本地音频流。

+ (int)muteLocalAudioOfChannel:(NSString *_Nullable)channelName mute:(BOOL)mute

Parameters

channelName

需要进行设置的频道名。如果为所有频道（包括所有未来将加入的频道），则设为 nil。
mute

设置是否暂停／恢复发送本地音频流：

  • YES: 暂停发送。
  • NO: 恢复发送。

Return Value

  • 0: 方法调用成功。
  • -1: 方法调用失败并返回错误码、设置 errno。

Discussion

可以先暂停向所有频道发送音频流，然后恢复向指定频道发送音频流。

Declared In

AgoraRtcService.h

+ muteRemoteAudioOfChannel:uid:mute:

暂停／恢复接收指定频道内指定远端用户的音频流。

+ (int)muteRemoteAudioOfChannel:(NSString *_Nullable)channelName uid:(uint32_t)uid mute:(BOOL)mute

Parameters

channelName

需要进行设置的频道名。如果为所有频道（包括所有未来将加入的频道），则设为 nil。
uid

指定用户的用户 ID。设为 0 则停止接收频道内所有用户的音频流。
mute

设置是否暂停／恢复接收远端音频流：

  • YES: 暂停接收。
  • NO: 恢复接收。

Return Value

  • 0: 方法调用成功。
  • -1: 方法调用失败并返回错误码、设置 errno。

Discussion

默认为接收所有已加入频道内的音频流。

可以先暂停接收所有频道的音频流，然后恢复接收某个指定频道的音频流。

Declared In

AgoraRtcService.h

+ muteLocalVideoOfChannel:mute:

暂停／恢复发送本地视频流。

+ (int)muteLocalVideoOfChannel:(NSString *_Nullable)channelName mute:(BOOL)mute

Parameters

channelName

需要进行设置的频道名。如果为所有频道（包括所有未来加入的频道），则设为 nil。
mute

设置是否暂停／恢复发送本地视频流：

  • YES: 暂停发送。
  • NO: 恢复发送。

Return Value

  • 0: 方法调用成功。
  • -1: 方法调用失败并返回错误码、设置 errno。

Discussion

可以先暂停向所有频道发送视频流，然后恢复向指定频道发送视频流。

Declared In

AgoraRtcService.h

+ muteRemoteVideoOfChannel:uid:mute:

暂停／恢复接收指定频道内指定远端用户的视频流。

+ (int)muteRemoteVideoOfChannel:(NSString *_Nullable)channelName uid:(uint32_t)uid mute:(BOOL)mute

Parameters

channelName

需要进行的频道名。如果为所有频道（包括所有未来加入的频道），则设为 nil。
uid

指定用户的用户 ID。设为 0 则停止接收频道内所有用户的视频流。
mute

设置是否暂停／恢复接收远端视频流：

  • YES: 暂停接收。
  • NO: （默认）恢复接收。

Return Value

  • 0: 方法调用成功。
  • -1: 方法调用失败并返回错误码、设置 errno。

Discussion

默认为接收所有已加入频道内的视频流。

可以先暂停接收所有频道的视频流，然后恢复接收指定频道的视频流。

Declared In

AgoraRtcService.h

+ requestVideoKeyFrameOfChannel:uid:streamId:

请求指定远端用户尽快为指定远端视频流生成关键帧。

+ (int)requestVideoKeyFrameOfChannel:(NSString *_nilable)channelName uid:(uint32_t)uid streamId:(uint8_t)streamId

Parameters

channelName

需要生成关键帧的频道名。如果为所有频道，则设为 nil。
uid

需要生成关键帧的用户 ID。如果为频道内的所有用户，则设为 0。
streamId

需要生成关键帧的视频流 ID。

Return Value

  • 0: 方法调用成功。
  • -1: 方法调用失败并返回错误码、设置 errno。

Declared In

AgoraRtcService.h

+ sendAudioDataToChannel:codec:audioData:

向加入的频道发送音频帧。

+ (int)sendAudioDataToChannel:(NSString *_Nullable)channelName codec:(uint8_t)codec audioData:(NSData *_Nonnull)audioData

Parameters

channelName

发送音频帧的目标频道。设为 nil 则发送音频帧到所有加入的频道。
codec

采用的音频编解码。
audioData

音频包数据。

Return Value

  • 0: 方法调用成功。
  • -1: 方法调用失败并返回错误码、设置 errno。

Discussion

频道内所有用户都能收到你发出的音频帧。

Note: 你加入的所有频道都会收到你发送的音频帧，除非你暂停向指定频道发送音频帧。

Declared In

AgoraRtcService.h

+ sendVideoDataToChannel:codec:streamId:isKeyFrame:videoData:

向加入的频道发送视频帧。

+ (int)sendVideoDataToChannel:(NSString *_Nullable)channelName codec:(uint8_t)codec streamId:(uint8_t)streamId isKeyFrame:(BOOL)isKeyFrame videoData:(NSData *_Nonnull)videoData

Parameters

channelName

发送视频帧的目标频道。设为 nil 则发送视频帧到所有加入的频道。
codec

采用的视频编解码。
streamId

视频流的 ID。必须设为 0。
isKeyFrame

视频帧是否为关键帧:

  • YES: 关键帧
  • NO: 非关键帧
videoData

视频包数据。

Return Value

  • 0: 方法调用成功。
  • -1: 方法调用失败并返回错误码、设置 errno。

Discussion

频道内所有用户都能收到你发出的视频帧。

Note: 你加入的所有频道都会接收到你发送的视频帧，除非你暂停向指定频道发送视频帧。

Declared In

AgoraRtcService.h

+ sendCmdToChannel:cmd:param:

通过可靠数据通道 (RDT) 向加入的频道发送控制命令。

+ (int)sendCmdToChannel:(NSString *_Nullable)channelName cmd:(int32_t)cmd param:(NSData *_Nullable)param

Parameters

channelName

发送控制命令的目标频道。
cmd

控制命令。
param

控制命令的参数。如无，可设为 nil。

Return Value

  • 0: 方法调用成功。
  • -1: 方法调用失败并返回错误码、设置 errno。

Discussion

Note: SDK 触发 rtcServiceDidRdtAvailabilityChangedInChannel 回调 且 is_available 参数为 1 时，RDT 状态为可用。

Declared In

AgoraRtcService.h

+ sendDataThroughRdtToChannel:data:

通过可靠数据通道 (RDT) 向加入的频道发送数据。

+ (int)sendDataThroughRdtToChannel:(NSString *_Nullable)channelName data:(NSData *_Nonnull)data

Parameters

channelName

发送数据的目标频道。
data

数据。

Return Value

  • 0: 方法调用成功。
  • -1: 方法调用失败并返回错误码、设置 errno。

Discussion

Note: SDK 触发 rtcServiceDidRdtAvailabilityChangedInChannel 回调 且 is_available 参数为 1 时，RDT 状态为可用。

Declared In

AgoraRtcService.h

+ leaveChannel:

退出频道。

+ (int)leaveChannel:(NSString *_Nullable)channelName

Parameters

channelName

想要离开的频道的频道名。设为 nil 则离开所有加入的频道。

Return Value

  • 0: 方法调用成功。
  • -1: 方法调用失败并返回错误码、设置 errno。

Discussion

停止在某频道传输数据后需要离开该频道。

Declared In

AgoraRtcService.h

+ finish

释放所有由 initWithAppId 方法分配给 Agora RTSA service 的资源。

+ (int)finish

Return Value

  • 0: 方法调用成功。
  • -1: 方法调用失败并返回错误码、设置 errno。

Declared In

AgoraRtcService.h