C++ API Library Reference  4.3.2-74-ge1d4cca
Public Functions | Public Static Functions | List of all members
CollaborationManager Class Referenceabstract

The CollaborationManager class provides methods to implement the collaboration functionality, and to manage which session is the owner.

About Session Ownership
CollaborationManager provides shallow collaboration: there is no difference, from a functionality perspective, between the host and the participants, and therefore changes in session ownership are not relevant to the end users. From a developer point of view, however, it is important to know that the size of the view on the host session dictates the size of the view for the collaboration participants (unless you explicitly override this default, see DefaultAllowSessionRenderOrResize).

The user who originally requests the URL for the collaboration session (called the share URL) is the session owner. If this user disconnects, session ownership automatically passes on to another collaboration participant (see IOwnerSessionProvider). It is also possible to use SetOwnerSession in this CollaborationManager class to pass ownership to a specific user when the host user is still connected.

About Color Providers
The color provider determines which color is assigned to each collaboration participant. This is useful, for example, when using the client-side acetate functionality: each participant's cursor or drawing on the view overlay will appear in a different color. PureWeb comes with a built-in color provider; changing this default is rare, but it is possible. For more information, see ISessionDefaultColorProvider.

Core Functions (most frequently used)

static CollaborationManagerInstance ()
 
static Guid GetSessionId (String elementName)
 
Guid OwnerSession () const
 
void SetOwnerSession (Guid sessionId)
 
virtual const Typeless GetSessionUserInfo (Guid sessionId)
 
virtual void SetSessionUserInfo (Guid sessionId, Typeless const &userInfo)
 
void InvalidateShare (String shareUrl, UpdateShareHandler callback)
 

Public Functions

void CreateShare (String password, UpdateShareHandler callback)
 
void CreateShare (String password, long timeout, UpdateShareHandler callback)
 
virtual Collections::List< ResponseInfo > GetNextResponses (Guid sessionId)=0
 
ISessionDefaultColorProviderGetSessionDefaultColorProvider ()
 
virtual void Initialize (StateManager *pStateManager)=0
 
bool IsInitialized () const
 
virtual void SessionConnected (Guid sessionId, Typeless const &command)=0
 
virtual void SessionDisconnected (Guid sessionId, Typeless const &command)=0
 
void SetOwnerSessionProvider (IOwnerSessionProvider *)
 
void SetSessionDefaultColorProvider (ISessionDefaultColorProvider *)
 
virtual void Uninitialize ()=0
 
Events
 DEFINE_EVENT (SessionsChanged, CollaborationManager &, EmptyEventArgs)
 
 DEFINE_EVENT (OwnerSessionChanged, CollaborationManager &, EmptyEventArgs)
 

Public Static Functions

static String GetSessionElementName (Guid sessionId)
 
static String GetSessionUserInfoName (Guid sessionId)
 

Usage Description

void CreateShare ( String  password,
UpdateShareHandler  callback 
)

Requests a share URL allowing collaboration directly from the service (this is not very common, as collaboration is usually initiated from client applications).

If you do not specify a timeout value as a parameter (see next method below), the URL will not time out unless you explicitly call InvalidateShare.

Parameters
passwordThe password that you want the participants to enter when joining the session.
callbackThe function that will be called when the share URL is received.
void CreateShare ( String  password,
long  timeout,
UpdateShareHandler  callback 
)

Requests a share URL allowing collaboration directly from the service (this is not very common, as collaboration is usually initiated from client applications).

Parameters
passwordThe password that you want the participants to enter when joining the session.
timeoutThe length of time (in milliseconds) that the share URL will remain valid for new participants to join.
callbackThe function that will be called when the share URL is received.
DEFINE_EVENT ( SessionsChanged  ,
CollaborationManager ,
EmptyEventArgs   
)

This event is triggered by a change to the session element in application state. This would happen, for example, whenever collaboration participants join or leave the session.

DEFINE_EVENT ( OwnerSessionChanged  ,
CollaborationManager ,
EmptyEventArgs   
)

This event is triggered by a change to the owner session element in application state. This would happen, for example, whenever a session host joins or leaves the session.

virtual Collections::List<ResponseInfo> GetNextResponses ( Guid  sessionId)
pure virtualinherited

Gets the next responses for the specified session.

Parameters
sessionIDThe session's unique identifer.
ISessionDefaultColorProvider * GetSessionDefaultColorProvider ( )

Returns the color provider currently set as the default. For more information, see ISessionDefaultColorProvider.

String GetSessionElementName ( Guid  sessionId)
static

Returns the name of the session element associated with the specified session ID. This is the name of the session element as it appears in the application state tree, in the form SessionId-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Guid GetSessionId ( String  elementName)
static

Returns the session ID associated with the provided element name. Expects an element name of the form SessionId-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

const Typeless GetSessionUserInfo ( Guid  sessionId)
virtual

Returns the content of the UserInfo element for the specified session ID.

UserInfo is an element in application state that stores any detail specific to a given collaboration participant.

String GetSessionUserInfoName ( Guid  sessionId)
static

Returns the name of the UserInfo element, as it appears in the application state tree, for the provided session ID.

virtual void Initialize ( StateManager pStateManager)
pure virtualinherited

Initializes the plugin with the specified StateManager.

Parameters
stateManagerThe StateManager.

Implemented in ViewManager.

CollaborationManager & Instance ( )
static

Returns the singleton instance of the CollaborationManager.

void InvalidateShare ( String  shareUrl,
UpdateShareHandler  callback 
)

Invalidates the specified share URL.

When a share URL is invalidated, new collaboration participants are not allowed to access the URL, but this has no impact on existing participants already in the session.

Parameters
shareUrlThe share URL to invalidate.
callbackThe function that will be called once the share URL has been rendered invalid.
bool IsInitialized ( ) const

Returns a boolean value indicating whether this instance is initialized.

Guid OwnerSession ( ) const

Returns the ID of the session currently set as the owner session.

virtual void SessionConnected ( Guid  sessionId,
Typeless const &  command 
)
pure virtualinherited

Indicates that the specified session is connected.

Parameters
sessionIdThe session's unique identifier.
commandThe command that was received causing the session to connect.
virtual void SessionDisconnected ( Guid  sessionId,
Typeless const &  command 
)
pure virtualinherited

Indicates that the specified session is disconnected.

Parameters
sessionIdThe session's unique identifier.
commandThe command that was received causing the session to disconnect.
void SetOwnerSession ( Guid  sessionId)

Sets a session as the owner session.

If set to Guid.Empty, then a new owner is chosen from existing sessions based on the owner session provider (see IOwnerSessionProvider). Otherwise, the specified value must be a valid session ID.

You can use this method to change ownership when the current host is still connected to the collaboration session.

void SetOwnerSessionProvider ( IOwnerSessionProvider provider)

Sets the default session owner provider. For more information, see IOwnerSessionProvider.

void SetSessionDefaultColorProvider ( ISessionDefaultColorProvider provider)

Sets the default color provider. For more information, see ISessionDefaultColorProvider.

void SetSessionUserInfo ( Guid  sessionId,
Typeless const &  userInfo 
)
virtual

Sets the UserInfo element to be posted to application state for the specified session ID. This is mostly used by PureWeb to manage collaboration under the hood.

UserInfo is an element in application state that stores any detail specific to a given collaboration participant.

virtual void Uninitialize ( )
pure virtualinherited

Uninitializes the plugin.

Implemented in ViewManager.