Invite Users to a Conference

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.

Before inviting a remote user to a conference, the local client must schedule a conference and obtain the conference Focus URI. The URI is returned to the local client in the OnScheduleConference event. Inviting a remote user to a conference involves sending the conference Focus URI to a remote user in an application session. A separate application session must be created for each remote user invited to a conference. For information about scheduling a conference, see Schedule a Conference.

The following sections discuss the two methods of inviting a remote user to a conference:

Dial-in.
A dial-in invitation is initiated by a local user to invite a remote user to a conference. The remote user accepts an invitation directly from the conference-scheduling user in an application session, creates the necessary sessions and enters the conference.
Dial-out
A dial-out invitation is an invitation that is initiated by a conference MCU and sent to a client as a media-specific session. For devices that cannot accept a conference invitation in an application session (such as a UC enabled telephone), the dial-out invitation is the only method that can be used to invite a user.

Important

A UC-enabled telephone cannot accept the application session invitation used to invite users to an audio conference. Instead, the telephone must accept a call generated by the conference MCU itself. This is known as a dial-out invitation.

Dial-in Invitations

The following procedures create a dial-in conference invitation.

Create a Conference Invitation

A separate conference invitation must be created for each remote user invited to a conference.

Start an application session

Create the application session with a session manager and then assign a context to the session. In the following example, the remote user invited to a conference with this application session is tied to the new application session with the named "ConfInvitee" property.

Important

If the conference invitation is being sent to escalate an existing peer-to-peer session, you must add the conversation ID of the peer-to-peer session to the new application session used to invite the remote participant.

The following example is drawn from an application method that invites a remote user to a conference. The example gets the conversation ID of an existing peer-to-peer session that is being escalated to a conference. The conversation ID is added to the outgoing conference invitation. The invitation recipient matches the conversation ID received in the conference invitation with the conversation ID of the peer-to-peer session that is active with this local client.
```
// Cast session manager from instance of IUccEndpoint.
IUccSessionManager sm = this.endpoint as IUccSessionManager;

// New context object.
UccContext sessionContext = new UccContext();

sessionContext.AddNamedProperty("ConfInvitee", "SIP:stigp@contoso.com");

if (PeerSession != null)
{
    //PeerSession is an instance of IUccSession and is an active
    // peer-to-peer session that is being escalated to a conference.
    string s_PeerToPeerSessionConversationID = PeerSession.Context.get_Property(
        10000).StringValue;

    //When escalating from peer-to-peer session, add the conversation ID of
    //the peer-to-peer session.  
    sessionContext.AddProperty(10000, s_PeerToPeerSessionConversationID);
}
// Create IUccSession. 
IUccSession _ApplicationSession = sm.CreateSession(UCC_SESSION_TYPE.UCCST_APPLICATION, sessionContext);
UCCPApplicationSesion s_AppSession = new UCCPApplicationSesion(s_Session);
```
After the client obtains an instance of IUccSession, an instance of the UCCPApplicationSession application class is created with the public UCCPApplicationSesion(IUccSession pApplicationSession) constructor.
Obtain an instance of UccUri for the remote invited user.

The primary source of UccUri instances is a local user's contact list. The Uri property of a IUccContact instance returns a UccUri instance. Alternatively, use the ParseUri method to return a UccUri instance when the SIP URI string of the remote user is passed.
Create an application session participant. A session participant is created for an application session by calling into CreateParticipant. The UccUri parameter value is an instance from a collection of UccUri instances that represent an invitee list.
```
// Create new session participant.
this.myRemoteParticipant =  this.myApplicationSession.CreateParticipant(
    pRemoteUri, 
    sessionContext);
```

Issue Conference Invitations

Issuing a conference invitation involves advising for application session participant events and adding an application session participant to the new application session.

Advise for application session participant events

Cast the application session participant to the IUccApplicationSessionParticipant type. To complete the conference invitation, the IUccApplicationSessionParticipant instance exposes the necessary application session participant events.
```
// Cast session participant to application session participant.
this.myAppParticipant = this.myRemoteParticipant as IUccApplicationSessionParticipant;
```

