# 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. 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](/docs/video-sdk/auth/). Prior to joining, be sure that you have [set up a delegate for callback events](/docs/video-sdk/linux/integrate/#implement-a-delegate). ### 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: ```cpp 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. | Name | Required | Note | | ----------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sessionName` | Yes | Name and unique identifier of the session. A user will be able to join the session by entering the session name. Should be alphanumeric with a max-length of 150 characters. It can include symbols and the space character. Session names are case insensitive (they are all converted to lowercase). This must match the `tpc` value in the [SDK JWT payload](/docs/video-sdk/auth/#payload). | | `userName` | Yes | Display name of the user shown in the session. If empty, the name is displayed as the string "null". Max 200 characters. Values longer than 200 characters are truncated without error. | | `token` | Yes | [SDK JWT token](/docs/video-sdk/auth/) generated from your SDK credentials. | | `sessionPassword` | No | Password for session. If set, the session will be private and can only be joined if the user provides a valid password. If not set, the session will be public for anyone in your account. To join, they must use `sessionName` only. The field has a max-length limit of 10 characters, printable ASCII characters only (ch >= 32 && ch < 127). | | `audioOption` | No | Store values in `ZoomVideoSDKAudioOption` to configure audio settings. | | `videoOption` | No | Store values in `ZoomVideoSDKVideoOption` to configure video settings. | 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. ```cpp 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. ## 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.**_ ```cpp 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`](/docs/video-sdk/auth/#payload) 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: ```cpp // 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`. ```cpp // 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`. ```cpp // 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`. ```cpp // 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`. ```cpp // 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`. ```cpp // Get local user. m_pVideoSDK->getSessionInfo()->getMyself(); ``` To obtain all of the users in the session, use `getAllUsers`. ```cpp // 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: ```cpp // Get all users who are not this user. IVideoSDKVector* remote_users = session->getRemoteUsers(); ``` ## Session callbacks Find session callbacks within your `IZoomVideoSDKDelegate` implementation. See [callback events](/docs/video-sdk/linux/integrate/#callback-events) for details on how to create a delete to listen for these callbacks. See [the reference documentation for the `IZoomVideoSDKDelegate` class](https://marketplacefront.zoom.us/sdk/custom/linux/class_i_zoom_video_s_d_k_delegate.html) for a full list of callbacks. 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\* 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\* 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. - `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: ```cpp virtual void onUserJoin(IZoomVideoSDKUserHelper* pUserHelper, IVideoSDKVector* userList){} virtual void onUserLeave(IZoomVideoSDKUserHelper* pUserHelper, IVideoSDKVector* userList){}; ``` Get notified when the host of the session changes: ```cpp 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: ```cpp virtual void onSessionNeedPassword(IZoomVideoSDKPasswordHandler* handler){}; ``` Get notified when a password is wrong when joining a session: ```cpp virtual void onSessionPasswordWrong(IZoomVideoSDKPasswordHandler* handler){}; ```