Developing SIP services

Developing SIP services Nicolas Palix INRIA Phoenix - LaBRI palix@labri.fr http://phoenix.labri.fr/ C c b s r http://creativecommons.org/licenses/by/3.0/

CPL, LESS and CCXML XML Technologies for telephony services Nicolas Palix INRIA Phoenix - LaBRI palix@labri.fr http://phoenix.labri.fr/ Developing SIP services C c b s r http://creativecommons.org/licenses/by/3.0/

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 3

CPL 4

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» Decouple service from signaling protocol Assurances on safety 5

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 Define an XML based Call Processing Language (CPL) 6

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) Fast operation 7

History of CPL Concept originated as end user uploading of service logic in SIP REGISTER JDR and HGS, 1997 CPL specification First draft April 1999 Submitted for consideration as RFC Dec. 2000 Proposed as one of main work items for new IP Telephony (iptel) working group when it was formed in Nov 1997 RFC 3880 Implementations First one by JDR, mid 1999 at Bell Labs Jonathan Lennox, Columbia U. took role as primary driver and author Framework and Requirements done first RFC2824 issued May 2000 Second by dynamicsoft Numerous ones exist or are in progress now» Indigo Software» Ubiquity» Netcentrex» SER» OpenSER» Vovida 8

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? Call routing services Call screening services Call logging services 9

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 REGISTER sip:sip.example.com SIP/2.0 From: Joe User <sip:joe@example.com> To: "J. User" <sip:joe@example.com> CSeq: 18 REGISTER Expires: 1800 Call-ID: 39485832@joespc.example.com Contact: sip:joe@joespc.example.com 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> Accept header Accept-Disposition header Download active CPL script 10

CPL Lifecycle CPL Execution starts on arrival of INVITE message at a proxy INV INV Governs operation of proxy for INVITE transaction ONLY 300 ACK INV When final response is sent, CPL execution terminates Does not stay in the call 600 600 ACK This is why CPL is good at pre-call services like routing and screening CPL Lifecycle Proxy UA1 UA2 11

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 CPLs for caller CPLs for caller CPLs for called user 12

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 Subaction» can be used by either incoming or outgoing 13

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 zero or one outgoing <?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> <incoming> SOME STUFF HERE </incoming> <outgoing> SOME STUFF HERE </outgoing> </cpl> 14

Mapping Trees to CPLs success proxy lookup Reject failure What is the date? Monday otherwise Redirect <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> 15

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 proxy, redirect 16

Available node tags Signaling Actions proxy redirect reject Decisions address-switch Location modifiers location lookup remove-location Subroutine calls sub string-switch time-switch priority-switch Other actions mail log 17

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» first-only <proxy recurse= yes > <busy> <reject/> </busy> <noanswer> <reject/> </noanswer> </proxy> 18

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 Contacts from 3xx are adding to implicit global location list List is always kept in sorted order based on q value 19

Redirect tag Node Redirects to the current locations Placed in Contact headers OK if there are no locations No outputs allowed CPL processing terminates <location url= sip:foo@bar > <redirect/> </location> Single attribute: permanent yes or no Indicates whether redirection is a permanent or temporary For SIP, 301 or 302 response 20

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 Optional: reason <reject status= busy /> 21

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> 22

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 tel (defined if it s a tel URL, or a sip URL with a telephone number) display 23

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 a prefix 24

Address-Switch Examples Matching address tags example Assume the request contains INVITE sip:ruser@rdomain.com SIP/2.0 From: FDisplay <sip:fuser@fdomain.com> To: TDisplay <sip:tuser@tdomain.com> <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> 25

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 Didn t work for H.323 26

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:sales@foo.com > <proxy/> </location> </string> <string contains= marketing > <location url= sip:marketing@foo.com > <proxy/> </location> </string> <otherwise> <location url= sip:random@foo.com > <proxy/> </location> </otherwise> </string-switch> 27

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» Accept language has parameters, commas, etc. 28

