Developing SIP services

(1)

Nicolas Palix

INRIA Phoenix - LaBRI

[email protected]

http://phoenix.labri.fr/

Developing SIP services

(2)

Nicolas Palix

CPL, LESS and CCXML

(3)

Several Markup Languages for Call Control

◆

Call Processing Language (CPL) - IETF

◆

Call Policy Markup Language (CPML)

◆

Telephony Markup Language (TML)

◆

CallXML

◆

Service Creation Markup Language (SCML) – JAIN Forum

◆

Call Control eXtensible Markup Language (CCXML) – W3C

◆

Language for End System Services (LESS) - IETF

(4)

(5)

CPL Problem Statement

◆

Would like to allow end users to

 Define new services

» GUI tools or web

» Hand edit

» Back and forth

 Customize vanilla services

 Have their services be enabled instantly

◆

Service providers require

 Platform independence

» Decouple service creation tool from execution

(6)

What are the Options?

◆

Web interfaces populate customer profile data

 Not cross platform

 Not flexible

◆

End users write Java applications and upload

 Moving between GUI tools and hand editing is impossible

 Safety issue still exists; sandboxing helps but not completely

◆

BIG IDEA

(7)

Advantages of XML for call services

◆

Easily edited by hand or by GUI tools

◆

Cross platform

◆

Allows us to define our own language primitives

 Can engineer language to be safe

 Can make it easy to build many common services

◆

Can be manipulated by off the shelf XML tools

◆

Readily transported in HTTP, SIP, FTP, other means

◆

Small in size (compared to Java)

(8)

History of CPL

◆ Concept originated as end user

uploading of service logic in SIP REGISTER

 JDR and HGS, 1997

◆ Proposed as one of main work items

for new IP Telephony (iptel) working group when it was formed in Nov 1997

◆ Jonathan Lennox, Columbia U. took

role as primary driver and author

◆ Framework and Requirements done

first

 RFC2824 issued May 2000

◆ CPL specification

 First draft April 1999

 Submitted for consideration as RFC Dec. 2000

 RFC 3880

◆ Implementations

 First one by JDR, mid 1999 at Bell Labs

 Second by dynamicsoft

 Numerous ones exist or are in progress now » Indigo Software » Ubiquity » Netcentrex » SER » OpenSER

(9)

CPL FAQ

◆ Where do CPLs get executed?

 In network elements

» SIP Proxies

» SIP Application Servers

» H.323 Gatekeepers

 Can be used in clients, not designed for it

◆ Who writes CPLs?

 Engineered for end users to write

 Can be written by administrators and third parties as well

◆ How do CPLs get into the network?

 Uploaded in REGISTER (next slide)

 Uploaded in http POST

 Sent through any other means (Direct database writes, FTP, ...)

◆ What kinds of services are best suited for CPL?

(10)

Uploading CPL in REGISTER

◆ draft-lennox-sip-reg-payload-01

◆ CPL in REGISTER body

◆ MIME type application/cpl+xml

◆ Content-Disposition header  script  sip-cgi ◆ Action parameter  Store a CPL service  Remove CPL service ◆ If-Unmodified-Since header  Conditional deployment ◆ Accept header  Accept-Disposition header

REGISTER sip:sip.example.com SIP/2.0 From: Joe User <sip:[email protected]> To: "J. User" <sip:[email protected]> CSeq: 18 REGISTER

Expires: 1800

Call-ID: [email protected] Contact: sip:[email protected] Accept: application/cpl+xml

Authorization: Basic am9lOnBhc3N3b3JkAFBX Content-Type: application/cpl+xml Content-Length: 137 Content-Disposition: script;action=store <cpl> <incoming> <reject status=“400”/> </incoming> </cpl>

(11)

CPL Lifecycle

◆

CPL Execution starts on arrival

of INVITE message at a proxy

◆

Governs operation of proxy for

INVITE transaction ONLY

◆

When final response is sent,

CPL execution terminates



Does not stay “in the call”

◆

This is why CPL is good at

pre-call services like routing

and screening

Proxy

UA1

UA2

INV INV INV 300 ACK 600 ACK 600 CPL Lifecycle

(12)

CPLs

for caller _{called user}CPLs for

Proxies and CPL

◆ SIP call setups traverse proxies

◆ Which ones does a user need to

put their CPL on?

◆ CPL guides behavior of a single

proxy

 Incoming calls, CPL is

generally on proxy that

accesses registrations for that user

 Outgoing calls, CPL is

generally on local outbound proxy

 CPLs can be put anywhere

else

 Up to user/system to decide

where they need to go

(13)

CPL Structure

