You need to enable JavaScript to run this app.
导航
实时音视频
  • 文档首页
    • /实时音视频/实时信令/使用独立 RTS SDK/API 参考/iOS 3.54/API 详情
API 详情
最近更新时间：2024.01.09 19:13:16首次发布时间：2022.09.14 20:26:33
我的收藏
RTS
@interface RTS : NSObject

成员变量

类型名称
iddelegate

静态函数

返回名称
voiddestroyRTS
NSString*getSdkVersion
intsetLogConfig:

成员函数

返回名称
RTS*createRTS:delegate:parameters:
intsetBusinessId:
intsetRuntimeParameters:
RTSRoom*createRoom:
intlogin:uid:
intlogout
intupdateLoginToken:
intsetServerParams:url:
intgetPeerOnlineStatus:
int64_tsendMessage:message:config:
int64_tsendBinaryMessage:message:config:
int64_tsendServerMessage:
int64_tsendServerBinaryMessage:
intsetCellularEnhancement:
intsetLocalProxy:

变量说明

delegate

@property(nonatomic, weak) id<RTSDelegate> _Nullable delegate;

函数说明

destroyRTS

+ (void)destroyRTS;

销毁引擎实例对象。

注意

  • 请确保和需要销毁的 RTS 实例相关的业务场景全部结束后，才调用此方法。
  • 该方法在调用之后，会销毁所有和此 RTS 实例相关的内存，并且停止与媒体服务器的任何交互。
  • 调用本方法会启动 SDK 退出逻辑。引擎线程会保留，直到退出逻辑完成。因此，不要在回调线程中直接调用此 API，也不要在回调中等待主线程的执行，并同时在主线程调用本方法。不然会造成死锁。
  • 可以通过 Objective-C 的ARC机制，在 dealloc 时自动触发销毁逻辑。

getSdkVersion

+ (NSString * _Nonnull)getSdkVersion;

获取 SDK 当前的版本号。

返回值
SDK 当前的版本号。

setLogConfig:

+ (int) setLogConfig:(ByteRTCLogConfig *_Nonnull) logConfig;

配置 SDK 本地日志参数，包括日志级别、存储路径、可使用的最大缓存空间。

传入参数

参数名类型说明
logConfigByteRTCLogConfig*本地日志参数，参看 ByteRTCLogConfig。

返回值

  • 0：成功。
  • –1：失败，本方法必须在创建引擎前调用。
  • –2：失败，参数填写错误。

注意
本方法必须在调用 createRTS:delegate:parameters: 之前调用。

createRTS:delegate:parameters:

+ (RTS * _Nullable)createRTS:(NSString * _Nonnull)appId delegate:(id<RTSDelegate> _Nullable)delegate parameters:(NSDictionary* _Nullable)parameters;

创建引擎对象。
如果当前进程中未创建引擎实例，那么你必须先使用此方法，以使用 RTS 提供的各种消息能力。

如果当前进程中已创建了引擎实例，再次调用此方法时，会创建另一个独立的引擎实例。

传入参数

参数名类型说明
appIdNSString*每个应用的唯一标识符，由控制台随机生成的。不同的 AppId 生成的实例完全独立，无法互通。
delegateidSDK 回调给应用层的 delegate，详见 RTSDelegate
parametersNSDictionary*用以覆盖默认参数的本引擎实例参数。JSON 字符串格式。

返回值
可用的 RTSDelegate 实例。

setBusinessId:

- (int)setBusinessId:(NSString* _Nullable)businessId;

设置业务标识参数

可通过 businessId 区分不同的业务场景。businessId 由客户自定义，相当于一个“标签”，可以分担和细化现在 AppId 的逻辑划分的功能，但不需要鉴权。

传入参数

参数名类型说明
businessIdNSString*用户设置的自己的 businessId 值。businessId 只是一个标签，颗粒度需要用户自定义。

返回值

  • 0： 成功
  • < 0： 失败
  • -2: ByteRTCReturnStatusParameterErr，参数非法。

注意
需要在调用 joinRoom 之前调用，joinRoom之后调用该方法无效。

setRuntimeParameters:

- (int)setRuntimeParameters:(NSDictionary * _Nullable)parameters;

设置运行时的参数

传入参数

参数名类型说明
parametersNSDictionary*保留参数

返回值

createRoom:

- (RTSRoom * _Nullable)createRoom:(NSString * _Nonnull)roomId;

创建房间实例。
调用此方法仅返回一个房间实例，你仍需调用 joinRoom 才能真正地创建/加入房间。
多次调用此方法以创建多个 RTSRoom 实例。分别调用各 RTSRoom 实例中的 joinRoom 方法，同时加入多个房间。
多房间模式下，用户可以同时订阅各房间的音视频流。

传入参数

