Check the room connection status

Before a user uses ZEGOCLOUD Express SDK to make audio and video calls or perform live streaming, the user must join a room to receive callback notifications about events such as adding or removing streams by other users in the same room, and user login and logout events. Therefore, a connection state of a user in the room determines whether the user can normally use the audio and video services.

This topic describes how to determine a connection state of a user in a room. Further, this topic describes the transition process of connection states.

Listen for room connection states

A user can monitor the connection state of the user in the current room in real time by listening for the onRoomStateChanged callback. If the connection state of the user changes, the SDK triggers the callback, and the current connection state and related error code are returned in the callback.

The SDK will retry internally if the connection to the room is interrupted due to poor network quality.

Room connection states

The room connection states flow. The developer can determine a state based on the returned reason and handle corresponding logic based on the return value of the errorCode parameter.

You can refer to the following code to handle common business events:

-(void)onRoomStateChanged:(ZegoRoomStateChangedReason)reason errorCode:(int)errorCode extendedData:(NSDictionary *)extendedData roomID:(NSString *)roomID {
    if(reason == ZegoRoomStateChangedReasonLogining)
    {
        // logging in
        // When loginRoom is called to log in to the room or switchRoom is used to switch to the target room, it enters this state, indicating that it is requesting to connect to the server.
    }
    else if(reason == ZegoRoomStateChangedReasonLogined)
    {
        // login successful
        //  Currently, the loginRoom is successfully called by the developer or the callback triggered by the successful switchRoom. Here, you can handle the business logic for the first successful login to the room, such as fetching chat room and live streaming basic information.
    }
    else if(reason == ZegoRoomStateChangedReasonLoginFailed)
    {
        // login failed
        if (errorCode == 1002033) {
            //When using the login room authentication function, the incoming Token is incorrect or expired.
        }
    }
    else if(reason == ZegoRoomStateChangedReasonReconnecting)
    {
        // Reconnecting
        // This is currently a callback triggered by successful disconnection and reconnection of the SDK. It is recommended to show some reconnection UI here.
    }
    else if(reason == ZegoRoomStateChangedReasonReconnected)
    {
        // Reconnection successful
    }
    else if(reason == ZegoRoomStateChangedReasonReconnectFailed)
    {
        // Reconnect failed
        // When the room connection is completely disconnected, the SDK will not reconnect. If developers need to log in to the room again, they can actively call the loginRoom interface.
        // At this time, you can exit the room/live broadcast room/classroom in the business, or manually call the interface to log in again.
    }
    else if(reason == ZegoRoomStateChangedReasonKickOut)
    {
        // kicked out of the room
        if (errorCode == 1002050) {
            // The user was kicked out of the room (because the user with the same userID logged in elsewhere).
        }
        else if (errorCode == 1002055) {
            // The user is kicked out of the room (the developer actively calls the background kicking interface).
        }
    }
    else if(reason == ZegoRoomStateChangedReasonLogout)
    {
        // Logout successful
        // The developer actively calls logoutRoom to successfully log out of the room.
        // Or call switchRoom to switch rooms. Log out of the current room successfully within the SDK.
        // Developers can handle the logic of actively logging out of the room callback here.
    }
    else if(reason == ZegoRoomStateChangedReasonLogoutFailed)
    {
        // Logout failed
        // The developer actively calls logoutRoom and fails to log out of the room.
        // Or call switchRoom to switch rooms. Logout of the current room fails internally in the SDK.
        // The reason for the error may be that the logout room ID is wrong or does not exist.
    }
}

Reconnect to a room after disconnection

After you log in to a room, you may be disconnected from the room due to a network signal issue or network-type switching issue. In this case, the SDK automatically initiates a reconnection. The following figure shows changes in the room connection state of a user A when the user A and a user B both have logged into the same room.

After a room disconnection occurs, the following three reconnection scenarios may be involved:

Scenario 1: Reconnection succeeds before the server determines that the heartbeat of the user A times out

• T0 = 0 s. The SDK of the user A receives a loginRoom request sent by the client.
• T1 is about 120 ms later than T0. Usually, the client can join a room about 120 ms later after the loginRoom operation is called. In the process of logging in to the room, the client of the user A may receive the onRoomStateChanged callback notifications twice. The notifications are used to notify the client that the connection to the room is being established (the `logining` state) and that the connection to the room has been established (the `logined` state).
• T2 is about 100 ms later than T1. Due to a network transmission delay, the user B receives the onRoomUserUpdate callback notification about 100 ms later than T1. The notification is used to notify the client that the user A joins the room.
• T3 specifies a point in time at which the uplink network status of the user A deteriorates due to network disconnection. Then, the SDK attempts to join the room again. At the same time, the client may receive a onRoomStateChanged callback notification used to notify the client that the user A is reconnecting to the room after disconnection.
• T5 specifies a point in time (less than 90 s) later than T3. At T5, the user A restores network connection and is reconnected to the room. The user A receives the onRoomStateChanged callback notification used to notify the client that the user A is reconnected to the room.

Scenario 2: Reconnection succeeds after the server determines that the heartbeat of the user A times out

• The definitions of T0, T1, T2, and T3 in this scenario are the same as those in the scenario 1.

• T4' is about 90 s later than T3. At T4', the user B receives the onRoomUserUpdate callback notification used to notify that the user A is disconnected.

• T5' specifies a point in time (greater than 90 s but less than 20 min) later than T3. At T5', the user A restores network connection and is reconnected to the room. The user A receives the onRoomStateChanged callback notification used to notify the client that the user A is reconnected to the room.

• T6' is about 100 ms later than T5'. Due to a network transmission delay, the user B receives the onRoomUserUpdate callback notification about 100 ms later than T5'. The notification is used to notify the client that the user A joins the room.

Scenario 3: The user A fails to reconnect to the room

• The definitions of T0, T1, T2, and T3 in this scenario are the same as those in the scenario 1.

• T4'' is about 90 s later than T3. At T4'', the user B receives the onRoomUserUpdate callback notification used to notify that the user A is disconnected.

• T5'' is 20 minutes later than T3. If the user A fails to join the room within 20 minutes after T3, the SDK does not attempt to reconnect to the room. The user A receives the onRoomStateChanged callback notification used to notify the client that the reconnection fails.

Related documents

Does Express SDK support the disconnection and reconnection mechanism?