Entering and Exiting Rooms and Room Information

A brief overview of entering the room

• Join the room using a token： The token field must be included in the roomParams parameter, and the information required by this interface must be consistent with the information used to generate the token. For details on how to generate a token, please refer to the relevant documentation.

• Join the room using an authKey： The token field is not required in the roomParams parameter.

• Regarding the Room ID: Regular Room: You need to create the room in the backend first and obtain the room ID. Then, call the joinRoomWithHost method to enter the room. Instant Room: There is no need to create the room in the backend first. You can directly call the joinRoomEx interface and pass in the room ID to enter the room. Note: When joining the room using a token, the room ID must be consistent with the room ID used when generating the token.

• Regarding the User ID: If a user ID is provided in roomParams, the SDK will use the specified userId. If no user ID is provided, the SDK will automatically generate a userId. Note: When joining the room using a token, the user ID must be consistent with the user ID used when generating the token.

• Regarding the Process of Joining a Room and Callbacks: ·       After calling the joinroom interface, the SDK enters the room joining process： ·       Checkroom: This function is used to check the room. It verifies information such as the room ID and user password. If successful, it can obtain the basic information of the room and the basic information of the users； ·       Configroom: Room configuration. Upon success, it obtains the room link IP address and the document server address； ·       Connectsocket: Connect the socket, based on the link IP address obtained, to establish a connection with the socket； ·       Joinroom: Enter the room. After the socket connection is successful, the process of entering the room begins, and room information is returned (including the number of people in the room, room messages, published stream information, etc.). ·       Callback： ·       Process Callback: During this process, the user will receive the delegate callback of either - (void)roomManagerDidOccuredError:(NSError *)error or - (void)roomManagerDidOccuredWaring:(TKRoomWarningCode)code. Based on the warning code or error code returned in the delegate callback, you can understand whether each process has succeeded or failed. ·       Joinroom Callback: After successfully entering the room, there is a callback of - (void)roomManagerRoomJoined

joinRoom

• Brief description

Join a normal room interface

It is necessary to create the room in the background first. After obtaining the room ID, this interface should be called to enter the room.

• Interface Name

- (int)joinRoom:(TKRoomParams *)param userParams:(TKUserParams *)userParams;

• Parameters

Parameter Name	Required	Type	Description
param	Yes	TKRoomParams	The basic parameters required for the room, a TKRoomParams object. For details of the key values, see the relevant definitions in TKRoomDefines.h
userParams	Yes	NSDictionary	The initialization information of the user when entering the room. This information will be saved to the properties attribute of the TKRoomUser object. It can be customized according to your own needs, such as giftNumber (number of gifts)

• Method Example

    NSString *userid = @"xxxxxx";
    TKRoomParams *roomParams = [[TKRoomParams alloc] init];
    roomParams.roomId = @"roomid";
    roomParams.userPwd = password;
    TKUserParams *userParams = [[TKUserParams alloc] init];
    userParams.userId = userid;
    userParams.roleId = [self.role integerValue];
    userParams.nickName = @"iost";
    [_roomMgr joinRoom:roomParams userParams:userParams];

• Return Value Description

Type	Description
int	0: Indicates that the call was successful. Non-zero: Indicates that the call failed

joinRoomEx

• Brief description

Join the live room

1.There is no need to create a room in the backend. You can directly input the room ID and then enter the room. After calling the interface, the backend will create the room based on the provided room ID. 2.An appKey is required. Before calling this interface, you must first call the initWithAppKey method and pass the appKey into it. 3.Config. Before calling this interface, you must first call the initWithAppKey method and pass the config into it.

• Interface Name

- (int)joinRoomEx:(TKRoomParams *)param userParams:(TKUserParams *)userParams;

• Parameters

Parameter Name	Required	Type	Description
roomParams	No	NSDictionary	The room custom parameters are of type NSDictionary. For details on the key values, refer to the relevant definitions in TKRoomDefines.h.
userParams	No	NSDictionary	The initialization information of the custom user will be saved to the properties property of the TKRoomUser object, and it can be customized according to your own needs.