参数名类型说明
roomIdNSString*标识通话房间的房间 ID。该字符串符合正则表达式：[a-zA-Z0-9_@\-\.]{1,128}。

返回值
创建的 RTSRoom 房间实例。

注意

  • 如果需要加入的房间已存在，你仍需先调用本方法来获取 RTSRoom 实例，再调用 joinRoom 加入房间。
  • 多房间模式下，创建多个房间实例需要使用不同的 roomId，否则会导致创建房间失败。

login:uid:

- (int)login:(NSString * _Nonnull)token uid:(NSString * _Nonnull)uid;

登录 RTS 服务器。

必须先登录，才能收发消息。

在调用本接口登录后，如果想要登出，需要调用 logout

传入参数

参数名类型说明
tokenNSString*用户登录必须携带的 Token，用于鉴权验证。
测试时可使用控制台生成临时 Token，roomId 填任意值。
正式上线需要使用密钥 SDK 在你的服务端生成并下发 Token，roomId 置空，Token 有效期及生成方式参看使用 Token 完成鉴权。
uidNSString*用户 ID， 在 appid 的维度下唯一。

返回值
方法调用结果：

  • 0：成功
  • -1：失败。无效参数
  • -2：无效调用。用户已经登录。成功登录后再次调用本接口将收到此返回值
  • -3：失败。Engine 为空。

注意
本地用户调用此方法登录后，会收到 rtsEngine:onLoginResult:errorCode:elapsed: 回调通知登录结果。

logout

- (int)logout;

登出 RTS 服务器。

调用本接口登出后，无法再调用消息相关的方法或收到相关回调。

返回值

注意
本地用户调用此方法登出后，会收到 rtcEngineOnLogout:rtsEngineOnLogout: 回调通知结果，远端用户不会收到通知。

updateLoginToken:

- (int)updateLoginToken:(NSString * _Nonnull)token;

更新用户用于登录的 Token

Token 有一定的有效期，当 Token 过期时，需调用此方法更新登录的 Token 信息。

调用 login:uid: 方法登录时，如果使用了过期的 Token 将导致登录失败，并会收到 rtsEngine:onLoginResult:errorCode:elapsed: 回调通知，错误码为 ByteRTCLoginErrorCodeInvalidToken。此时需要重新获取 Token，并调用此方法更新 Token。

传入参数

参数名类型说明
tokenNSString*更新的动态密钥

返回值

注意

  • 如果 Token 无效导致登录失败，则调用此方法更新 Token 后，SDK 会自动重新登录，而用户不需要自己调用 login:uid: 方法。
  • Token 过期时，如果已经成功登录，则不会受到影响。Token 过期的错误会在下一次使用过期 Token 登录时，或因本地网络状况不佳导致断网重新登录时通知给用户。

setServerParams:url:

- (int)setServerParams:(NSString * _Nonnull)signature url:(NSString * _Nonnull)url;

设置应用服务器参数

客户端调用 sendServerMessage: 或 sendServerBinaryMessage: 发送消息给应用服务器之前，必须需要设置有效签名和应用服务器地址。

传入参数

参数名类型说明
signatureNSString*动态签名
应用服务器会使用该签名对请求进行鉴权验证。
urlNSString*应用服务器的地址

返回值

注意

getPeerOnlineStatus:

- (int)getPeerOnlineStatus:(NSString * _Nonnull)peerUserId;

查询本地/远端用户的登录状态。

在发送消息之前，用户可以通过本接口了解对端用户是否登录，从而决定是否发送消息。也可以通过本接口查询自己查看自己的登录状态。

传入参数

参数名类型说明
peerUserIdNSString*需要查询的用户 ID

返回值

注意

sendMessage:message:config:

- (int64_t)sendMessage:(NSString * _Nonnull)userId message:(NSString * _Nonnull)messageStr config:(int)config;

给指定的用户发送点对点文本消息（p2p）

传入参数

参数名类型说明
userIdNSString*消息接收用户的 ID
messageStrNSString*发送的文本消息内容，消息不超过 64KB。

返回值
方法调用结果：

  • >0：发送成功，返回这次发送消息的编号，从 1 开始递增
  • -1：发送失败，RTS 引擎实例未创建
  • -2：发送失败，userId 为空

注意

sendBinaryMessage:message:config:

- (int64_t)sendBinaryMessage:(NSString * _Nonnull)userId message:(NSData * _Nonnull)messageStr config:(int)config;

给指定的用户发送点对点二进制消息（P2P）。

传入参数

参数名类型说明
userIdNSString*消息接收用户的 ID
messageStrNSData*发送的二进制消息内容，不超过 46KB。

返回值
方法调用结果：

  • >0：发送成功，返回这次发送消息的编号，从 1 开始递增
  • -1：发送失败，RTS 引擎实例未创建
  • -2：发送失败，userId 为空

