Sessions

A session is the most fundamental building block of the Video SDK for Linux. A session is similar to, but not limited to, a virtual meeting where two or more users can communicate with each other over video and audio. Optional features include in-session chat, screen share, and live streaming.

Create and join session#

To create or join a session, you must provide a session name and the developer's SDK JWT. Prior to joining, be sure that you have set up a delegate for callback events.

Session name#

The session name determines whether the SDK joins an existing session or creates a new one:

• If you call joinSession() with a session name and there is no session currently active with that name, the SDK creates the session for you.
• If a session with that name is currently active, the SDK lets you join the active session if you provide all the required parameters, for example, a password if one has been set for the session.

The session name only needs to be unique to your app at the developer account level. For instance, developers with separate developer accounts (separate SDK credentials) can use the same session name for their separate apps (for example, App A and App B). While the names are the same, Zoom creates different unique sessions for both of these apps. Two different apps built with the Video SDK cannot join sessions created by the other. Each app can only join a session that it created.

Create a ZoomVideoSDKSessionContext object#

To create a session through the SDK, create an instance of ZoomVideoSDKSessionContext and provide the userName, sessionName, and SDK JWT:

ZoomVideoSDKSessionContext session_context;
session_context.sessionName = "session_name"
session_context.sessionPassword = "session password"
session_context.userName = "user name";
session_context.token = "JWT";
session_context.videoOption.localVideoOn = true;
session_context.audioOption.connect = true;
session_context.audioOption.mute = true;

The following table describes all the properties of the ZoomVideoSDKSessionContext object.

Prior to joining a session, ensure that you have set up a delegate for callback events by conforming your class to the IZoomVideoSDKDelegate interface.

Once you have your context and delegate set up, call joinSession() to join a session.

IZoomVideoSDKSession* session = NULL;
if (video_sdk_obj) {
    session = video_sdk_obj->joinSession(session_context);
}

Note that the return value of the joinSession() method will return the session upon success, and NULL upon failure.

Optimize join latency with pre-join#

To reduce connection time in 1:1 calls or invite flows, prepare the session before the user accepts the call. When the user accepts, commit the join to connect immediately. This two-step flow minimizes the time between when a user answers a call and when they're in the call.

Before the user can use prepareJoin() and commitJoin(), the caller must already have the session up and running. The user then uses the pre-join flow to join the existing session more quickly.

Implement the surrounding incoming-call workflow, including push notification delivery and application-level call UI.

Prepare to join#

First create your session context as described in Create a ZoomVideoSDKSessionContext object. Then call prepareJoin() to prepare the connection without joining the session. Configure the timeout interval using ZoomVideoSDKPreJoinParam.

ZoomVideoSDKPreJoinParam preJoinParam;
preJoinParam.timeoutInterval = 30; // Timeout in seconds (1-60, or 0 for default 30s)

IZoomVideoSDKSession* session = NULL;
if (video_sdk_obj) {
    session = video_sdk_obj->prepareJoin(session_context, preJoinParam);
}

Commit the join#

When the user accepts the call, finalize the connection by calling commitJoin().

ZoomVideoSDKErrors result = video_sdk_obj->commitJoin();

The return value indicates success or error. Listen for onSessionJoin() to confirm you've successfully joined.

Cancel pre-join#

If the user declines the call after prepareJoin(), cancel the preparation.

ZoomVideoSDKErrors result = video_sdk_obj->cancelPrepareJoin();

Hold participants until admitted#

OnHold places participants in a holding state when they join a session. They stay on hold, outside the session, until a host or manager admits them.

The hold JWT payload field controls whether a session supports OnHold. Set it in the JWT of the first user to join, which starts the session.

• 0 - (default) The session does not support OnHold.
• 1 - The session supports OnHold, and OnHold is on when the session starts.
• 2 - The session supports OnHold, but OnHold is off when the session starts. A host or manager can turn it on during the session.

When OnHold is on, participants who join receive onHoldJoined() instead of onSessionJoin() until a host or manager admits them.

Check OnHold status#

Get the IZoomVideoSDKOnHoldHelper by calling getOnHoldHelper(). Call isSupportHold() to check whether the current session supports OnHold, and isOnHoldEnabled() to check whether OnHold is on.

IZoomVideoSDKOnHoldHelper* pOnHoldHelper = video_sdk_obj->getOnHoldHelper();
if (pOnHoldHelper) {
    bool isSupportHold = pOnHoldHelper->isSupportHold();
    bool isOnHoldEnabled = pOnHoldHelper->isOnHoldEnabled();
}

Get notified when you are on hold#

When the local user joins a session with OnHold on, the SDK calls onHoldJoined() instead of onSessionJoin(). Use this callback to show a holding state until a host or manager admits the user.

virtual void onHoldJoined()
{
    // The local user is on hold.
}

Get notified when other users are on hold#

The SDK calls onHoldUserJoin() when users are placed on hold, and onHoldUserLeave() when users leave the on-hold list. Use these callbacks to keep a list of users waiting for a host or manager to admit them.

Users leave the on-hold list in either of the following cases.