• Method Example

    NSString *userid = @"xxabcdef123";
    TKUserParams *userParams = [[TKUserParams alloc] init];
    userParams.userId = userid;
    userParams.roleId = [self.role integerValue];
    userParams.nickName = @"iost";
    TKRoomExParams *roomExParams = [[TKRoomExParams alloc] init];
    roomExParams.roomId = @"1234589";
    NSTimeInterval ts = [[NSDate date] timeIntervalSince1970] * 1000;
    NSString *val = [[NSString alloc] initWithFormat:@"appId=%@&thirdRoomId=%@&userId=%@&ts=%.0f&expireTs=%d", kAppId, roomExParams.roomId, userid, ts, 7 * 3600];
    NSString *token = [GenerateUserSig AES128_CBCEncryptWithKey:kAuthkey iv:kAuthkey encrypt:val];
    roomExParams.token = token;
    roomExParams.roomType = 1;
    [_roomMgr joinRoomEx:roomExParams userParams:userParams];

• Return Value Description

Type	Description
int	0: Indicates that the call was successful. Non-zero: Indicates that the call failed

leaveRoom

• Brief description

Leave the classroom

After calling the interface, both I and the other users in the room will receive the corresponding callbacks. 1.  I will receive the callback for myself leaving the room: - (void)roomManagerRoomLeft. 2.  The other users in the room will receive the callback for my leaving the room: - (void)roomManagerUserLeft:(NSString *)peerID.

• Interface Name

- (int)leaveRoom:(BOOL)sync Completion:(completion_block _Nullable)completion; Synchronize and exit - (int)leaveRoom:(completion_block _Nullable)completion;

• Parameters

Parameter Name	Required	Type	Description
sync	Yes	BOOL	Whether it is executed synchronously
completion	No	completion_block	The callback of the API call will return an error message if there is an error

• Method Example

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

• Return Value Description

Type	Description
int	0: Indicates that the call was successful. Non-zero: Indicates that the call failed

getRoomProperty

• Brief description

Get room properties

This function should be called after the joinRoom interface is invoked to obtain valid results. It returns all information related to the room, such as the room ID, room type, and configuration items. Configuration items refer to whether the room has enabled teaching auxiliary functions, such as automatic class dismissal, quiz tools, and other interactive teaching features.

• Interface Name

- (NSDictionary *)getRoomProperty;

• Method Example

NSDictionary *roomProperty = [_roomMgr getRoomProperty];

• Return Value Description

Type	Description
NSDictionary	Dictionary of room-related information

getRoomUserWithUId

• Brief description

Get user by user ID

TKRoomUser is a user object class that stores user-related information. It can only return valid results when called after the joinRoom interface is invoked.

• Interface Name

- (TKRoomUser * _Nullable)getRoomUserWithUId:(NSString *)peerId;

• Parameters

Parameter Name	Required	Type	Description
peerId	Yes	NSString	User ID

• Method Example

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

• Return Value Description

Type	Description
TKRoomUser	If there is a user with the specified user ID in the room, it returns the TKRoomUser user object; otherwise, it returns nil

getServerList

• Brief description

Get the server list

These servers can be used for switching connections. Valid results can only be obtained by calling this after the joinRoom interface has been invoked.

• Interface Name

- (NSArray * _Nullable)getServerList;

• Method Example

NSArray *serverList = [_roomMgr getServerList];

• Return Value Description

Type	Description
NSArray	If there are available servers, it returns an NSArray object; otherwise, it returns nil.

getStreamStats

• Brief description

Get the upstream audio and video statistics data of the user

Obtain the upstream audio and video network statistics data for a specific user, including statistics on packet loss, latency, bandwidth, etc. Valid results can only be obtained by calling this after the joinRoom interface has been invoked.

• Interface Name

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

• Parameters

Parameter Name	Required	Type	Description
peerId	Yes	NSString	User ID
allStreams	Yes	BOOL	Whether to obtain the statistics of all streams in the room. If NO, it means: Obtain the statistics of all audio and video streams published by the user with the peerId. If YES, it means: Obtain the statistics of all audio and video streams in the room, in which case the peerId parameter will not take effect.
callback	Yes	void (^)(NSDictionary * stats, NSError * _Nullable error)	Callback, returning the obtained results. stats represents the retrieved statistics, and error represents any error that occurred

• Method Example

       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);
        }
    }];

• Return Value Description

Type	Description
int	0: Indicates that the call was successful. Non-zero: Indicates that the call failed

Notes

For more return error codes, please refer to the error code descriptions in TKRoomErrorCode