◆ CPL represents a tree

◆ Trees have nodes and links

 Each corresponds to a tag

◆ Nodes

 Actions to take

 Decisions to make

◆ Links

 Results of actions

 Which decision was made

◆ Subroutines

 Incoming

 Outgoing

(14)

<?xml version="1.0" encoding="UTF-8" ?> <!DOCTYPE cpl PUBLIC "-//IETF//DTD RFCxxxx CPL 1.0//EN" "cpl.dtd"> <cpl>

<subaction id="voicemail"> SOME STUFF HERE

</subaction>

<subaction id=“email”> SOME STUFF HERE </subaction>

SOME STUFF HERE </incoming>

SOME STUFF HERE </outgoing>

</cpl>

Beginning a CPL

◆ First line Specifies XML version

◆ Next line Specifies DTD

◆ CPL tag follows

◆ Within CPL tag, you can have

 subaction

 zero or one incoming

(15)

Mapping Trees to CPLs

lookup

proxy

What is the date? Reject Redirect succ ess fa ilu re Mon day ot_h e rw is_e <lookup source=“registration”> <success> <proxy/> </success> <failure> <time-switch> <time dtstart=20001001T000000” duration=“24H” freq=“weekly” byday=“MO”> <reject status=“400”/> </time> <otherwise> <redirect/> </otherwise> </time-switch> </failure> </lookup>

(16)

CPL Execution Model

◆

Processing begins at incoming or outgoing node

 Depends on system

◆

Server traverses tree

 Making decisions

 Performing actions

◆

Implicit global variable

 List of locations

◆

Certain nodes modify the location list

 location, lookup, location-filter

◆

Other nodes use the location list

(17)

Available node tags

◆ Signaling Actions  proxy  redirect  reject ◆ Decisions  address-switch  string-switch  time-switch  priority-switch ◆ Other actions  mail ◆ Location modifiers  location  lookup  remove-location ◆ Subroutine calls  sub

(18)

Proxy tag

◆ Node

◆ Proxies to current location list

◆ Outputs are result of proxy

 busy (486)  noanswer (408 or timeout)  redirection (3xx)  failure (4xx,5xx,6xx)  default (3xx, 4xx, 5xx, 6xx) ◆ Attributes  timeout  recurse  ordering » sequential » parallel <proxy recurse=“yes”> <busy> <reject/> </busy> <noanswer> <reject/> </noanswer> </proxy>

(19)

Proxy tag Details

◆ Tried elements are removed from global location list

 for parallel and sequential, that’s all sip URLs

 for first only, that’s the top sip URL

◆ Default timeout

 20s if a no-answer tag is present

 system defined otherwise

 why? If there is a no-answer, there is something else to do

◆ Default recurse is yes

◆ Default ordering is parallel

◆ Recursing

(20)

Redirect tag

◆ Node

◆ Redirects to the current locations

 Placed in Contact headers

 OK if there are no locations

◆ No outputs allowed

 CPL processing terminates

◆ Single attribute: permanent

 yes or no

 Indicates whether redirection

is a permanent or temporary

 For SIP, 301 or 302 response

(21)

Reject tag

◆ Node

◆ Rejects the call

◆ No outputs allowed  CPL processing terminates ◆ Attributes:  Mandatory: status » busy » notfound » reject » error

» SIP servers can also allow

numeric codes

(22)

Switch Statements

◆ Decision making components

◆ Common structure

 Start with X-switch, where X is

the element to check

 Subtags are all called X, and

each of them represents a link with a specific value of the

element

 otherwise is defined as an

allowed subtag of X-switch

 not-present as well - when

element is not in the message

<foo-switch> <foo is=“hello”> <reject/> </foo> <foo is=“goodbye”> <redirect/> </foo> <otherwise> <proxy/> </otherwise> <not-present> <log/> </not-present> </foo-switch>

(23)

Address-Switch

◆ Used to make decisions based on the value of address fields

◆ Defines two attributes, field and subfield

◆ Field is

 origin (From field)

 original-destination (To field)

 destination (Request URI)

◆ Subfield defines component of the URI in the field

 address-type (scheme of URL)

 user, password

 host, port

(24)

Address

◆ Outputs of address-switch are address tags

◆ Singe attribute, which can be one of is, contains, subdomain-of

◆ is

 used for exact match

 case sensitivity depends on subfield

◆ contains

 substring match

 case sensitivity depends on subfield

◆ subdomain-of

 only defined for tel and for host

 for host, it matches if the domain in the subfield is a subdomain of the

listed domain

 for tel, it matches if the telephone number contains the listed number as

(25)

