In Unified Communications Managed API version 1.0, a signaling session is modeled by the SignalingSession class. A signaling session consists of a local participant (LocalParticipant) and a remote participant (RemoteParticipant).

A session is uniquely identified by callid, from-tag and to-tag. The callid is generated when the session is created. The from-tag is assigned when the INVITE request is sent out. The to-tag is added by the remote participant when responding to the INVITE request.

A signaling session can be in any of the session states as enumerated by the SignalingState enumeration type. An application can examine the state of a session reading the State property of the session.

Associated with a signaling session are two signaling participants. One is local and the other is remote. A signaling participant is represented by a SignalingParticipant object. This object captures the information about a participant. The information includes the URI of the participant (Uri), the endpoint ID, which the participant uses to participate in a signaling session (EndpointId), and the display name of the participant (Name). In addition, a signaling participant object raises events when the display name or the endpoint ID is modified.

A signaling session supports the following events.

StateChanged

The session state has changed.

MessageReceived

A message is received in the session.

ReferReceived

A REFER request is received by this session.

Redirecting

The session is redirecting a request.

InvitationAccepted

The invitation to join the session is accepted by the remote participant.

InvitationCompleted

The invitation process completes.

TerminatedByRemote

The session is terminated by the remote participant.

An application must implement appropriate event handlers and register them with a newly created SignalingSession object if it is interested in receiving the notification and handling any of the events.

For more information about the programming patterns for handling session events, see Subscribing to Signaling Session Events.

For each endpoint, a signaling session starts when an invitation is accepted and ends when a termination request is sent.

In Unified Communications Managed API version 1.0, an outgoing signaling session is started for an endpoint when a SignalingSession object is created. The invitation to join the session is sent to the remote participant (chosen when the signaling session is created) by a call to the Participate (or its asynchronous version, BeginParticipate) method. For an incoming session, an endpoint accepts the session invitation by calling Participate (or its asynchronous version, BeginParticipate) when the session is received.

The invitation is inherently asynchronous and results in one or more responses from the remote participant. These responses trigger changes to the signaling session state. Participate or BeginParticipate…EndParticipate will fail if the session invitation cannot be delivered to the participant for some reason, such as, for example, an invalid URI is used or no connection can be established. An application should not call the synchronous method from any UI thread. Otherwise, the UI thread may be blocked while the invitation is processed.

In the Multiple Points of Presence (MPOP) situation, it is possible to have the invitation arrive at all the endpoints of the remote participant. The signaling session will process provisional responses from all the endpoints. However, only one successful response is used for establishing the session. After the session is established with one remote endpoint, none of the other remote endpoints can join the session. The sender can also send the invitation to a specific endpoint of the remote participant by specifying a specific endpoint ID, which can be obtained from another signaling session or a subscription session.

The programming patterns for initiating and receiving a signaling session are discussed in Creating an Outgoing Signaling Session and Receiving an Incoming Signaling Session.

An endpoint can use a signaling session to send messages to the remote participant or to receive messages from the remote participant. An application supports this by calling the synchronous SendMessage method or the asynchronous BeginSendMessage method. The messages can be of type Message or of the other enumerated message types supported by MessageType.

To receive the messages, an application must subscribe to receive and handle the MessageReceived event. For more information, see Programming Patterns in Unified Communications Managed API version 1.0.

Although Page-Mode Messaging can be used for exchanging messages between endpoints, session-based messaging has the advantage of less overhead because the connection or connection information is cached. Messaging in a session is therefore preferred when message exchange takes place in a form of conversation.

For information about programming patterns for sending and receiving a message in a signaling session, see Sending and Receiving Messages in a Signaling Session.

Signaling Header

Media negotiation is about exchange of media description that is transmitted as the payload of SIP messages. Media description allows the participants to describe their preferred media settings or acceptable media capabilities. Media negotiation involves one party making an offer and another presenting the answer. For example, when a participant invites another to a video chat, the inviting party makes an offer specifying both incoming and outgoing audio/video feeds at a certain rate. The invited party might not be able to stream video, because no video camera is installed on the device used by the invitee, or to receive high-fidelity sound, because the audio device is of a lower grade. In the answer, the invitee can present a counter offer specifying the acceptable media capabilities. Media is often described using Session Description Protocol (SDP). However, an application can use other protocols including custom protocols.

Media negotiation takes place during the process to establish a signaling session. When a participant invites another into a session, an INVITE message is sent to the invited party. To accept the invitation, the invitee sends a successful response (200 OK) back to the inviter. Upon receiving the response, the inviter sends an ACK message to the invitee to acknowledge the establishment of the session.

The inviter can include the media description as the body of the INVITE message. The included media description is referred to as an offer. The recipient of the invitation then examines the offer and decides whether to accept, modify, or reject the offer. If the offer is not rejected, the invitee prepares the answer to be accepted or modified and have it sent back along with the 200 OK response. Upon receiving the response, the session inviter might change media settings to match the received answer.

Another possibility is that the inviter can send an INVITE request with an empty offer (known as a null offer). When this happens, the invitee must make an offer and send it back in the 200 OK response. The inviter then must examine the offer, prepare an answer and send the answer to the invitee as part of the ACK message. Upon receiving the ACK message, the invitee must then change media settings according to the received answer.

Media description can also be renegotiated any time during a signaling session. Media renegotiation takes place when a re-INVITE message is processed. The media description is offered and answered in the same way as with an INVITE message. However, either participant can initiate the renegotiation, and the initial offer cannot be null.

In Unified Communications Managed API version 1.0, media description is represented by the ContentDescription class, which specifies the content type and a message body. Applications can extend this class to represent other media types. Media negotiation involves concerted efforts between an application and the platform: the platform is responsible for delivering the offers and answers, whereas the application is responsible for parsing the offer and providing the answer. To coordinate this effort, Unified Communications Managed API version 1.0 exposes the IOfferAnswer interface as the contract between the platform and applications for handling media negotiation. If interested in media negotiation, a Unified Communications Managed API version 1.0 application must honor the contract by implementing the interface to prepare an offer or answer to be sent by the platform. Applications interested in media negotiation must set the IOfferAnswer implementation as the value of the MediaNegotiation property. Applications not interested in media negotiation can set the OfferAnswerNegotiation property to null.

For more information about the programming patterns for media negotiation, see Negotiating Media in a Signaling Session.

To decline an incoming session, an application calls the Terminate or TerminateWithRejection method on a SignalingSession object.

When the session is declined, it is no longer available for any use because the resources have been freed, although some properties may still be accessible until the object is garbage collected.

To leave an existing session, the application can call Terminate at any time. This results in Unified Communications Managed API version 1.0 sending a BYE or CANCEL message, depending on the session state, and then disconnecting the session. Some properties of the session might still be accessible after Terminate is called.

When an invitation to join an incoming session arrives at an endpoint, an application can redirect the request to one or more other targets by calling either of the two overloaded TerminateWithRedirection or TerminateWithRedirection methods on the SignalingSession object. If the target is a single endpoint, the real-time address is used as the method parameter. Multiple-endpoint targets require a collection of endpoints to be supplied to the other overload of the method.

For more information about the programming patterns for redirecting a signaling session to another target, see Redirecting a Signaling Session.

A local endpoint in a signaling session can refer another participant to the remote endpoint. Currently, you can refer to a third endpoint inside an existing dialog.

For more information about the programming patterns for referring, see Accepting or Declining a Session Referral.

Concepts