注意

sendServerMessage:

- (int64_t)sendServerMessage:(NSString * _Nonnull)messageStr;

客户端给应用服务器发送文本消息（P2Server）。

传入参数

参数名类型说明
messageStrNSString*发送的文本消息内容，不超过 64KB。

返回值
方法调用结果：

  • >0：发送成功，返回这次发送消息的编号，从 1 开始递增
  • -1：发送失败，RTS 引擎实例未创建

注意

sendServerBinaryMessage:

- (int64_t)sendServerBinaryMessage:(NSData *_Nonnull)messageStr;

客户端给应用服务器发送二进制消息（P2Server）。

传入参数

参数名类型说明
messageStrNSData*发送的二进制消息内容，消息不超过 46KB。

返回值
方法调用结果：

  • >0：发送成功，返回这次发送消息的编号，从 1 开始递增
  • -1：发送失败，RTS 引擎实例未创建

注意

setCellularEnhancement:

- (int)setCellularEnhancement:(BOOL)enhance;

启用蜂窝网络辅助增强，改善通话质量。

传入参数

参数名类型说明
enhanceBOOL是否开启。默认不开启。

返回值
方法调用结果：

  • 0: 成功。
  • -1：失败，内部错误。

setLocalProxy:

- (int)setLocalProxy:(NSArray <ByteRTCLocalProxyInfo *> * _Nonnull)configurations;

设置本地代理。

传入参数

参数名类型说明
configurationsNSArray <ByteRTCLocalProxyInfo>**本地代理配置参数。参看 ByteRTCLocalProxyInfo。
你可以根据自己的需要选择同时设置 Http 隧道 和 Socks5 两类代理，或者单独设置其中一类代理。如果你同时设置了 Http 隧道 和 Socks5 两类代理，此时，媒体和信令采用 Socks5 代理， Http 请求采用 Http 隧道代理；如果只设置 Http 隧道 或 Socks5 一类代理，媒体、信令和 Http 请求均采用已设置的代理。
调用此接口设置本地代理后，若想清空当前已有的代理设置，可再次调用此接口，选择不设置任何代理即可清空。

注意

RTSRoom
@interface RTSRoom : NSObject

成员变量

类型名称
iddelegate

成员函数

返回名称
voiddestroy
intsetRTSRoomDelegate:
intjoinRoom
intleaveRoom
int64_tsendRoomMessage:
int64_tsendRoomBinaryMessage:

变量说明

delegate

@property(nonatomic, weak) id<RTSRoomDelegate> _Nullable delegate;

函数说明

destroy

- (void)destroy;

退出并销毁调用 createRoom: 所创建的房间实例。

setRTSRoomDelegate:

- (int)setRTSRoomDelegate:(id<RTSRoomDelegate> _Nullable)roomDelegate;

通过设置 RTSRoomDelegate 代理，可以监听此 RTSRoom 对象对应的回调事件。

传入参数

参数名类型说明
roomDelegateid参见 RTSRoomDelegate。

返回值

joinRoom

- (int)joinRoom;

加入房间。

调用 createRoom: 创建房间后，可调用该方法进房，在房间内收发广播消息。

返回值
方法调用结果：

  • 0: 成功
  • -2: 已经在房间内。接口调用成功后，只要收到返回值为 0 ，且未调用 leaveRoom 成功，则再次调用进房接口时，无论填写的房间 ID 和用户 ID 是否重复，均触发此返回值。
  • -3: room 为空

注意

leaveRoom

- (int)leaveRoom;

离开房间。

用户调用此方法离开房间，结束实时消息通信，释放所有通信相关的资源。

返回值
方法调用结果。

  • 0: 方法调用成功
  • < 0: 方法调用失败

注意

  • 可见的用户离开房间后，房间内其他用户会收到 rtsRoom:onUserLeave:reason: 回调通知；
  • 此方法是异步操作，调用返回时并没有真正退出房间。真正退出房间后，本地会收到 rtsRoomOnLeaveRoom: 回调通知。
  • 如果调用此方法后立即销毁引擎，SDK 将无法触发 rtsRoomOnLeaveRoom: 回调

sendRoomMessage:

- (int64_t)sendRoomMessage:(NSString * _Nonnull)message;

给房间内的所有其他用户发送文本消息。

传入参数

参数名类型说明
messageNSString*发送的文本消息内容。
消息不超过 64KB。

返回值
这次发送消息的编号，从 1 开始递增。

注意

sendRoomBinaryMessage:

- (int64_t)sendRoomBinaryMessage:(NSData * _Nonnull)message;

给房间内的所有其他用户发送二进制消息。

传入参数

参数名类型说明
messageNSData*用户发送的二进制广播消息
消息不超过 46KB。

返回值
这次发送消息的编号，从 1 开始递增。

注意