API 详情

@interface RTS : NSObject

成员变量

静态函数

成员函数

变量说明

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 本地日志参数，包括日志级别、存储路径、可使用的最大缓存空间。

传入参数

返回值

• 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 提供的各种消息能力。

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

传入参数

返回值
可用的 RTSDelegate 实例。

setBusinessId:

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

设置业务标识参数

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

传入参数

返回值

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

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

setRuntimeParameters:

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

设置运行时的参数

传入参数

返回值

• 0: 调用成功。
• < 0 : 调用失败。查看 ByteRTCReturnStatus 获得更多错误说明

createRoom:

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

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

传入参数

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

注意

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

login:uid:

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

登录 RTS 服务器。

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

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

传入参数

返回值
方法调用结果：

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

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

logout

- (int)logout;

登出 RTS 服务器。

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

返回值

• 0: 调用成功。
• < 0 : 调用失败。查看 ByteRTCReturnStatus 获得更多错误说明

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

updateLoginToken:

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

更新用户用于登录的 Token

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

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

传入参数

返回值

• 0: 调用成功。
• < 0 : 调用失败。查看 ByteRTCReturnStatus 获得更多错误说明

注意

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

setServerParams:url:

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

设置应用服务器参数

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

传入参数

返回值

• 0: 调用成功。
• < 0 : 调用失败。查看 ByteRTCReturnStatus 获得更多错误说明

注意

• 用户必须调用 login:uid: 登录后，才能调用本接口。
• 调用本接口后，SDK 会使用 rtsEngine:onServerParamsSetResult: 返回相应结果。

getPeerOnlineStatus:

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

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

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

传入参数

返回值

• 0: 调用成功。
• < 0 : 调用失败。查看 ByteRTCReturnStatus 获得更多错误说明

注意

• 必须调用 login:uid: 登录后，才能调用本接口。
• 调用本接口后，SDK 会使用 rtsEngine:onGetPeerOnlineStatus:status: 回调通知查询结果。

sendMessage:message:config:

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

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

传入参数

返回值
方法调用结果：

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

注意

• 在发送点对点文本消息前，必须先调用 login:uid: 完成登录。
• 用户调用本接口发送文本信息后，会收到一次 rtsEngine:onMessageSendResult:error: 回调，得知消息是否成功发送。
• 若文本消息发送成功，则 userId 所指定的用户会通过 rtsEngine:onMessageReceived:message: 回调收到该消息。

sendBinaryMessage:message:config:

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

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

传入参数

返回值
方法调用结果：

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

注意

• 在发送点对点二进制消息前，必须先调用 login:uid: 完成登录。
• 用户调用本接口发送二进制消息后，会收到一次 rtsEngine:onMessageSendResult:error: 回调，通知消息是否发送成功。
• 若二进制消息发送成功，则 userId 所指定的用户会通过 rtsEngine:onBinaryMessageReceived:message: 回调收到该条消息。

sendServerMessage:

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

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

传入参数

返回值
方法调用结果：

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

注意

• 在向应用服务器发送文本消息前，必须先调用 login:uid: 完成登录，随后调用 setServerParams:url: 设置应用服务器。
• 调用本接口后，会收到一次 rtsEngine:onServerMessageSendResult:error:message: 回调，通知消息发送方是否发送成功。
• 若文本消息发送成功，则之前调用 setServerParams:url: 设置的应用服务器会收到该条消息。

sendServerBinaryMessage:

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

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

传入参数

返回值
方法调用结果：

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

注意

• 在向应用服务器发送二进制消息前，先调用 login:uid: 完成登录，随后调用 setServerParams:url: 设置应用服务器。
• 调用本接口后，会收到一次 rtsEngine:onServerMessageSendResult:error:message: 回调，通知消息发送方发送成功或失败；
• 若二进制消息发送成功，则之前调用 setServerParams:url: 设置的应用服务器会收到该条消息。

setCellularEnhancement:

- (int)setCellularEnhancement:(BOOL)enhance;

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

传入参数

返回值
方法调用结果：

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

setLocalProxy:

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

设置本地代理。

传入参数

注意

• 该方法需要在进房前调用。
• 调用该方法设置本地代理后，SDK 会触发 rtsEngine:onLocalProxyStateChanged:withProxyState:withProxyError: ，返回代理连接的状态。

@interface RTSRoom : NSObject

成员变量

成员函数

变量说明

delegate

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

函数说明

destroy

- (void)destroy;

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

setRTSRoomDelegate:

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