<address-switch field=“destination” subfield=“user”> <address is=“ruser”/> </address-switch> <address-switch field=“destination” subfield=“port”> <address is=“5060”/> </address-switch> <address-switch field=“original-destination” subfield=“host”> <address subdomain-of=“com”/> </address-switch> <address-switch field=“origin” subfield=“display”> <address contains=“FDisp”/> </address-switch>

Address-Switch Examples

◆ Matching address tags example

◆ Assume the request contains

INVITE sip:[email protected] SIP/2.0 From: FDisplay <sip:[email protected]> To: TDisplay <sip:[email protected]>

(26)

Address-Switch motivations

◆

Older CPL drafts used string-switch for this

◆

Motivations for change

 Hard to match on specific fields through glob matching

 Glob matching was hard to implement

 Take advantage of inherent structure

(27)

String-Switch

◆ String matching on textual fields

◆ Request strings only

◆ Mandatory attribute “field”

indicates what is being matched

 subject

 user-agent

 organization

 display (free-form text)

◆ Subtags of string-switch

 string

◆ String contains either “is” or

“contains” for exact or substring matching <string-switch field=“subject”> <string is=“Sales”> <location url=“sip:[email protected]”> <proxy/> </location> </string> <string contains=“marketing”> <location url=“sip:[email protected]”> <proxy/> </location> </string> <otherwise> <location url=“sip:[email protected]”> <proxy/> </location> </otherwise> </string-switch>

(28)

String Switch Details

◆

Matching Issue

 Case insensitive

 These fields are freeform UTF-8!

» Case insensitivity depends on language and locale

» Nearly impossible to do

 Solution is a new Compatibility Composition form defined for Unicode

◆

Language is Accept-Language header in SIP

 Good for routing to operator based on language of caller

 Only substring matching is useful

(29)

Language-Switch

◆ Allows call dispatch

◆ Subtags are language tags

◆ Language tag

 Mandatory “matches” attribute

 Conventional values <language-switch> <language matches=“FR”> <location url=“sip:[email protected]”> <proxy/> </location> </language> <language matches=“US”> <location url=“sip:[email protected]”> <proxy/> </location> </language> </language-switch>

(30)

Priority-Switch

◆ Allows matching based on priority

of request

◆ Subtags are priority tags, which

have attribute less, equal, greater

◆ Comparisons are against defined

SIP values of emergency, urgent, normal, non-urgent

◆ If nothing is in request, ...

 priority is normal

◆ unknown priorities mapped to

normal for greater, less comparisons <priority-switch> <priority equals=“newpriority”> <location url=“sip:[email protected]”> <proxy/> </location> </priority> <priority less=“normal”> <location url=“sip:[email protected]”> <proxy/> </location> </priority> <priority greater=“urgent”> <location url=“sip:[email protected]”> <proxy/> </location> </priority> </priority-switch>

(31)

Time Switch

◆

Significantly different and more complex than initial version

 Initially crontab based

 Now iCal based

◆

Why iCal?

 RFC 2445

 Makes integration with calendaring programs easier

 More complete, more modern

◆

Based on an iCal subset

 implementable in O(1) time!

◆

Powerful representation of repeating events

(32)

Handling Timezones

◆ User and server may be in different timezone

◆ CPL times should refer to timezone of user

◆ How to indicate timezone of user?

◆ Offset from GMT not sufficient

 Want scripts to be valid for years

 Offset varies as DST comes and goes!!

◆ Solution

 time-switch contains either tzurl or tzid

 tzurl refers to an object that defines the timezone

 tzid refers to either a to-be-established registry, or a server specific

(33)

Time tags

◆ Time tags contain many attributes

that define repeating events

◆ Basic event description

 dtstart: event start date and

time

 dtend: event end time

 duration: instead of dtend

◆ Defining repetitions through

periodicity

 freq: frequency of occurrence

» daily, weekly, monthly,

yearly

◆ Limiting repetitions

 until: date/time when

repetitions end

◆ Defining exceptions

 byday

» List of days of the week

 bymonthday

» List of days of the month

 byyearday

» List of days of the year

 byweekno

(34)

Time Exceptions

◆

Expansion

 If frequency is a greater unit than largest exception

 Adds more events

 Example: freq=“yearly” bymonth=“jan,feb” defines an event that repeats

twice a year - once in jan, once in feb

◆

Contraction

 If frequency is a smaller unit than largest exception

 Reduces number of events

(35)

Time-switch Example

◆ Time of day forwarding/screening application

◆ Proxy calls to work during 9-5 during the week

◆ Proxy calls to home during the evening of the week

◆ Reject calls on weekends

