In this topic three of the most common SIP offer/answer media negotiation scenarios in the Microsoft Unified Communications infrastructure are presented. Each scenario shows the steps taken by two applications, a local application, and a remote application. The programming pattern for media negotiation requires the following steps on the local and remote sides.
Initiating an INVITE Request with a Media Offer
In the first scenario a local application sends an
initial offer in the body of an INVITE request. The remote
application sends its answer in the body of a 200 OK
response.
- (Local side) The local application creates a new SignalingSession to
make an outbound call.
- (Local side) The local application binds an implementation of
the IOfferAnswer
interface to the SignalingSession
instance. The offer is prepared in this step.
- (Local side) The local application calls Participate on
the SignalingSession.
- (Local side) Unified Communications Managed API version 1.0
calls the GetOffer method that was implemented in Step 2.
The local application formats the offer and passes it in the
initial INVITE request to be sent to the remote participant.
- (Remote side) The SessionReceived event is raised on the
remote RealTimeEndpoint
object, which causes the developer-implemented handler for this
event to execute. For more information about the
SessionReceived event handler, see Receiving an Incoming
Signaling Session. The media offer is accessible from the
SessionReceivedEventArgs
parameter that is associated with this event handler. The remote
application can now start preparing the answer.
- (Remote side) When the answer is ready, the remote application
binds an implementation of the IOfferAnswer
interface to the SignalingSession
created upon receiving the INVITE request. It then calls
Participate on the SignalingSession
instance to accept the session.
- (Remote side) Unified Communications Managed API version 1.0
calls the GetAnswer method on the remote-side implementation
of the IOfferAnswer
interface. This method will return the answer prepared in Step 2.
The answer is then included as part of the
200 OK
response that is sent back to the session initiator.
- (Local side) Unified Communications Managed API version 1.0
then calls the SetAnswer method on the remote-side
implementation of the IOfferAnswer
interface so that the local application can consume the answer.
Accepting a 200 OK Request with a Media Offer
In the second scenario, the local application first
sends an INVITE message with an empty offer. The remote application
then responds with its offer contained in a 200 OK
response. Finally, the local application replies with an ACK
request that contains its answer to the offer sent by the remote
side.
- (Local side) The local application creates a new SignalingSession
instance to make an outbound call.
- (Local side) The local application binds an implementation of
IOfferAnswer
to the SignalingSession
instance.
- (Local side) The local application calls Participate on
the SignalingSession
object.
- (Local side) Unified Communications Managed API version 1.0
calls the GetOffer method on the local-side implementation
of the IOfferAnswer
interface, which returns a null ContentDescription
object. Unified Communications Managed API version 1.0 then sends
an initial INVITE without any offer. That is, there is no
Content-Type header, and the Content-Length value is zero (0).
- (Remote side) The SessionReceived event is raised on the
remote RealTimeEndpoint
object, which causes the developer-implemented handler for this
event to execute. For more information about the
SessionReceived event handler, see Receiving an Incoming
Signaling Session. The SessionReceivedEventArgs
parameter that is associated with this event handler can be
examined to discover that the INVITE was sent with an empty offer.
Because there is no offer, Unified Communications Managed API
version 1.0 asks the receiving party for an offer by calling the
GetOffer method on the remote-side implementation of the
IOfferAnswer
interface to present an offer.
- (Remote side) When the remote application chooses to accept the
session, it binds an implementation of the IOfferAnswer
interface to the SignalingSession
object created when the INVITE request was received. The
application then calls Participate on the SignalingSession
object to accept the session.
- (Remote side) Unified Communications Managed API version 1.0
calls the GetOffer method on the remote-side implementation
of the IOfferAnswer
interface, and sends a
200 OK
response that contains the offer as its payload.
- (Local side) On receiving the
200 OK
response from the remote participant, Unified Communications Managed API version 1.0 calls the HandleOfferInInviteResponse method on the local-side implementation of the IOfferAnswer interface, passing the offer in the OfferInInviteResponseEventArgs parameter. The application can then prepare its answer, and when it is ready, can call ReadyToAnswer. At this time, Unified Communications Managed API version 1.0 calls GetAnswer on the local-side implementation of the IOfferAnswer interface, and passes this answer to the remote endpoint as part of an ACK request.
- (Remote side) Upon receiving the acknowledgement, Unified
Communications Managed API version 1.0 calls the SetAnswer
method on the remote-side implementation of the IOfferAnswer
interface to pass the answer to the application. The application
can choose to reconcile any differences in media description based
on the newly arrived answer.
Renegotiating Media Description Inside a Signaling Session
Subsequent offers can be sent or received as part of media renegotiation inside a signaling session.
- (Local side) The local application prepares an offer in order
to renegotiate media capabilities of an established session.
- (Local side) The local application calls the
RenegotiateDescription method.
- (Local side) Unified Communications Managed API version 1.0
calls the GetOffer method on the local-side implementation
of the IOfferAnswer
interface.
- (Local side) Unified Communications Managed API version 1.0
sends a re-INVITE request that contains a new media description in
the SIP message body in the existing signaling session.
- (Remote side) Upon receiving the INVITE request on the remote
side, Unified Communications Managed API version 1.0 calls the
HandleOfferInReInvite method on the remote-side
implementation of the IOfferAnswer
interface. The offer can be accessed from the OfferInReInviteEventArgs
argument.
- (Remote side) The application extracts the media description
from the OfferInReInviteEventArgs
argument and uses it to asynchronously prepare an answer.
- (Remote side) When the answer is prepared, the remote
application optionally calls SendProvisionalResponse on the
OfferInReInviteEventArgs
instance. When the application is ready with its answer, it can
call Accept to accept the offer or Decline to decline
the offer. A call to Accept results in GetAnswer
being called.
- (Local side) After the
200 OK
response is received, Unified Communications Managed API version 1.0 calls the SetAnswer method on the local-side implementation of the IOfferAnswer interface to process the accompanying answer.