You need to enable JavaScript to run this app.
导航
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 开始递增。

注意