<time-switch tzid="America/New-York”>

(36)

Location Addition

◆ Location

 Defines a location to be added to the global location list

 Single attribute, URL, contains the URL to add to the list

◆ Lookup

 Obtains the URI to add through indirection

 source attribute specifies place to go to

 registration looks in registration DB

 if source is a URL, fetches the URL and that contains a document with

just a URL to add

 success, failure, notfound outputs

(37)

remove-location

◆ Allows for removal of locations

from global location list

◆ Based on caller preferences

specification

◆ Caller prefs

 Associates parameters with

contacts

 Example: mobile=fixed,

media=video

 INVITEs contain headers that

ask to reach specific contacts by parameter

◆ Parameter filtering

 two main attributes, param

and value

 both are comma separated

lists

 param contains the name of a

parameter (e.g., mobile)

 value contains the value for

that parameter (e.g., fixed)

 same number of elements in

param and value lists

 causes matching contacts to

be removed

◆ Address filtering

 location attribute contains a

(38)

Example Parameter filtering

<remove-location field=“mobility,feature” value=“mobile,voicemail”>

sip:user@foo;mobility=“fixed” sip:joe@bar;feature=“voicemail”

(39)

Mail tag

◆ Allows CPL to send email

◆ Single parameter, url, contains mailto URL to use

◆ CPL server will

 Set the From field to its own address

 Set the body to contain information about the call, unless a body is

specified by CPL

 Set the Subject to something useful, unless subject is specified by CPL

◆ Caveats

(40)

Log tag

◆ Allows CPL to generate log output

◆ How output is logged is system dependent

◆ Two parameters

 name: specifies name of log to use

 interpretation of name is system dependent

 comment: text to place in log

◆ CPL should also generate time of day and other params in log

(41)

Subroutines

◆ CPL can call a subroutine

 defined by subaction

◆ Subactions have an id

◆ To call subroutine, use sub tag

 id as the value of ref attribute

◆ Subroutines can only be called if

they are physically above in the CPL  Avoids loops! <subaction id=“vmail”> <location url=“sip:[email protected]”> <proxy/> </location> </subaction> <incoming> <lookup source=“registration”> <success> <proxy> <default> <sub ref=“vmail”/> </default> </proxy> </success> <notfound> <sub ref=“vmail”/> </notfound> </lookup> </incoming>

(42)

Default Actions

◆ What happens if a script reaches

a point where there are no more tags?

◆ Default Action is taken

◆ Default action depends on how

far script has gotten

◆ No signaling actions, no locations

defined, location set empty

 lookup in database, proxy or

redirect as normal

◆ No signaling actions, no locations,

location set non-empty

 Happens for outgoing calls

◆ locations or lookups performed,

no signaling

 proxy or redirect there

◆ proxy action invoked, noanswer

output not present

 let phone ring forever, or until

system defined timeout

◆ proxy performed, responses

received

 forward best response

(43)

(44)

LESS

◆

LESS : Language for End System Services

◆

Draft IETF : draft-wu-iptel-less-00

 Expired on August 2005

◆

Implementation : sipc

◆

Graphical editor

◆

Authors : Xiaotao Wu and Henning Schulzrinne

◆

Inspired by CPL

◆

Use XML schema

◆

Interaction checker

(45)

LESS functionalities

◆

Same implicit locations as CPL

◆

Same switching actions

◆

Handle incoming calls and performs outgoing calls

◆

Timer based action

◆

Handle SIP events

◆

Handle IM messages

◆

Handle media sessions

(46)

LESS Action elements

◆ accept: accept an incoming call ◆ reject: reject an incoming call

◆ redirect: redirect an incoming call ◆ authenticate: authenticate an

incoming request

◆ call: make an outgoing call ◆ terminate: disconnect a call

◆ wait: wait for a certain time before

next action

◆ mail: send email

◆ log: log request handling process ◆ Media:mediaupdate: update media

attributes

◆ Midcall:merge: merge multiple calls ◆ UI:alert: alert user

◆ UI:getinput: get user input ◆ IM:sendmsg: send an instant

message

◆ Event:approve: approve subscription ◆ Event:deny: deny event subscription ◆ Event:defer: defer the decision on

event subscription

◆ Event:subscribe: send subscription

out

◆ Event:notify: send notification out ◆ Queue:enqueue: put a call and its

context into a queue

◆ Queue:dequeue: get a call and its

(47)

CCXML and VoiceXML

◆

CCXML 1.0 : Call Control eXtensible Markup Language

 Provide telephony call control support for dialog systems

 Working Draft (22 November 2006)

 http://www.w3.org/TR/ccxml/

