Sessions

Sessions are the fundamental building blocks of the Video SDK. A session connects two or more users to communicate with each other over video and audio, similar to a virtual meeting.

Create and join a session

To create a session, you must provide a session name to uniquely identify it.

The process of creating and joining a session requires the developer's SDK JWT. When you create and join a session through the Video SDK, you must provide a string value representing the session name. The 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.

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.

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.

To create a session through the SDK, create an instance of ZoomVideoSDKSessionContext and provide the userName, sessionName,and JWT as shown below.

Create a ZoomVideoSDKSessionContext object

ZoomVideoSDKSessionContext sessionContext;
sessionContext.sessionName = L"Session name";
sessionContext.sessionPassword = L"Session password";
sessionContext.userName = L"User name";
// JWT for this session.
sessionContext.token = L"JWT";
// Video and audio options.
sessionContext.videoOption.localVideoOn = true;
sessionContext.audioOption.connect = true;
sessionContext.audioOption.mute = false;

Properties of the ZoomVideoSDKSessionContext object

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

Leave a session

When you are ready to leave the session, call the leaveSession method. Leave session has a bool parameter that when set to true will end the session. Note, only the host can end the session.

// A value of true will end the session, if you are the host.
m_pVideoSDK->leaveSession(false);

Callbacks

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

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

IZoomVideoSDKSession* pSession = m_pVideoSDK->joinSession(sessionContext);
if (!pSession)
{
    CString cstrInfo;
    cstrInfo.Format(_T("Failed to join session"));
}
else
{
    CString cstrInfo;
    cstrInfo.Format(_T("Joined session successfully."));
}

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

Important Callbacks

All of these callbacks can be found within your IZoomVideoSDKDelegate implementation. For information on implementation, See Integrate.

• onSessionJoin(): Called when current user has joined the session.
• onSessionLeave(): Called when 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. Helper is provided to provide 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. Helper is provided to provide 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. A handler parameter is provided to retry the join. Use handler when you would like 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. A handler parameter is provided to retry the join. Use handler when you would like 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.

Session callback examples

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

void CExampleListener::onSessionJoin()
{
    // You have successfully joined the session.
}
void CExampleListener::onSessionLeave()
{
    // You have successfully left the session.
}

Get notified when a user other than the local user successfully joins or leaves ### a session

void CExampleListener::onUserJoin(IZoomVideoSDKUserHelper* pUserHelper, IVideoSDKVector<IZoomVideoSDKUser*>* userList)
{
    CString strInfo;
    IZoomVideoSDKUser* pUser;
    int count = userList->GetCount();
    for (int i = 0; i < count; i++)
    {
        pUser = userList->GetItem(i);
        if (!pUser) continue;
        strInfo.Format(_T("A user joined the session: name=%s"), pUser->getUserName());
    }
}
void CExampleListener::onUserLeave(IZoomVideoSDKUserHelper* pUserHelper, IVideoSDKVector<IZoomVideoSDKUser*>* userList)
{
    CString strInfo;
    IZoomVideoSDKUser* pUser;
    int count = userList->GetCount();
    for (int i = 0; i < count; i++)
    {
        pUser = userList->GetItem(i);
        if (!pUser) continue;
        strInfo.Format(_T("A user left the session: name=%s"), pUser->getUserName());
    }
}

Get notified when the host of the session is changed

void CExampleListener::onUserHostChanged(IZoomVideoSDKUserHelper* pUserHelper, IZoomVideoSDKUser* pUser)
{
    CString strInfo;
    strInfo.Format(_T("The host of the session is now: name=%s"), pUser->getUserName());
}

Get notified when a password is required to join a session

void CExampleListener::onSessionNeedPassword(IZoomVideoSDKPasswordHandler* handler)
{
    // Store password handler.
    m_pPasswordHandler = handler;
    // When ready, call inputSesstionPassword on the handler.
    if (m_pPasswordHandler)
    {
        CString strPassword;
        m_pPswHandler->inputSessionPassword(strPassword.GetBuffer());
    }
    // Or ignore the password request and leave the session with leaveSessionIgnorePassword.
   /* if (m_pPasswordHandler)
    {
        m_pPasswordHandler->leaveSessionIgnorePassword();
    }*/
}

Get notified when a password is wrong when joining a session

void CExampleListener::onSessionPasswordWrong(IZoomVideoSDKPasswordHandler* handler)
    // Store password handler.
    m_pPasswordHandler = handler;
    // When ready, call inputSesstionPassword on the handler.
    if (m_pPasswordHandler)
    {
        CString strPassword;
        m_pPswHandler->inputSessionPassword(strPassword.GetBuffer());
    }
    // Or ignore the password request and leave the session with leaveSessionIgnorePassword.
   /* if (m_pPasswordHandler)
    {
        m_pPasswordHandler->leaveSessionIgnorePassword();
    }*/

Get user information

Each user joining a session is assigned an IZoomVideoSDKUser to provide access to various user information. This section gives you an overview of user information that you can view and manage.

While in a session, you can retrieve the following information of a user:

• CustomID
• Display name (UserName)
• Video status
• Audio status
• Share status
• Host status
• Manager status
• Video Statistics
• Share Statistics
• Custom Identity (set on JWT payload)

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();

Get user's video pipe

A user is tied to an IZoomVideoSDKRawDataPipe to render that user's video stream within a session. To obtain the video pipe of a user, use GetVideoPipe within IZoomVideoSDKUser. To obtain the share pipe of a user, use GetSharePipe.

// Get user's video pipe.
m_pUser->GetVideoPipe()
// Get user's share pipe.
m_pUser->GetSharePipe()

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