进出房间和房间信息

• 关于进房间的简要概述
• joinRoomWithHost
• joinRoomEx
• leaveRoom
• getRoomProperty
• getRoomUserWithUId
• getServerList
• getStreamStats
• 备注

最近更新时间：2022-01-25 14:46:23 星期二

关于进房间的简要概述

• 使用token方式加入房间：

  必须在参数 roomParams 中加入 TKJoinRoomParamsToken，TKJoinRoomParamsPrivilegeExpiredTs 字段, 并且该接口需要的信息必须与生成 token 时使用的信息一致。 关于如何生成Token请查看相关文档。

• 使用authKey方式加入房间：

  参数 roomParams 中 无需添加 TKJoinRoomParamsToken，TKJoinRoomParamsPrivilegeExpiredTs 字段。

• 关于房间ID：

  普通房间：需要优先在后台 创建房间，获取到房间ID后，调用 joinRoomWithHost 进房间。 即时房间：无需优先在后台创建房间，可直接调用 joinRoomEx 接口，传入房间ID，即可进入房间。 注意：token 方式进房间时，房间ID必须与生成的 token 时使用的房间ID信息一致。

• 关于用户ID问题：

  roomParams 若传入了用户ID，SDK会使用传入的userId，若不传入用户ID， SDK会自动生成一个userId。 注意：token 方式进房间时，用户ID必须与生成的 token 时使用的用户ID信息一致。

• 关于进房间的流程及回调：

  • 调用joinroom接口后，sdk就进入了 进房间流程 :
  • checkroom：检测房间， 检查 房间ID、用户密码 等信息。成功后可以获取该房间基础信息和用户基础信息；
  • configroom：房间配置， 成功后获取房间链路IP地址和文档服务器地址；
  • connectsocket：链接socket， 根据获取到的链路IP地址去链接socket；
  • joinroom：进房间， socket成功后，开始进入房间，并返回房间信息（包括房间人数、房间消息、已发布的流信息等）。
  • 回调 :
  • 流程回调：此过程中用户会收到 - (void)roomManagerDidOccuredError:(NSError *)error 或者 - (void)roomManagerDidOccuredWaring:(TKRoomWarningCode)code 的代理回调。根据在代理回调中返回的警告码或者错误码，可以了解到各个流程是成功或者失败。
  • joinroom回调：成功进入房间后，有 - (void)roomManagerRoomJoined 回调

joinRoomWithHost

简要描述
- 加入普通房间接口

需要优先在后台 创建房间，获取到房间ID后，调用此接口进入房间。

接口名称

    - (int)joinRoomWithHost:(NSString *)host
                                   port:(int)port
                           nickName:(NSString *)nickname
                     roomParams:(NSDictionary *)roomParams
                      userParams:(NSDictionary * _Nullable)userParams 

参数

参数名	必填	类型	说明
host	是	NSString	服务器地址 默认是https
port	是	int	服务器端口 若在初始化“- (int)initWithAppKey:optional:”接口中设置 TKRoomSettingOptionalSecureSocket 为 YES，表示使用 https 或者 wss，所以此端口需要设置为：443(默认)；若初始化接口中设置 TKRoomSettingOptionalSecureSocket 为 NO 或者 不设置，端口为：80(默认).
nickname	是	NSString	昵称
roomParams	是	NSDictionary	房间所需的基本参数，NSDictionary类型，key值详情见 TKRoomDefines.h 相关定义
userParams	是	NSDictionary	进入房间时用户的初始化的信息, 该信息会保存到 TKRoomUser 对象的 properties 属性中。可根据自身需求自定义，比如 giftNumber（礼物数）