• A host or manager admits them. Hosts and managers then also receive onUserJoin() for each admitted user who is not already in the session's user list.
• They leave while still on hold. The SDK reports these users through onHoldUserLeave() only, not through onUserLeave().

virtual void onHoldUserJoin(IZoomVideoSDKOnHoldHelper* pOnHoldHelper, IVideoSDKVector<IZoomVideoSDKOnHoldUser*>* userList)
{
    if (!userList) return;
    for (int i = 0; i < userList->GetCount(); i++) {
        IZoomVideoSDKOnHoldUser* pUser = userList->GetItem(i);
        printf("User on hold: name=%s\n", pUser->getUserName());
    }
}

virtual void onHoldUserLeave(IZoomVideoSDKOnHoldHelper* pOnHoldHelper, IVideoSDKVector<IZoomVideoSDKOnHoldUser*>* userList)
{
    // Remove these users from your list of users on hold.
}

Admit users on hold#

A host or manager can call getOnHoldUserList() to get the users currently on hold, then call admit() to admit one user or admitAll() to admit every user on hold.

IZoomVideoSDKOnHoldHelper* pOnHoldHelper = video_sdk_obj->getOnHoldHelper();
IVideoSDKVector<IZoomVideoSDKOnHoldUser*>* pOnHoldUsers = pOnHoldHelper->getOnHoldUserList();

// Admit one user.
if (pOnHoldUsers && pOnHoldUsers->GetCount() > 0) {
    ZoomVideoSDKErrors result = pOnHoldHelper->admit(pOnHoldUsers->GetItem(0));
}

// Admit all users on hold.
ZoomVideoSDKErrors result = pOnHoldHelper->admitAll();

Turn OnHold on or off during a session#

A host or manager can call enableHold() to turn OnHold on or off in a session that supports OnHold. This change only affects future join attempts. It does not admit users who are already on hold.

// Pass true to turn OnHold on, or false to turn it off.
ZoomVideoSDKErrors result = video_sdk_obj->getOnHoldHelper()->enableHold(true);

Leave session#

When you are ready to leave the session, call leaveSession().

Leave session has a bool parameter that when set to true will end the session. Only the host can end the session.

if (video_sdk_obj)
    session = video_sdk_obj->leaveSession(session_context);

Sessions become inactive and available for reuse after you call leaveSession() to end a session or the backend closes the session when there are no longer any users in that session.

User roles and actions#

People in a session can hold one of the following roles: host, manager, or participant.

Host#

The user with the host role_type is the host of the session.

A host of the session has the following privileges.

• View information of users in the session.
• Change the display name of a user in the session.
• Mute or unmute a user's audio.
• Transfer the host role to someone else in the session.
• Promote another user to be a manager of the session.
• Remove participants from the session.
• Revoke manager privilege from a user.
• Start a live stream.
• Prevent other users from sharing their screen (lock screen).
• End the session.

Manager#

The manager or co-host role can be assigned to a participant by the host to help the host to manage the session participants.

A manager of the session is assigned the following subset of the host privileges.

• Remove participants from a session.
• Change the display name of a user in the session.
• Mute or unmute a user's audio.
• Prevent other users from sharing their screen (lock screen).

Participant#

A regular user who joins the session without host or manager permission. A participant has privileges to view their own information as well as the information of other users.#

Manage users#

See below for details on how to manage users.

Change display name#

If you are the host, you can change your display name while in the session using changeName within IZoomVideoSDKUserHelper. If you are the host or a manager, you may also change the display name of other users:

// Change name of user.
IZoomVideoSDKUserHelper* pUserHelper = m_pVideoSDK->getUserHelper();
pUserHelper->changeName(strNewDisplayName, pUser);

Transfer host privilege to another user#

The host of a session can transfer the host role to another user by calling makeHost within IZoomVideoSDKUserHelper.

// Check if the current user is the host.
IZoomVideoSDKUser* pLocalUser = m_pVideoSDK->getSessionInfo()->getMyself();
bool localUserIsHost = pLocalUser->isHost();

if (localUserIsHost) {
    // Transfer host privileges to User.
    m_pVideoSDK->getUserHelper()->makeHost(pUser);
}

Assign manager role#

Managers can help manage users while in a session. The host can promote a user to be a manager by calling makeManager within IZoomVideoSDKUserHelper.

// Check if the current User is the host.
IZoomVideoSDKUser* pLocalUser = m_pVideoSDK->getSessionInfo()->getMyself();
bool localUserIsHost = pLocalUser->isHost();

if (localUserIsHost) {
    // Make user a manager.
    m_pVideoSDK->getUserHelper()->makeManager(pUser);
}

Revoke manager role#

The host can revoke the manager role from a user by calling revokeManager within IZoomVideoSDKUserHelper.

// Check if the current User is the host.
IZoomVideoSDKUser* pLocalUser = m_pVideoSDK->getSessionInfo()->getMyself();
bool localUserIsHost = pLocalUser->isHost();

if (localUserIsHost) {
    // Revoke manager privileges from User.
    m_pVideoSDK->getUserHelper()->revokeManager(pUser);
}