◆

VoiceXML 2.0 : Dialog systems

 Recommendation (16 March 2004)

 http://www.w3.org/TR/voicexml20/

◆

Co-design...

 Many references to VoiceXML's capabilities and limitations

◆

However ...

 CCXML could be integrated with

» Traditional Interactive Voice Response (IVR) system

(48)

CCXML and VoiceXML System Architecture

(49)

CCXML

◆

Concepts

 Session : executing CCXML document(s)

 Connection : call legs

 Conference

 Dialog : interact with connections and conferences

◆

Functionalities

 Variables

 Loops

(50)

Nicolas Palix

JAIN SIP API

(51)

Java API's for Integrated Networks - JAIN

◆

JAIN SIP

◆

JAIN SIP Servlet

◆

JAIN SLEE

◆

JAIN Presence and IM

◆

JAIN SIMPLE

◆

JAIN SIP Lite

◆

JAIN ENUM

◆

JAIN MGCP

(52)

General information

◆

JSRs: Java Specification Requests

 JSR 32: JAIN SIP API Specification

◆

Website:

 https://jain-sip.dev.java.net/

◆

Documentation of JAIN SIP 1.2 (current version):

 http://snad.ncsl.nist.gov/proj/iptel/jain-sip-1.2/javadoc/

◆

Specification and Implementation Leads

 Phelim O'Doherty

Software Architect Sun Microsystems

(53)

Related projects

◆

Related JSR

 JSR 116: SIP Servlet API

 JSR 125: JAIN SIP Lite

 JSR 141: SDP API

 JSR 165: SIMPLE Instant Messaging

 JSR 180: SIP API for J2ME

◆

Reference Implementation available

 http://snad.ncsl.nist.gov/proj/iptel/

◆

Technology Compatibility Kit (TCK) available

◆

Related development

 https://sip-communicator.dev.java.net/

(54)

JAIN SIP for Instant Messaging

◆

JAIN SIP can be used for

building Instant Messaging

and Presence Clients and

Servers

◆

API supports the required

methods and Headers

◆

JAIN creates and manages

Dialogs for SUBSCRIBE and

MESSAGE methods

◆

NIST-SIP JAIN IM Client

SipListener is about 1100

LOC

(55)

JAIN-SIP in Proxy Servers

◆ JAIN SIP facilities construction of

Proxy Servers

◆ Stateless, Transaction-stateful, and

Dialog-stateful operation

◆ Application has access to

Dialog/Transaction state and route tables

◆ Support for extensibility and

application- controlled Routing

◆ Deep copy semantics for cloning