方法示例
authKey方式：

    [_roomMgr joinRoomWithHost:@"global.talk-cloud.net"
                                        port:@"443"
                                nickName:@"iOS"
                              roomParams:@{
                                            TKJoinRoomParamsRoomIDKey : @"1473793911",  //房间ID
                                          TKJoinRoomParamsUserRoleKey : @"0",                   //用户角色
                                         TKJoinRoomParamsPasswordKey : @"1",                    //密码
                                             TKJoinRoomParamsUserIDKey : @"ade123456",    //用户ID
                                                                    @"clientType" : @(3)                     // 3表示是iOS平台设备
                                                }
                              userParams:nil];

token方式：

    NSString *token = @"a297caebdc8f2b56f2c5f93c6bcba908";
    NSString *privilegeExpiredTs = @"0";
    [_roomMgr joinRoomWithHost:@"global.talk-cloud.net"
                                        port:@"443"
                                nickName:@"iOS"
                              roomParams:@{
                                            TKJoinRoomParamsRoomIDKey : @"1473793911",  //房间ID
                                          TKJoinRoomParamsUserRoleKey : @"0",                   //用户角色
                                         TKJoinRoomParamsPasswordKey : @"1",                    //密码
                                             TKJoinRoomParamsUserIDKey : @"ade123456",    //用户ID
                                                  TKJoinRoomParamsToken : token,
                                 TKJoinRoomParamsPrivilegeExpiredTs : privilegeExpiredTs,
                                                                      @"clientType": @(3)                    // 3表示是iOS平台设备
                                                }
                              userParams:nil];

返回值说明

类型	说明
int	0:表示调用成功，非0:表示调用失败

joinRoomEx

简要描述
- 加入即时房间

1. 无需在后台 创建房间，可以直接传入房间ID，然后进入房间。调用接口后，后台会以传入的房间ID创建房间。
2. 必须有appKey。调用此接口前，需先调用 initWithAppKey ，并且在 initWithAppKey 中传入 appKey 。
3. roomType。调用此接口前，需先调用 initWithAppKey ，并且在 initWithAppKey 中传入 roomType。roomType默认是 TKRoomType_More(一对多房间)。

接口名称

- (int)joinRoomEx:(NSString *)roomId
            nickName:(NSString * _Nullable)nickname
             third_uid:(NSString * _Nullable)third_uid
        roomParams:(NSDictionary * _Nullable)roomParams
          userParams:(NSDictionary * _Nullable)userParams

- (int)joinRoomEx:(NSString *)roomId
            nickName:(NSString * _Nullable)nickname
             third_uid:(NSString * _Nullable)third_uid
          userParams:(NSDictionary * _Nullable)userParams

参数

参数名	必填	类型	说明
roomId	是	NSString	房间ID
nickname	是	NSString	昵称
third_uid	是	NSString	用户ID
roomParams	否	NSDictionary	房间自定义参数，NSDictionary类型，key值详情见 TKRoomDefines.h 相关定义
userParams	否	NSDictionary	自定义用户的初始化的信息，该信息会保存到 TKRoomUser 对象的 properties 属性中，可根据自身需求自定义。

方法示例
authKey方式：

    NSString *userid = @"1131223463fff";
    NSString *roomId = @"1473793911";
    [_roomMgr joinRoomEx:roomId
                        nickName:@"iOS"
                       third_uid:userid
                  roomParams:nil
                    userParams:nil];

token方式：

    NSString *userid = @"1131223463fff";
    NSString *roomId = @"1473793911";
    NSString *token = @"a297caebdc8f2b56f2c5f93c6bcba908";
    NSString *privilegeExpiredTs = @"0";
    [_roomMgr joinRoomEx:roomId
                        nickName:@"iOS"
                       third_uid:userid
                  roomParams:@{ TKJoinRoomParamsToken : token,
                             TKJoinRoomParamsPrivilegeExpiredTs : privilegeExpiredTs,
                                          TKJoinRoomParamsUserIDKey : userid
              }
              userParams:nil];

返回值说明

类型	说明
int	0:表示调用成功，非0:表示调用失败

leaveRoom

简要描述
- 退出教室

