Performing Essential Session Tasks

Article
06/14/2014

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

A Microsoft Unified Communications Client API session represented by the IUccSession interface is the base type on which all specific session types are built. The IUccSession interface is used to establish a session, create, add, and remove a remote participant, and also add the modality-specific session interfaces that conduct the new session according to a specific modality. The methods exposed by the IUccSession interface are not available within the modality-specific session interfaces. The modality-specific interfaces expose methods and properties designed to support the unique character of a given modality. For example, the Audio/Video session interface provides a mechanism to add media channels to a session participant. With the IM session interface, you can send a text message to the remote session participant.

If you create an instant message (IM) session, an audio/video session, or any other session, you must perform several common session setup tasks before a new client session can be used. These tasks include:

Obtain a Session Manager
A session manager creates new session instances when a local user initiates a new session with a remote user. The session manager is obtained from an enabled endpoint. To manage the creation of outgoing sessions and the response to incoming session invitations, Unified Communications Client API exposes the IUccSessionManager interface.
Create an Outgoing Session
Advise for session events.
The IUccSession object raises events from the _IUccSessionEvents dispinterface. The modality-specific session interfaces raise events specific to session modality type. To receive generic session events and type-specific session events, you must advise for both session and modality-specific session events.
Invite a Participant
Inviting a participant amounts to calling AddParticipant on the session object used to create the participant.

To create a session of any type, the CreateSession method is called on the session manager interface obtained from the enabled endpoint object. The first argument of the method call is of type UCC_SESSION_TYPE representing the specific session type to be created.

Obtain a Session Manager

Obtain IUccSessionManager from the enabled endpoint.
```
// Assume IUccEndpoint endpoint has been created and enabled.
this.sm = endPoint as IUccSessionManager;
```
Important

You should obtain the session manager within the OnEnable callback method. Get the session manager if the enable action is complete (pEventData.IsComplete = true) and the endpoint is enabled (pEventData.StatusCode >= 0). A session manager is obtained only once. It is used whenever a local user creates a new outgoing session.

Advise for session manager events so client can accept incoming session invitations.

void _IUccEndpointEvents.OnEnable(
    IUccEndpoint pEventSource,
    IUccOperationProgressEvent pEventData)
{
    try
    {
        // Is enable operation complete?
        if (pEventData.IsComplete)
        {

            // Is status OK?
            if (pEventData.StatusCode >= 0)
            {

               // Cast session manager from SIP endpoint.
               // Session manager (sm) is a class member.
               this.sm = pEventSource as IUccSessionManager;

               // Advise for session manager events.
               UCC_Advise<_IUccSessionManagerEvents>(sm, this);

            }
            else
            {
                // Sign in failed. Make class endpoint reference null.
                this.endpoint = null;
            }
        }
    }
    catch (Exception)
    {
       throw;
    }
}

Accepting or declining an invitation to join a session regardless of its type is handled by a single callback function, OnIncomingSession. For information about session manager events, see Handling Session Invitations. For information about session types, see Session Objects.

Create an Outgoing Session

Create a session by calling the CreateSession method. The following example creates an instant messaging session. Creating an audio/video, application, or conference session is done in the same way except the enumerated session type value is set based on the desired session type. The returned session can only be cast to the modality-specific session

If you intend your custom client to interoperate with Microsoft Office Communicator, you must create a unique conversation ID for any session you create. The conversation ID is added to the outgoing session invitation when you add a specific property to the operation context passed to CreateSession. You must assign a property ID of 10000 to the conversation identifier property added to your operation context.

// Private class field.
private IUccSession _session;
//... additional class logic.

// Create IUccSession and store reference in private class field.
// New context object.
UccContext sessionContext = new UccContext();

// Create named property in new context object.   
sessionContext.AddNamedProperty("RemoteParticipant", "robertP@contoso.com");

// Create GUID to uniquely identify session.
string _ConversationGUID = System.Guid.NewGuid().ToString();

// Assign GUID string as session property.
// 10000 is a reserved value that causes the platform
// to insert the GUID into the outgoing session invitation.
sessionContext.AddProperty(10000, _ConversationGUID);

this._session = this.sm.CreateSession(UCC_SESSION_TYPE.UCCST_INSTANT_MESSAGING,sessionContext);

Advise for session events.

// Advise for session events with new session as event source,
// with session wrapper class (this) as event sink.
UCC_Advise<_IUccSessionEvents>(this._session, this);

For information about handling session events, see Handling Session Events.

Cast session object to modality type-specific interface.

IUccInstantMessagingSession IMSession = this._session as IUccInstantMessagingSession;

Invite a Participant

Call the CreateParticipant method on the new session.

To invite a remote user to a new session, an instance of the session participant is created and then added to the new session. The following example continues using the SessionOut object used in previous examples. In addition, the example creates an operation context object to pass in the second argument of AddParticipant. This process can provide specific context information to a callback function that handles the OnParticipantAdded event.

For a complete code example, see Code Listing: A Session Class.
Advise for events raised by the new participant.
Add the participant to the new session.

The following example creates the remote session participant that is invited to an IM session, advises for events on the new participant, and finally adds the participant to the new session. The example references this._session, a class field representing the new IM session.



/// <summary>
/// Adds a participant to the current session (this._session)
/// </summary>
/// <param name="u">UccUri representing the user to be added</param>
/// <returns>true if participant was created and the client
/// succeeded in calling AddParticipant</returns>
public Boolean addParticipant(UccUri u)
{
    try
    {
        // Create a session participant using the passed SIP URI.

        // Create a context for the new participant.
        UccContext ctx = new UccContextClass();
        ctx.AddNamedProperty("Participant", u.User);

        // Create the participant using the passed UccUri and new context.
        IUccSessionParticipant p = this._session.CreateParticipant(
                                    u,
                                    ctx);

        // Advise for events raised by the new session participant.
        UCC_Advise<_IUccSessionParticipantEvents>(p, this);

        // Create an operation context for the operation of adding the participant.
        UccOperationContext operationContext = new UccOperationContext();
        pContext.AddNamedProperty("OpCaller", "session.AddParticipant");

        // Initialize the operation context using the context created for
        // the new participant.
        operationContext.Initialize(1, ctx);

        // Add the participant to the session. This causes the platform
        // to send the IM invitation.
        this._session.AddParticipant(p, operationContext);

        return true;

    }
    catch (COMException ce)
    {
        
         MessageBox.Show(
            "sampleUCCPClient.session on add participant: COM Exception. " +
            ce.Message);
        return false;
    }

}

Performing Essential Session Tasks

Obtain a Session Manager

Create an Outgoing Session

Invite a Participant

See Also

Concepts

Additional resources