Language-Switch Allows call dispatch Subtags are language tags Language tag Mandatory matches attribute Conventional values <language-switch> <language matches= FR > <location url= sip:operator@fr.foo.com > <proxy/> </location> </language> <language matches= US > <location url= sip:operator@us.foo.com > <proxy/> </location> </language> </language-switch> 29

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:new@foo.com > <proxy/> </location> </priority> <priority less= normal > <location url= sip:whocares@foo.com > <proxy/> </location> </priority> <priority greater= urgent > <location url= sip:emergency@foo.com > <proxy/> </location> </priority> </priority-switch> 30

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 Every third Tuesday in February and March First Monday of the month etc. 31

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 name names are things like EST, CET and CST 32

Time tags Time tags contain many attributes that define repeating events Basic event description dtstart: event start date and time dtend: event end time Limiting repetitions until: date/time when repetitions end Defining exceptions byday» List of days of the week duration: instead of dtend Defining repetitions through periodicity freq: frequency of occurrence bymonthday» List of days of the month byyearday» List of days of the year» daily, weekly, monthly, yearly interval: how often recurrence repeats byweekno» List of weeks of the year bymonth» List of months of the year 33

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 Example: freq= daily byday= MO,WE defines only Mondays and Wednesdays 34

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 > <time dtstart="20000703t090000" duration="8h" freq="weekly" byday="mo,tu,we,th,fr"> <location url= sip:work@foo.com > <proxy/> </location> </time> <time dtstart= 20000703T170000 dtend= 20000703T210000 freq= weekly byday= MO,TU,WE,TH,FR > <location url= sip:home-eve@foo.com > <proxy/> </location> </time> <time dtstart= 20000703T000000 duration= 24H freq= weekly byday= SA,SU > <reject status= reject reason= it s the weekend /> </time> </time-switch> 35

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 <location url= sip:foo@bar > <redirect/> </location> <lookup source= registration > <success> <proxy/> </success> </lookup> 36

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 URL pattern to match 37

Example Parameter filtering sip:user@foo;mobility= fixed sip:joe@bar;feature= voicemail <remove-location field= mobility,feature value= mobile,voicemail > sip:user@foo;mobility= fixed 38

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 Ampersand must be with an entity! <mail url= mailto:user@host?subject=foo &body=hello%20there > 39

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 <log comment= rejected call > 40

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:vmail@foo.com > <proxy/> </location> </subaction> <incoming> <lookup source= registration > <success> <proxy> <default> <sub ref= vmail /> </default> </proxy> </success> <notfound> <sub ref= vmail /> </notfound> </lookup> </incoming> 41

Default Actions What happens if a script reaches a point where there are no more tags? locations or lookups performed, no signaling 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 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 upstream Proxy to location set 42

Other technologies 43

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 44

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 New switching actions: status, event, physical location 45

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 context from a queue Midcall:transfer: transfer a call 46

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» 3GPP Media Resource Function (MRF) VoiceXML or other dialog systems could be integrated with other call control systems 47

CCXML and VoiceXML System Architecture 48

CCXML Concepts Session : executing CCXML document(s) Connection : call legs Conference Dialog : interact with connections and conferences Functionalities Variables Loops XML Schema definition 49

JAIN SIP API Nicolas Palix INRIA Phoenix - LaBRI palix@labri.fr http://phoenix.labri.fr/ Developing SIP services C c b s r http://creativecommons.org/licenses/by/3.0/

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 JAIN Megaco JAIN SDP 51

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 Mudumbai Ranganathan Computer Scientist National Institute of Standards and Technology (NIST) 52

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/ https://jain-sip-presence-proxy.dev.java.net/ https://jain-sip-applet-phone.dev.java.net/ 53

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 54

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 server) is about 3500 LOC 55

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 Simple Messaging and Presence are almost there 56

JAIN SIP A Event-Layer Abstraction Application which handles JAIN events JAIN SIP API Protocol Stack with Proprietary primitives 57

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 RFC 3311, 3326, 3428, 3515, 3581 58

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 (PUBLISH/SUBSCRIBE/NOTIFY) 59

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) RFC 3581 for NAT traversal (rport parameter for Via header) 60

