Update page.

Sip RA Type Memo

Abstract

Definitions

Mid-dialog request := A request starting a new transaction within an already established dialog, as described in RFC 3261 section 12.2. Examples are re-INVITEs, BYE, MESSAGE.

Out-of-dialog request := A request that it sent outside an existing dialog. The most common example is an original INVITE which can lead to a dialog being created but which is by definition sent before any dialog exists.

SIP RA Type with dual event sets

Introduction

Activities and Sip RA interfaces

public ActivityContextInterface getActivityContextInterface(javax.sip.Dialog dialog) throws NullPointerException, UnrecognizedActivityException, FactoryException;

Table of events

1. This event also ends the activity.
2. This event is used when the request method is not recognized.
3. This is just for "100 Trying" responses, which can usually be safely ignored by the app.
4. These events will be fired instead of the usual response/timeout events, if a dialog activity exists.
5. If a BYE request that terminates the dialog is received, the RA will fire a javax.sip.dialog.TerminationRequest event instead of a javax.sip.dialog.Request.BYE event.

Events and activities

Out-of-dialog request events

• Obtain the javax.sip.Dialog object for the request which is done by calling the javax.sip.SipProvider.getNewDialog(Transaction tx) method. (The SipProvider is obtained from the JainSipResourceAdaptorSbbInterface)
• Get the activity context interface by calling

  SipActivityContextInterfaceFactory.getActivityContextInterface(Dialog dialog)

• Attach to the dialog ACI

Code snippet:

JainSipResourceAdaptorSbbInterface intf = ...
SipActivityContextInterfaceFactory factory = ...
SbbLocalObject myLocalObject = ...
SipProvider provider = intf.getSipProvider();
Dialog dialog = provider.getNewDialog(requestEvent.getServerTransaction());
ActivitiyContextInterface aci = factory.getActivityContextInterface(dialog);
aci.attach(myLocalObject);

From this point the following mid-dialog requests will be delivered on the dialog ACI. The RA does create server transaction activities for these requests and if the application needs to use the corresponding ACI it can obtain it by doing the following

ServerTransaction tx = RequestEvent.getServerTransaction();
SipActivityContextInterfaceFactory factory = ....
ActivityContextInterface aci = factory.getActivityContextInterface(tx);

It is not necessary to create the dialog ACI and attach to it immediately after the dialog has been obtained. This step can be postponed to a later stage since the dialog object is obtainable from the javax.sip.RequestEvent , javax.sip.ResponseEvent and javax.sip.Transaction objects respectively. Hoever this is encouraged in cases when dialgo has not been created automaticly. Some implementations can depend on attaching to dialog ACI.

Mid-dialog request events

There are a few methods that deserve some extra explanation:

• javax.sip.dialog.Request.ACK

• javax.sip.dialog.Request.BYE

Automatic dialog creation

 <event event-direction="Receive" initial-event="True">
            <event-name>InDialogInvite</event-name>
            <event-type-ref>
                <event-type-name>javax.sip.dialog.Request.INVITE</event-type-name>
                <event-type-vendor>net.java</event-type-vendor>
                <event-type-version>1.2</event-type-version>
            </event-type-ref>
            ....
 </event>

Responses

Applications that want to use the dialog support must obtain a dialog before a dialog creating request is sent (see the JAIN SIP 1.2 documentation). Code snippet:

JainSipResourceAdaptorSbbInterface intf = ...
SipActivityContextInterfaceFactory factory = ...
SbbLocalObject myLocalObject = ...
ClientTransaction tx = ....
SipProvider provider = intf.getSipProvider();
Dialog dialog = provider.getNewDialog(tx);
ActivitiyContextInterface aci = factory.getActivityContextInterface(dialog);
aci.attach(myLocalObject);

It is not mandatory to create and attach to the dialog ACI at this stage, this can be postponed to a later stage if desired. (But it is encouraged as soon as dialog representing object has been created) The code snippet shows the recommended way for most applications. If the Sbb is attached to the dialog ACI when the request is sent the behaviour of the RA is to deliver response events on a client transaction activity if the dialog state is not affected. For responses that affect the state of the dialog the events from the “Dialog state events” category are used. See next section for example flows containing both types of events.

Dialog state events

javax.sip.dialog.SetupFailed event.

The dialog state is affected by responses, requests and timeouts and the following is a brief survey of the events.

When a provisional response with a To tag is received the dialog enters the early state and a

javax.sip.dialog.SetupEarly

If then a 2XX final response is received a

javax.sip.dialog.SetupConfirmed

In case of a non 2XX final response a

javax.sip.dialog.SetupFailed

If the dialog setup times out a

javax.sip.dialog.SetupTimedOut

The

javax.sip.dialog.Terminated

Timeout events

javax.sip.Timeout.TRANSACTION

The