调用接口后，我和房间其他用户会收到相应的 回调。 1、我会接收到自己离开房间的回调：[- (void)roomManagerRoomLeft][11]。 2、在房间其他用户收到我离开房间的回调：- (void)roomManagerUserLeft:(NSString *)peerID。

接口名称
- - (int)leaveRoom:(BOOL)sync Completion:(completion_block _Nullable)completion; 同步退出 - (int)leaveRoom:(completion_block _Nullable)completion;

参数

参数名	必填	类型	说明
sync	是	BOOL	是否同步执行
completion	否	completion_block	调用接口的回调，若出错，会返回错误信息

方法示例

    int ret = [_roomMgr leaveRoom:NO Completion:^(NSError *error) {
            if (error) {
                NSLog(@"leave room error:%@", error);
            }
     }];
OR：
    int ret = [_roomMgr leaveRoom:nil];

返回值说明

类型	说明
int	0:表示调用成功，非0:表示调用失败

getRoomProperty

简要描述
- 获取房间属性

需在调用 joinroom 接口后调用才能获取有效结果。 返回房间相关的所有信息，例如房间ID、房间类型、配置项等。 配置项：表示该房间是否开启了教学辅助功能，例如自动下课、答题器等等教学互动功能。

接口名称
- - (NSDictionary *)getRoomProperty;

方法示例

    NSDictionary *roomProperty = [_roomMgr getRoomProperty];

返回值说明

类型	说明
NSDictionary	房间相关信息的字典

getRoomUserWithUId

简要描述
- 根据用户ID获取用户

TKRoomUser 是用户对象类，存储了用户的相关信息。 需在调用 joinroom 接口后调用才能获取有效结果。

接口名称
- - (TKRoomUser * _Nullable)getRoomUserWithUId:(NSString *)peerId;

参数

参数名	必填	类型	说明
peerId	是	NSString	用户ID

方法示例

    TKRoomUser *roomUser = [_roomMgr getRoomUserWithUId:@"ade123456"];

返回值说明

类型	说明
TKRoomUser	如果房间中有这个用户ID的用户，则返回 TKRoomUser的用户对象，否则返回 nil

getServerList

简要描述
- 获取服务器列表

可用于切换链接的服务器。 需在调用 joinroom 接口后调用才能获取有效结果。

接口名称
- - (NSArray * _Nullable)getServerList;

方法示例

    NSArray *serverList = [_roomMgr getServerList];

返回值说明

类型	说明
NSArray	若存在可用的服务器，则返回 NSArray 数组对象，否则返回 nil。

getStreamStats

简要描述
- 获取用户的上行音视频统计信息数据

获取某一用户的上行音视频网络统计数据，包括丢包、延迟、带宽等统计信息。 需在调用 joinroom 接口后调用才能获取有效结果。

接口名称
- - (int)getStreamStats:(NSString *)peerId allStreams:(BOOL)allStreams callback:(void (^)(NSDictionary <NSString *, NSDictionary *>* stats, NSError * _Nullable error))callback;

参数

参数名	必填	类型	说明
peerId	是	NSString	用户ID
allStreams	是	BOOL	是否获取房间中所有流的统计信息。若NO，表示：获取peerId的用户发布的所有音视频流的统计信息。若YES，则表示：获取房间中所有音视频流的统计信息，此时 peerId 参数将不生效。
callback	是	void (^)(NSDictionary * stats, NSError * _Nullable error)	回调，返回获取的结果。stats：表示获取的统计信息，error：表示出现错误

方法示例

    int ret = [_roomMgr getStreamStats:@"ade123456" allStreams:NO callback:^(NSDictionary<NSString *,NSDictionary *> * _Nonnull stats, NSError * _Nullable error) {
        if (!error) {
            NSLog(@"stream stats = %@", stats);
        } else {
            NSLog(@"error = %@", error);
        }
    }];

返回值说明

类型	说明
int	0:表示调用成功，非0:表示调用失败

备注

• 更多返回错误代码请看 TKRoomErrorCode 错误代码描述