Advise for _IUccApplicationSessionParticipantEvents events.

// Advise for application session participant events and set event handler to this class.
UCC_Advise<_IUccApplicationSessionParticipantEvents>(
    this.myAppParticipant, 
    this);

Issue conference invitation

Create an operation context instance. UccOperationContext is a cocreatable class that is created with a call into the UccOperationContextClass() constructor. After creating UccOperationContext, it must be initialized with a call into the Initialize method. The UccContext parameter can be null.
```
// Create operation context class and set existing context as operation context.
UccOperationContext inviteOperationContext = new UccOperationContextClass();
inviteOperationContext.Initialize(1, sessionContext);
```

Add the participant to the application session by calling the AddParticipant method on the application session instance.

// Add the participant to the session. 
// This operation triggers the application invitation to be sent and raises
// OnOutgoingInvitation.
this.myApplicationSession.AddParticipant(
    this.myRemoteParticipant,
    inviteOperationContext);

Handle the application session participant OnOutgoingInvitation event.

If you use a custom client to invite a Microsoft Office Communicator client, two properties exposed by the OnOutgoingInvitation event data parameter must be filled in the following manner:

ContentType provides an Office Communicator client with the context of an incoming application session. The value must be "application/ms-conf-invite+xml".

SessionDescription must contain an XML string conforming to an XML schema published by Office Communicator.

The following example is an XML string conforming to the Office Communicator XML schema. The element values are supplied by the local user initiating the conference. In this example, Jesper Aaberg has created a conference and is using the conference Focus URI returned in the OnScheduleConference event.

<Conferencing version="2.0">
   <focus-uri>sip:Jeaaberg@contoso.com;gruu;opaque=app:conf:focus:id:1CBEA21157B6974DAF40A6D279F43F6A</focus-uri>
   <subject>Budget Conference</subject>
   <im available="True">
      <first-im>Fiscal year 2009 budget sign-off meeting. Attendence is required.</first-im>
   </im>
</Conferencing>

After filling ContentType and SessionDescription, call Send on the event data parameter.

The following example handles OnOutgoingInvitation. The string value of the focus-uri element is obtained in the OnScheduleConference event that is raised after a Focus Factory processes a request to schedule a conference. For information about scheduling a conference, see Schedule a Conference.

/// <summary>
/// Before outgoing invitation is sent, callback function injects
/// XML string containing the Conference URI, IM availability, 
/// and the first IM greeting.
/// </summary>
/// <param name="pEventSource"></param>
/// <param name="pEventData"></param>
void _IUccApplicationSessionParticipantEvents.OnOutgoingInvitation(
    UccApplicationSessionParticipant pEventSource,
    UccOutgoingInvitationEvent pEventData)
{

    // Initialize XML string.
    string sessionDesc = string.Empty;

    string boolString = string.Empty;
    if (this.myIMAvailable == true)
    {
        boolString = System.Boolean.TrueString;
    }
    else
    {
        boolString = System.Boolean.FalseString;
    }


    // Create conference invitation XML string.
    sessionDesc = @"<Conferencing version=""2.0"">"
    + "<focus-uri>sip: Jeaaberg@contoso.com;gruu;opaque=app:conf:focus:id:1CBEA21157B6974DAF40A6D279F43F6A</focus-uri><subject>"
    + this.myConferenceSubject
    + "</subject>"
    + "<im available=\""
    + boolString
    + "\"><first-im>"
    + this.myFirstIMGreeting
    + "</first-im></im></Conferencing>";

    // Define outgoing application session as a conference invite session.
    pEventData.ContentType = "application/ms-conf-invite+xml";

    // Put the conference invitation XML into the outgoing application session.
    pEventData.SessionDescription = sessionDesc;

    // Send the invitation.
    pEventData.Send();

}

The remote user added to this application session receives the conference invitation as an application session after the local client calls Send. For more information about receiving an incoming conference invitation, see Accept a Conference Invitation.

Share via

Invite Users to a Conference

Dial-in Invitations

Create a Conference Invitation

Issue Conference Invitations

See Also

Concepts

Additional resources