javax.sip.Timeout.DIALOG

Example scenarios

Successful INVITE

1. Sbb attached to dialog ACI & client transaction ACI
2. Client transaction & dialog activitiy started
3. INVITE --->
4. <--- javax.sip.message.Response.Trying on client activity
5. <--- javax.sip.dialog.SetupEarly on dialog activity
6. <--- javax.sip.dialog.SetupConfirmed on dialog activity
7. ACK --->
8. Client transaction activity ended
9. Dialog activity continues to exists, here subsequent mid-dialog requests can occur within this activity
10. Client transaction activity started
11. BYE ---> (Which should be sent via the javax.sip.Dialog.sendRequest method)
12. <--- OK
13. Client transaction & dialog activity ends

Cancelled invitation (original INVITE)

1. Server transaction activity started
2. <--- javax.sip.message.Request.INVITE on server transaction activity
3. Sbb creates dialog and attaches to dialog ACI
4. Dialog activity started
5. 180 Ringing --->
6. UAC Dialog enters early state, now it is legal for the UAC to cancel the request
7. <--- SIP CANCEL arrives at the RA which responds 200 OK to the CANCEL and 487 “Request Terminated” to the INVITE request being cancelled
8. <--- javax.sip.message.Request.CANCEL on server transaction activity
9. Both server transaction and dialog activity ended

(If the Sbb tries to respond 200 OK after the RA has responded 487 “Request Terminated” the RA must throw an IllegalStateException)

Design choices

Response event javax.sip.message.Response.TRYING

By making "100 Trying" a separate event type, this makes it easy for the RA to filter out these responses, so they never have to enter the SLEE event router. The RA can know that no services are interested in "100 Trying" events by implementing the serviceActivated/serviceDeactivated callbacks (from JSR 240 EDR) and keeping track of the event types that services require.

If we did not have this separate event type, we would have to always fire an "INFORMATIONAL" event for "100 Trying", even though it is almost certainly not used by any application. This design choice is partly an optimization, partly a cleaner separation of event types that haev different meaning for applications.

Cancellation

In SIP the CANCEL method is used to cancel a previously sent request. The only method that is subject to cancellation (of the core methods defined in RFC 3261) is INVITE because it is the only method that can take a long time to complete.

The CANCEL request is sent in a transaction of its own, although it refers to the transaction to be cancelled (see RFC 3261 for details). When a CANCEL request is received the folllowing procedure is to be perfomed:

• 1. CANCEL arrives at RA. RA checks to see if it matches a previous ServerTransaction. If there is a match, go to (2), else (3)

• 2. The CANCEL matches a previous ServerTransaction (INVITE), here the RA can send a 200 OK response for the CANCEL if final response has not been sent, otherwise it should drop CANCEL. ( Actually firing CANCEL and OKing its transaction should be postponed a little bit to give sbbs chance to process INVITE - as it could be to late to CANCEL this INVITE)

• 2a. If there is also an associated dialog activity, the RA generates the 487 response and ends the dialog activity. The CANCEL event is fired on the ServerTransaction activity to inform the app. The app does not need to do anything else.

• 2b. If no dialog activity is present, then fire the CANCEL event on the ServerTransaction activity. The app must handle this as appropriately, ie. send a 487 if it is a UAS, or cancel pending branches if it is a proxy.

• 3. If there is no match, the CANCEL event must be passed up statelessly to the app - a proxy will need to statelessly forward this downstream. Here there is no activity to fire the event on, so the RA will need to create a "one-shot" dummy activity that ends immediately after the event is fired. This one shot activity should implement javax.sip.ServerTransaction. ( Good candidate would be CANCELs ServerTransaction)

• 4. If the CANCEL did not match any previous ServerTransaction , and the CANCEL event in (3) was not processed by any SBBs (the RA can detect this in the event processing callbacks in the SLEE 1.1 RA API), then I think in this case the RA is safe to respond with "481 Call/Transaction Does Not Exist".

- in order to make this procesing path available when application acts as proxy , application has to remove ServerTransaction associated with INVITE from activities list - for isntance explicitly terminate it. However this would nto be good approach, instead RA implemenattion should give means to notice RA that request with this transaction has been proxied. Or RA should asume that if no dialog has been created after INVITE processing and its TX has not entered terminated state that "we" are acting as proxy.

In step (2) there is a potential race between the SBB sending a final response and the RA firing the CANCEL event. It is up to the RA implementation to resolve this. For example, if the SBB tries to send after the RA has fired the CANCEL event, the RA could detect this and throw an IllegalStateException.

Possible implementation choice for dialog timeout event

Future changes

The following is a list of possible future changes.

Proxy support

Forking

Transaction stateless behaviour

List of contributors to this proposal

• Open Cloud
• Mobicents
• NIST

-- Main.niklasuhrberg - 04 May 2006