◆ Example Proxy (including presence

(56)

SIP Communicator

◆

A fully functional 100% Pure

Java SIP User Agent

◆

Hosted at

http://sip-communicator.dev.java.net

◆

Based on the JAIN-SIP RI

from NIST and JMF-2.1.1e

◆

Supports conversations over

both IPv6 and IPv4

◆

Uses the Stun4J stack to

handle NATs

(57)

JAIN SIP – A Event-Layer Abstraction

Application

which handles JAIN events

JAIN SIP API

Protocol Stack

(58)

Overview

◆

Java-standard interface to a SIP signaling stack.

 Standardized the interface to the stack

 Standardized the events and event semantics

 Application portability - verified via the TCK

◆

Designed for powerful access to the SIP protocol

◆

JAIN SIP can be utilized in a user agent, proxy, or embedded

into a service containers

◆

Supported RFC:

 RFC 3261, 2976, 3262, 3265

(59)

JAIN SIP Functionality

◆

JAIN SIP supports the RFC 3261 of SIP protocol

◆

JAIN SIP also supports the following SIP extensions:

 RFC 2976 allows for the carrying of session related control information

that is generated during a session (INFO)

 RFC 3262 provide information on progress of the request processing

(PRACK)

 RFC 3265 the ability to request asynchronous notification of events

(60)

JAIN SIP Functionality

◆

JAIN SIP also supports the following SIP extensions:

 RFC 3311 allows the caller or callee to provide updated session

information before a final response (UPDATE)

 RFC 3326 the ability to know why a SIP request was issued (Reason

header)

 RFC 3428 allows the transfer of Instant Messages (MESSAGE)

 RFC 3515 requests that the recipient refer to a resource provided in the

request (REFER)

(61)

(62)

Provider

Listener

JAIN SIP 1.2 Messaging Architecture

Application

Provider

Listening Point Stack

SIP messages SIP events

Provider Listening Point Stack Network Listening Point Provider Listening Point Listener Application Listening Point Listening Point

(63)

Generic SIP Application Structure

Application (SipListener) SipProvider SipStack Parser Encoder Rq Rp Rq Rq Rp T ra ns a ct io n T ra n sa ct ion T ra ns a ct ion Dialog Dialog Events Messages Messages Events Messages Events

(64)

JAIN SIP Object Architecture

Setup Function Listener SIP Factory

Stack Listening

Point

Proprietary

stack Proprietarystack

Network

Provider

1. Create SIPListener instance 2. getInstance()

3. create SIP Stack 5. create SIP Provider

4. create

Listening Point 6. add SIP Listener

Provider Provider Listening Point Listening Point

(65)

Responsibilities of the Application

◆

Application create the stack and the listening points

◆

Application registers an implementation of the SipListener

interface to interact with the SIP Stack

◆

Gets SipProviders from the Stack to send messages and create

SIP Transactions

◆

Application MUST go via SipProviders for all messaging with

the stack

 Application sends messages and access stack objects

via the SipProvider

(66)

Services provided by JAIN SIP

◆

Provide methods to format and send SIP messages

◆

Parse incoming messages and enable application to access to

fields via a standardized JAVA interface

◆

Invoke appropriate application handlers when protocol

significant (message arrivals, transaction time-outs, errors)

◆

Provide transaction support and manage transaction state and

lifetime on behalf of a user application

◆

Provide dialog support and manage dialog state and lifetime on

(67)

(68)

Application - Stack Creation

Initialize Stack using SipFactory

try {

Properties properties = new Properties();

properties.setProperty("javax.sip.STACK_NAME", "NISTv1.2"); properties.setProperty("javax.sip.OUTBOUND_PROXY",

"129.6.55.182:5070/UDP"); // Other initialization properties.

try { sipStack = sipFactory.createSipStack(properties); } catch(SipException e) { System.exit(-1); } }

(69)

Application - Processing Requests

Handle incoming messages as Events

public void processRequest(RequestEvent requestEvent) { try {

Request request = requestReceivedEvent.getRequest();

ServerTransaction st = requestEvent.getTransaction(); // do request specific processing here

} catch(Exception e) { // handle exception }

(70)

Application - Request Creation

Initialize Request using Factories

try {

SipURI requestURI = addressFactory.createSipURI (toUser, toSipAddress);

// Create other headers

Request request = messageFactory.createRequest

(requestURI, Request.INVITE, callIdHeader,

cSeqHeader, fromHeader, toHeader, viaHeaders, maxForwards);

(71)

Application - Sending Requests

Send outgoing messages

try {

// Create the client transaction ClientTransaction inviteTid =

sipProvider.getNewClientTransaction(request); // send the request

sipProvider.sendRequest(inviteTid,request);

(72)

(73)

Stateful or Stateless?

◆

Stateful request handling simplifies design

 Stack takes care of messy transaction details, retransmission, filters

duplicates etc

◆

Stateless handling is “Fire and Forget”

 Enhances scalability

 Good for building Proxy Servers (especially IM and Presence)

◆

You can have both stateful and stateless handling within a

(74)

SIP Transactions

SIP transaction consists of a single request and

any responses to that request

C lie nt tr a ns a ct ion S e rv e r t ra ns a ct io n C lie nt tr a ns a ct ion S e rv e r t ra ns a ct io n

(75)

Transaction Support

◆

Transaction is created on incoming Request or may be created

to send outgoing request

 When a Request is sent out statefully, application must request a

ClientTransaction for the outgoing Request

 When a new Request arrives, Stack associates a ServerTransaction with

Request and passes up to application

◆

When a response arrives, the Stack possibly associates a

previously created ClientTransaction with the response and

passes up to the Application

(76)

Client Transactions

◆

Requests are sent out statefully or statelessly

 Stateless requests are sent using SipProvider

 Stack implements a transaction state machine to support stateful

requests

◆

ClientTransaction is created to send outgoing Request statefully

 Application requests a new ClientTransaction from the SipProvider

 Application uses the ClientTransaction to send the Request

◆

When a Response arrives, the Stack possibly associates a

(77)

INVITE Server Transaction State Machine

RFC 3261 Ch 17 Proceeding Confirmed Completed Terminated Pass INVITE to TU Timer I Timer I 101-199 from TU 300-699 from TU

INVITE send response

Timer G fires Send response ACK

INVITE send response

(78)

Server Transactions

◆

Application may choose to handle non-Dialog-Creating request

either statefully or statelessly

◆

Application may choose to create Server Transaction when

Dialog-Creating Request arrives:

 Automatically creates a Dialog and marks its state to null

 Must be done when the event is delivered (cannot be deferred)

 All subsequent requests within the Dialog are assigned a Server

(79)

Generic SIP Application Structure

Application (SipListener) SipProvider SipStack Parser Encoder Rq Rp Rq Rq Rp T ra ns a ct io n T ra n sa ct ion T ra ns a ct ion Dialog Dialog Events Messages Messages Events Messages Events

(80)

Dialog Support

◆

A Dialog is a peer to peer association between communicating

SIP endpoints

 Maintains Route Sets and Sequence Numbers

◆

Dialogs are never directly created by the Application

 Dialogs are established by Dialog creating Transactions (INVITE,

MESSAGE, SUBSCRIBE?), however are managed by the stack.

◆

Dialog deletion may be under application control

(81)

Dialog Layer

◆

Dialog is a peer-to-peer association between communicating

SIP endpoints

 Dialogs established by successful completion of Dialog creating

Transactions

 Not all transactions create Dialogs

 A Transaction belongs to exactly one Dialog

 Dialog maps to multiple Transactions

 JAIN-SIP has extension methods to extend the standard set

 Dialog has a simple state machine which depends upon the state of

(82)

Dialog Layer

◆

SIP messages carry enough state to identify the Dialog directly

from the message

◆

For stateful operation: jain-sip maintains a dialog pointer for

every transaction

 Dialog d = transaction.getDialog();

(83)

Dialog Support

◆

Application may store its state using an opaque data pointer

 Dialog.[set/get]ApplicationData

 Note: available for Transaction only since version 1.2

◆

Dialogs store Route Sets and other useful information that can

be used for subsequent requests within the Dialog

JAIN-SIP makes this easy:

Request request = dialog.createRequest(Request.ACK);

ClientTransaction ct = sipProvider.createClientTransaction(request); dialog.sendRequest(ct);

(84)

Implementation Tips in a Stateful Server

Application Data

Incoming dialog (call leg)

INVITE

Outgoing dialog

(call leg) Outgoing dialog(call leg)

INVITE INVITE

◆

When all dialogs referencing the Application Data go away, so

(85)

Addresses, Messaging and Headers

◆

Defines support for Address/Header/Message Factories

◆

Address package contains a URI wrapper and defines URIs for

SIP and Tel URIs

◆

Header package defines interfaces for all the supported

headers

◆

Accessor (set/get) methods for SIP Header parameters

◆

Deep copy requirement for cloning Addresses, Headers and

(86)

JAIN SIP Extensibility

◆

SIP Extensions Typically Define:

 New Methods

 New Headers

 New Dialog Creating Methods

◆

JAIN SIP Supports these by:

 Architected ExtensionHeader that can be handled by name

(87)

(88)

JAIN SIP Object Architecture

Setup Function Listener SIP Factory

Stack Listening

Point

Proprietary

stack Proprietarystack

Network

Provider

1. Create SIPListener instance 2. getInstance()

3. create SIP Stack 5. create SIP Provider

4. create

Listening Point 6. add SIP Listener

Provider Provider Listening Point Listening Point

(89)

SipStack Interface

◆

Manages listening points and providers

◆

Can have multiple providers with multiple listening points

◆

Application can have multiple SIP stacks

◆

Cannot be deleted once created

◆

Instantiated by the SipFactory and initialized with a Property set

◆

javax.sip.* properties are reserved and names defined for stack

(90)

SipProvider Interface

◆

Send Request's either statefully via client transactions or

statelessly

◆

Send Response's to a recently received Requests either

statefully via server transactions or statelessly

◆

Register a SipListener to the SipProvider

 Notifies Registered Listener of Events (Request/Response/Timeout)

◆

De-register a SipListener from the SipProvider

 Once de-registered, no longer receive Events from SipProvider

◆

New Client and Server Transaction methods

◆

Listening Point manipulation methods

(91)

SipListener Interface

◆

A single SipListener per SipStack which implies a single

Listener in the architecture

 all SipProviders associated to a Sipstack have the same SipListener

◆

Process Request's either statefully or statelessly dependent on

application

◆

Process Response's to a recently sent Requests statefully

◆

Process Transaction timeouts and retransmits Timer events

◆

Notified when IO socket error occurs

(92)

(93)

Stack Configuration Parameters – JSIP 1.x

◆

javax.sip.STACK_NAME

 A string identifier for the stack. You can use this for logging and

management but the stack does not use it for processing

◆

javax.sip.IP_ADDRESS (deprecated)

 IP Address on which the stack listens for incoming messages (port is

specified when listening point is created)

 It is now a listening point parameter

◆

javax.sip.OUTBOUND_PROXY

 Has the format ipAddress:port/transport

(94)

Stack Configuration Parameters – JSIP 1.x

◆

javax.sip.ROUTER_PATH

 Router is a class that is consulted by the stack to route out of dialog

messages

 Application may provide its own router implementation

◆

javax.sip.EXTENSION_METHODS

 Extension methods are methods outside the standard ones that may

result in Dialog Creation

◆

javax.sip.RETRANSMISSION_FILTER (deprecated)

 Simplifies the complexities of handling INVITE transactions.

Retransmission is handled in the stack

(95)

Stack Configuration Parameters – JSIP 1.2

◆

javax.sip.FORKABLE_EVENTS

 Comma separated list of event (package) names

◆

javax.sip.USE_ROUTER_FOR_ALL_URIS (default: true)

 If set to true then all routing decisions pass through the application router

- identitcal to the behavior supported in v1.1

 If set to false the user installed router will only be consulted for routing of

Non-SIP URIs

◆

javax.sip.AUTOMATIC_DIALOG_SUPPORT (default: ON)

 Enable/Disable automatic dialog handling by the stack

(96)

JAIN SIP

(97)

Some RI-Specific Features

◆

JAIN-SIP is a minimal spec. Additional features are often useful

in building SIP network elements

◆

gov.nist.javax.sip.CACHE_SERVER_CONNECTIONS

 Caches incoming TCP connections. If false, server will drop connection

when not in use. If true then server will keep connection alive until client closes it. (default is true)

◆

gov.nist.javax.sip.CACHE_CLIENT_CONNECTIONS

 Caches outgoing client connections. If true then client will keep

connection open after transaction completion

◆

gov.nist.javax.sip.MAX_MESSAGE_SIZE

(98)

Some RI-Specific Features

◆

gov.nist.javax.sip.MAX_CONNECTIONS

 Max number of simultaneous TCP connections

◆

gov.nist.javax.sip.READ_TIMEOUT

 Timeout (ms) between successive TCP reads for message

content/header to prevent DOS attacks

◆

gov.nist.javax.sip.STUN_SERVER

 IP Address and port of the STUN server

◆

gov.nist.javax.sip.THREAD_POOL_SIZE = integer

(99)

Some RI-Specific Features

◆

Logging facilities for trace viewer

 gov.nist.javax.sip.SERVER_LOG = fileName

 gov.nist.javax.sip.LOG_MESSAGE_CONTENT = true|false

 gov.nist.javax.sip.DEBUG_LOG = fileName

◆

gov.nist.javax.sip.REENTRANT_LISTENER = true|

false

 Multiple threads could be active in the listener at the same time

◆

gov.nist.javax.sip.ADDRESS_RESOLVER = classpath

 The AddressResolver allows you to support lookup schemes for

addresses that are not directly resolvable to IP adresses using getHostByName

(100)

Some RI-Specific Features

◆

gov.nist.javax.sip.MAX_SERVER_TRANSACTIONS = integer

 Maximum size of server transaction table. The default is 5000

◆ gov.nist.javax.sip.PASS_INVITE_NON2XX_ACK_TO_LISTENER = true|false

 This is not standard behavior per RFC 3261

 Useful flag for testing. The TCK uses this flag for example.

◆ gov.nist.javax.sip.DELIVER_TERMINATED_EVENT_FOR_ACK = [true|false]

 ACK Server Transaction is a Pseudo-transaction

 If you want termination notification on ACK transactions (so all server

transactions can be handled uniformly in user code during cleanup), then set this flag to true.

(101)

More RI goodies

◆

RI includes a generalized pattern matcher facility

 Match feature not part of JAIN SIP but could be useful for building testers

and such

◆

Each field of a SIP Message can be replaced by a regular

expression

 gov...SIPMessage.match(SIPMessage template) returns true if the

template matches the message

 Is aware of SIP Message header ordering equivalency rules, case

sensitivity rules etc

(102)

More RI Goodies

◆

SIP Transaction aware trace visualization

 Trace logging can be turned on using gov.nist.javax.sip.TRACE_LEVEL

and gov.nist.javax.sip.SERVER_LOG

 Trace visualization tool to view message traces is included with the RI

(103)

Bibliography

◆

Jonathan Rosenberg. “Introduction to CPL”, VoN Developers

conference, Febuary 2001

◆

Mudumbai Ranganathan. “JAIN SIP: A SIP For the People!

Architecture, Implementation, Programming”, May 2004

◆

Xiaotao Wu and Henning Schulzrinne. “LESS effort, more

services”, SIPPING - IETF 62, Minneapolis, March 2005

◆