Remove user from a session#

Users with either host or manager privilege can remove users from a session using removeUser within IZoomVideoSDKUserHelper.

// Get current user.
IZoomVideoSDKUser* pLocalUser = m_pVideoSDK->getSessionInfo()->getMyself();

// Check if the current User is the host.
bool localUserIsHost = pLocalUser->isHost();
// Check if the current User is a manager.
bool localUserIsAManager = pLocalUser->isManager();

if (localUserIsHost == true || localUserIsAManager == true) {
    // Remove User from session.
    m_pVideoSDK->getUserHelper()->removeUser(pUser);
}

Retrieve user#

To obtain the IZoomVideoSDKUser of the current user, use getMyself through IZoomVideoSDKSession.

// Get local user.
m_pVideoSDK->getSessionInfo()->getMyself();

To obtain all of the users in the session, use getAllUsers.

// Get all users.
m_pVideoSDK->getSessionInfo()->getAllUsers();

Get all users who are not the current user#

The user who is currently using this instance of the SDK is referred to as the local user. To get a list of all users who are not the local user use this method:

// Get all users who are not this user.
IVideoSDKVector<IZoomVideoSDKUser*>* remote_users = session->getRemoteUsers();

Session callbacks#

Find session callbacks within your IZoomVideoSDKDelegate implementation. For details on how to create a delegate to listen for these callbacks, see callback events. For a full list of callbacks, see the reference documentation for the IZoomVideoSDKDelegate class . Here's a list of some available ones:

• onSessionJoin(): Called when the current user has joined the session.
• onSessionLeave(): Called when the current user has left the session.
• onError(ZoomVideoSDKErrors errorCode, int detailErrorCode): Called when the SDK raises an error. For example, failure to join a session, network timeouts, etc. ZoomVideoSDKErrors_Success represents a successful callback without errors.
• onUserJoin(IZoomVideoSDKUserHelper* pUserHelper, IVideoSDKVector\<IZoomVideoSDKUser*>* userList): Called when any user joins the session. The helper provides user-related functionality. userList represents the updated list of users who just joined the session.
• onUserLeave(IZoomVideoSDKUserHelper* pUserHelper, IVideoSDKVector\<IZoomVideoSDKUser*>* userList): Called when any user leaves the session. The helper provides user-related functionality. userList represents the updated list of users who just left the session.
• onSessionNeedPassword(IZoomVideoSDKPasswordHandler* handler): Called when attempting to join a session that requires a password, but no password was provided. Use a handler parameter to retry joining the session. Through the IZoomVideoSDKPasswordHandler interface, call inputSessionPassword to pass in the password. Call leaveSessionIgnorePassword to not provide a password and leave the session instead.
• onSessionPasswordWrong(IZoomVideoSDKPasswordHandler* handler): Called when attempting to join a session that requires a password, but the provided password was incorrect. Use a handler parameter to retry joining the session. Through the IZoomVideoSDKPasswordHandler interface, call inputSessionPassword to pass in the password. Call leaveSessionIgnorePassword to not provide a password and leave the session instead.
• onHoldJoined(): Called when the current user joins a session with OnHold on and is placed on hold. See Hold participants until admitted.
• onHoldUserJoin(IZoomVideoSDKOnHoldHelper* pOnHoldHelper, IVideoSDKVector\<IZoomVideoSDKOnHoldUser*>* userList): Called when users are placed on hold. userList represents the users who were just placed on hold.
• onHoldUserLeave(IZoomVideoSDKOnHoldHelper* pOnHoldHelper, IVideoSDKVector\<IZoomVideoSDKOnHoldUser*>* userList): Called when users leave the on-hold list, either because a host or manager admitted them or because they left while on hold. userList represents the users who just left the on-hold list.
• onUserHostChanged(IZoomVideoSDKUserHelper* pUserHelper, IZoomVideoSDKUser* pUser): Called when the session host changes.
• onUserManagerChanged(IZoomVideoSDKUser* pUser): Called when the session manager changes.
• onUserNameChanged(IZoomVideoSDKUser* pUser): Called when the user's name changes.

Session callback examples#

Get notified when a local user successfully joins or leaves a session:

virtual void onUserJoin(IZoomVideoSDKUserHelper* pUserHelper, IVideoSDKVector<IZoomVideoSDKUser*>* userList){}

virtual void onUserLeave(IZoomVideoSDKUserHelper* pUserHelper, IVideoSDKVector<IZoomVideoSDKUser*>* userList){};

Get notified when the host of the session changes:

virtual void onUserHostChanged(IZoomVideoSDKUserHelper* pUserHelper, IZoomVideoSDKUser* pUser)
{
    printf("The host of the session is now: name=%s), pUser->getUserName());
;

Get notified when a password is required to join a session:

virtual void onSessionNeedPassword(IZoomVideoSDKPasswordHandler* handler){};

Get notified when a password is wrong when joining a session:

virtual void onSessionPasswordWrong(IZoomVideoSDKPasswordHandler* handler){};