Architecture 61

JAIN SIP 1.2 Messaging Architecture Application Application Listener Listener SIP messages SIP events Provider Provider Listening Point Point Stack Provider Provider Listening Point Point Stack Network 62

Generic SIP Application Structure SipProvider SipStack Events Messages Dialog Dialog Application (SipListener) Events Messages Transaction Transaction Transaction Events Messages Rq Rp Rq Rq Rp Parser Encoder Network (Raw Bytes) 63

JAIN SIP Object Architecture 1. Create SIPListener instance 2. getinstance() Setup Function Listener SIP Factory 6. add SIP Listener Listening Point Point 4. create Listening Point Provider Stack Proprietary stack Network 5. create SIP Provider 3. create SIP Stack Proprietary stack 64

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 Application receives messages from the stack as events via the SipListener interface 65

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 behalf on a user application 66

Code patterns 67

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); } } 68

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 69

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); } 70

Application - Sending Requests Send outgoing messages try { } // Create the client transaction ClientTransaction invitetid = sipprovider.getnewclienttransaction(request); // send the request sipprovider.sendrequest(invitetid,request); 71

When going deeper... 72

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 given application JAIN-SIP maintains an one-to-one mapping from SIP Messages to transactions 73

SIP Transactions SIP transaction consists of a single request and any responses to that request Server transaction Client transaction Server transaction Client transaction UAC Transaction stateful proxy UAS 74

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 The JAIN SIP implementation manages the association between Transactions and Dialogs 75

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 previously created ClientTransaction with the response and passes up to the Application 76

INVITE Server Transaction State Machine RFC 3261 Ch 17 INVITE send response Proceeding Pass INVITE to TU 101-199 from TU 300-699 from TU INVITE send response Completed ACK Timer G fires Send response 300-699 ACK sent Confirmed Timer I Timer I TU SIP Listener State Machine JAIN SIP Terminated Transport error 2xx from TU 77

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 Transaction (handled Statefully) within the Dialog 78

Generic SIP Application Structure SipProvider SipStack Events Messages Dialog Dialog Application (SipListener) Events Messages Transaction Transaction Transaction Events Messages Rq Rp Rq Rq Rp Parser Encoder Network (Raw Bytes) 79

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 Transactions may belong to a Dialog Dialog state changes as a result of changes in Transaction State 80

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 underlying transaction that creates/terminates the Dialog 81

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(); Returns null for a transaction that cannot map to a dialog 82

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); 83

Implementation Tips in a Stateful Server Application Data Incoming dialog (call leg) Outgoing dialog (call leg) Outgoing dialog (call leg) INVITE INVITE INVITE When all dialogs referencing the Application Data go away, so does the application data When an event comes in for one of the Dialogs, you can get all the other ones 84

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 Messages for the benefit of proxies 85

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 New Dialog Creating methods specified at Stack configuration 86

Interfaces 87

JAIN SIP Object Architecture 1. Create SIPListener instance 2. getinstance() Setup Function Listener SIP Factory 6. add SIP Listener Listening Point Point 4. create Listening Point Provider Stack Proprietary stack Network 5. create SIP Provider 3. create SIP Stack Proprietary stack 88

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 configuration properties 89

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 Only one provider per listening point 90

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 Process terminated transaction Process terminated dialog 91

Configuration 92

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 Is passed un-interpreted to the Router class 93

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 Retransmissions are handled on a server transaction basis 94

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 Useful for construction of simple user agent vs complex server 95

JAIN SIP Reference Implementation 96

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 Maximum size of incoming TCP messages. Allows servers to guard against DOS attacks. 97

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 Concurrency control for number of simultaneous active threads 98

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 99

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. 100

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 Match complexity depends upon Reg-exp complexity 101

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 (useful for protocol debugging) 102

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 and official website resources of CCXML VoiceXML Acknowledgment to Laurent Réveillère for his course template