820-0643 - SIP API Developer's Guide

8/3/2019 820-0643 - SIP API Developer's Guide

1/92

SIP API Developer's Guide

Beta

Part No: 820064312November2010


2/92

Copyright 2007, 2010, Oracleand/or itsafliates. Allrights reserved.

This sotware and related documentation are provided undera license agreement containingrestrictions on use and disclosure and are protected by intellectualproperty laws. Exceptas expresslypermitted in your license agreementor allowed by law, youmay notuse, copy, reproduce, translate, broadcast, modiy, license,transmit,distribute,exhibit,perorm,publish,or display anypart,in anyorm,or by anymeans. Reverse engineering,disassembly,or decompilation o this sotware,unless required by law or interoperability, is prohibited.

Theinormationcontained hereinis subject to changewithout noticeand is notwarranted to be error-ree. I yound anyerrors,please reportthem to us in writing.

Ithis is sotware or related sotware documentation that is deliveredto theU.S. Government or anyonelicensing it on behalo theU.S. Government, theollowingnotice is applicable:

U.S. GOVERNMENT RIGHTS Programs, sotware, databases, and related documentation and technicaldata deliveredto U.S. Governmentcustomers arecommercial computer sotware or commercial technical data pursuant to the applicableFederalAcquisition Regulation and agency-specic supplementalregulations.As such, theuse, duplication,disclosure,modication, andadaptationshallbe subject to therestrictions andlicensetermsset orth in theapplicableGovernment contract,and, to theextent applicable by thetermso theGovernment contract,the additional rightsset orth in FAR 52.227-19,CommercialComputer Sotware License (December 2007).Oracle America, Inc.,500 Oracle Parkway, Redwood City,CA 94065.

This sotware or hardware is developedor general usein a variety o inormation management applications. Itis notdeveloped or intended oruse in anyinherentlydangerousapplications, includingapplications which maycreate a risk o personal injury. I youuse this sotware or hardware in dangerousapplications, then youshall be responsible to take allappropriateail-sae, backup, redundancy, andothermeasuresto ensureits saeuse. OracleCorporationand itsafliatesdisclaimany

liabilityor anydamagescausedby useo this sotware or hardware in dangerousapplications.Oracleand Java areregistered trademarks o Oracleand/or itsafliates. Other names maybe trademarks o their respective owners.

AMD, Opteron, theAMD logo, andthe AMDOpteron logo aretrademarksor registered trademarks o Advanced Micro Devices. Intel andIntelXeonaretrademarks or registeredtrademarks o IntelCorporation. All SPARC trademarksare used underlicense and are trademarksor registered trademarkso SPARCInternational,Inc. UNIX is a registered trademarklicensed through X/Open Company, Ltd.

This sotware or hardware anddocumentation mayprovide accessto or inormation on content, products,and services rom third parties. OracleCorporationanditsafliates arenot responsible orand expresslydisclaimall warranties o anykind with respect to third-party content, products,and services.Oracle Corporationandits afliates will notbe responsible orany loss, costs,or damages incurred dueto your accessto or useo third-party content, products,or services.

110425@25097


3/92

Contents

Preace .....................................................................................................................................................7

1 SIP Overview .........................................................................................................................................11

Introduction to SIP .............................................................................................................................. 11

Overview olibsip ............................................................................................................................. 11

Header Management Layer ........................................................................................................ 12

Transaction Management Layer ................................................................................................ 12

Dialog Management Layer .......................................................................................................... 12

Message Formatting Layer .......................................................................................................... 12

Timer Management Layer .......................................................................................................... 13

Connection Manager ................................................................................................................... 13

2 Oracle Solaris SIP Internals ................................................................................................................15

SIP Stack Initialization ........................................................................................................................ 15

Generic Stack Parameters ........................................................................................................... 15

Upper Layer Registrations .......................................................................................................... 16

Connection Manager Interaces ................................................................................................. 16

Custom Header Table .................................................................................................................. 17

Header Management Layer ................................................................................................................ 17

Writing Parsers For Custom Headers ........................................................................................ 20

Transaction Management Layer ........................................................................................................ 21

Transaction Creation And Maintenance .................................................................................. 21

Transaction Creation and ACK Signal Generation .................................................................... 22

Transaction Deletion ................................................................................................................... 22

Transaction Lookup .................................................................................................................... 22

Transaction Timers ..................................................................................................................... 22Transaction And Network Errors .............................................................................................. 23

3


4/92

Dialog Management Layer ................................................................................................................. 23

UAC Dialog Creation .................................................................................................................. 23

UAS Dialog Creation ................................................................................................................... 24Dialog Caching ............................................................................................................................. 24

Dialog Termination, Deletion, and Notication ...................................................................... 24

Message Formatting Layer ................................................................................................................. 24

Receiving Messages ...................................................................................................................... 25

Sending Messages ......................................................................................................................... 25

Connection Manager .......................................................................................................................... 25

Connection Object ....................................................................................................................... 26

Caching a Connection Object .................................................................................................... 26

Freeing a Connection Object ...................................................................................................... 27

Sending Messages ......................................................................................................................... 27

Receiving Messages ...................................................................................................................... 27

Transaction Layer and I/O Errors .............................................................................................. 28

Timer Management Layer .................................................................................................................. 28Generating Call-ID, From and To tags, Branch-ID and Cseq .......................................................... 28

Multithreading Support ...................................................................................................................... 29

3 Multithreading and URISupport ......................................................................................................31

URI Support ......................................................................................................................................... 31

4 SIP API Functions .................................................................................................................................33

Stack Initialization Function .............................................................................................................. 33

Message Allocation Functions ........................................................................................................... 34

SIP Header Addition Functions ......................................................................................................... 34

SIP Request and Response Creation Functions ............................................................................... 41

Header and Message Copying Functions ......................................................................................... 43Header and Value Deleting Functions .............................................................................................. 44

Header Lookup Functions .................................................................................................................. 45

Value Retrieval and Response Description Functions .................................................................... 45

SIP ID Generating Functions ............................................................................................................. 46

VIA Functions ...................................................................................................................................... 47

SIP Message Sending Function .......................................................................................................... 47

Processing Inbound Messages ........................................................................................................... 48

Contents

SIP API Developer's Guide November 2010(Beta)4


5/92

Transaction Layer Functions ............................................................................................................. 48

Dialog Layer Functions ....................................................................................................................... 50

URI Functions ...................................................................................................................................... 53SIP Header Value Retrieval Functions .............................................................................................. 56

Connection Object Functions ............................................................................................................ 66

Miscellaneous Functions .................................................................................................................... 68

A ExamplesoUse ...................................................................................................................................71

Example o UAS and UAC Use .......................................................................................................... 71

B Programming withtheSIP API .......................................................................................................... 83

Initializing the SIP Stack ..................................................................................................................... 83

Upper Layer Registrations .................................................................................................................. 83

Connection Manager Interaces ........................................................................................................ 85

Custom SIP Headers ........................................................................................................................... 86

C Transaction Timers ..............................................................................................................................89

Index ......................................................................................................................................................91

Contents

5


6/92

6


7/92

Preface

The SIPAPI orSolaris ReerenceGuidecontains a description o the internals o the Oracle

Solaris implementation o the Session Initiation Protocol (SIP). This book includes descriptionsor the unction calls in the API. This book also provides usage examples or the API.

Who Should UseThis Book

This book is meant or use by application developers that are writing SIP applications.

Related Books

Programming InteracesGuide

Documentation, Support, and Training

See the ollowing web sites or additional resources:

Documentation (http://docs.sun.com) Support (http://www.oracle.com/us/support/systems/index.html) Training (http://education.oracle.com) Click the Sun link in the let navigation bar.

Oracle WelcomesYour Comments

Oracle welcomes your comments and suggestions on the quality and useulness o its

documentation. I you nd any errors or have any other suggestions or improvement, go to

http://docs.sun.com and click Feedback. Indicate the title and part number o the

documentation along with the chapter, section, and page number, i available. Please let usknow i you want a reply.

7
http://docs.sun.com/http://docs.sun.com/http://docs.sun.com/http://www.oracle.com/us/support/systems/index.htmlhttp://www.oracle.com/us/support/systems/index.htmlhttp://www.oracle.com/us/support/systems/index.htmlhttp://education.oracle.com/http://education.oracle.com/http://education.oracle.com/http://docs.sun.com/http://docs.sun.com/http://education.oracle.com/http://www.oracle.com/us/support/systems/index.htmlhttp://docs.sun.com/


8/92

Oracle Technology Network (http://www.oracle.com/technetwork/index.html) oers a

range o resources related to Oracle sotware:

Discuss technical problems and solutions on the Discussion Forums(http://forums.oracle.com).

Get hands-on step-by-step tutorials with Oracle By Example (http://www.oracle.com/

technology/obe/start/index.html). Download Sample Code (http://www.oracle.com/technology/sample_code/

index.html).

Typographic Conventions

The ollowing table describes the typographic conventions that are used in this book.

TABLEP1 TypographicConventions

Typeface Meaning Example

AaBbCc123 The names o commands, les, and directories,

and onscreen computer output

Edityour .login le.

Use ls -a to list all les.

machine_name% you have mail.

AaBbCc123 What you type, contrasted with onscreen

computer output

machine_name% su

Password:

aabbcc123 Placeholder:replacewith a realname orvalue The command toremove a le is rm

flename.

AaBbCc123 Book titles, new terms, and terms to be

emphasized

Read Chapter 6 in the User's Guide.

A cache isa copy thatis stored

locally.

Do notsave the le.

Note: Some emphasized items

appear bold online.

Shell Prompts in Command Examples

The ollowing table shows the deault UNIX system prompt and superuser prompt or shells

that are included in the Oracle Solaris OS. Note that the deault system prompt that is displayed

in command examples varies, depending on the Oracle Solaris release.

Preface

http://www.oracle.com/technetwork/index.htmlhttp://www.oracle.com/technetwork/index.htmlhttp://www.oracle.com/technetwork/index.htmlhttp://forums.oracle.com/http://forums.oracle.com/http://forums.oracle.com/http://forums.oracle.com/http://www.oracle.com/technology/obe/start/index.htmlhttp://www.oracle.com/technology/obe/start/index.htmlhttp://www.oracle.com/technology/obe/start/index.htmlhttp://www.oracle.com/technology/obe/start/index.htmlhttp://www.oracle.com/technology/sample_code/index.htmlhttp://www.oracle.com/technology/sample_code/index.htmlhttp://www.oracle.com/technology/sample_code/index.htmlhttp://www.oracle.com/technology/sample_code/index.htmlhttp://www.oracle.com/technology/sample_code/index.htmlhttp://www.oracle.com/technology/sample_code/index.htmlhttp://www.oracle.com/technology/sample_code/index.htmlhttp://www.oracle.com/technology/obe/start/index.htmlhttp://www.oracle.com/technology/obe/start/index.htmlhttp://forums.oracle.com/http://forums.oracle.com/http://www.oracle.com/technetwork/index.html


9/92

TABLEP2 Shell Prompts

Shell Prompt

Bashshell, Korn shell, and Bourne shell $

Bashshell, Korn shell, and Bourne shell or superuser #

C shell machine_name%

C shell or superuser machine_name#

Preface

9


10/92

10


11/92

SIP Overview

This chapter serves as a brie introduction to the Session Initiation Protocol (SIP) and thelibrary that implements this protocol in the Oracle SolarisTM operating system.

Introduction to SIPThe Session Initiation Protocol enables Internet endpoints to negotiate the character o a sharedmultimedia session. SIP is a tool that can create, modiy, and terminate multimedia sessions.SIP works independently o any underlying transport protocols.

Overview olibsipApplications that use SIP must initialize the Oracle Solaris SIP stack by registering certainmandatory and optional unctions. These unctions enable message exchanges and relatedunctionalities between peers. I the application does not register any o the optional unctions,the library uses the built-in equivalent when such an equivalent is available.

The SIP library is multithread-sae. Multiple threads can perorm simultaneous operations onmessage headers. Each message maintains a reerence count. The stack rees a message whenthe reerence count is zero. The library does not protect messages against the case where an

application thread reduces the reerence count to 0. In this case, the stack can delete the messagewhile other threads are using the message.

Note An application cannot initialize the SIP stack more than once. Attempting to initialize analready initialized SIP stack returns an error.

The SIP stack consists o the ollowing operational components: Header management layer

1C H A P T E R 1

11


12/92

Transaction management layer Dialog management layer Message ormatting layer Timer management layer Connection manager

Header Management Layer

The header management layer provides the interaces that are required to build, parse, examineand validate SIP headers.

Transaction Management Layer

SIP is based on a request/response transaction model that is similar to the model that is used byHTTP. A transaction comprises a request that is sent by a client to a server and all o theresponses to that request that are sent back rom the server. The transaction management layerhandles application-level retransmissions, matching responses to requests, andapplication-level timeouts. A User Agent Client (UAC) perorms tasks by using a series otransactions.

Dialog Management Layer

A dialog is a persistent peer-to-peer SIP relationship between two user agents. A dialogacilitates the sequencing o messages and the proper routing o requests between the useragents. The use o dialogs is optional. Dialogs hold state inormation, which can be used toconstruct a request within a session. An application can implement its own dialog managementlayer instead o using the layer that the SIP stack provides. I the stack manages the dialog, itautomatically creates and updates dialogs or incoming and outgoing SIP messages. The stackalso delivers the matching dialog to the application with the incoming message.

Message Formatting LayerThe message ormatting layer constructs a SIP message or an incoming message beoredelivering the message to the application. I the underlying transport protocol is TCP, this layeralso breaks the byte stream at SIP message boundaries. The message ormatting layerdetermines the SIP message boundaries by using the Content-Length header. I a transactionexists, the stack passes the message to the transaction layer or urther processing, then passesthe message to the application. I the dialog management layer is present, the stack passes the

message to the dialog management layer, then passes the message to the application. I neither atransaction nor a dialog management layer are present, the stack passes the message to the

Overview oflibsip



13/92

application directly. For outbound messages, the message ormatting layer adds aContent-Length header that is ollowed by an empty line, meeting the requirements o RFC3261. The stack passes the message to the application's send unction ater passing the message

to the transaction layer and dialog layer, i either is present. The stack sends the SIP message tothe application's send routine ater the stack copies all o the message's headers and contentsinto a contiguous buer.

Timer Management Layer

The SIP stack uses several timers. The timer management layer provides timeout and

un-timeout routines or these timers. The application can implement its owntimeout/un-timeout routines and register them with the stack instead o using the routines thatare provided by the library.

Connection Manager

The connection manager provides input/output unctionality. The connection manager is not apart o the SIP library, but interacts with the library by using well dened interaces. Aconnection is identied by two endpoints, one local and one remote, as well as by the transportprotocol that the connection uses. A connection is represented within the stack by a connectionobject. The stack requires that the rst member o the connection object be a void pointer. Thestack uses this rst member to store data that is related to the connection object. Theapplication must initialize the connection object. The application is responsible or theollowing unctions:

Compliance with RFC 3263 The library expects the application to supply the addresso the next recipient o the SIP message and to handlenetwork errors. The application must ollow theprocedures dened in RFC 3263 or locating SIP servers.

Sent-By and Received parameters Section 18.1.1 o RFC 3261 states that the transport layermust add a sent-by parameter to the topmost VIAheader in every request. The application must includethis inormation when constructing the VIA header. Theapplication must register all values it could use or thesent-by parameter with the stack to enable the stack tovalidate incoming responses as required by section 18.1.2o RFC 3261. Section 18.2.1 o RFC 3261 lists theconditions under which the transport layer must add areceived parameter to the top VIA header o incomingmessages. This received header must indicate the

source o the message. The stack does not add areceived parameter.

Overview oflibsip

Chapter 1 SIP Overview 13


14/92

TTL and maddr parameters The application should add the TTL and maddrparameters in the VIA header when required.

Overview oflibsip



15/92

Oracle Solaris SIP Internals

The ollowing sections describe various components o the stack in detail. The interaces

described in this section are internal to the library unless otherwise specied.

SIP Stack InitializationAn application initializes the stack beore perorming any other tasks. The initialization

parameters can be broadly subdivided into the ollowing our types:

Generic stack parameters Upper layer registrations Connection manager interaces Custom header table

Ater initializing the stack, an application creates requests by using the interaces that are

provided by the header management layer. Applications send requests by using the message

ormatting layer's interace. Applications receive incoming requests and responses ater

initializing the stack and pass the requests and responses to the stack or processing.

Generic Stack Parameters

SIP version SIP_STACK_VERSION denes the SIP stack version.

Stack ags SIP_STACK_DIALOGS instructs the stack to maintain dialogs. I this ag is notset, the stack does not maintain any dialog inormation.

2C H A P T E R 2

15


16/92

Upper Layer Registrations

Upper layer receive routine

The stack uses this unction to deliver SIP messages to the application. Applications mustregister this routine.

Application specic timeout and un-timeout routinesThe application can dene timeout and un-timeout routines or the stack to use.Applications must dene both routines or neither routine. I the application does not denethese routines, the stack uses the built-in timeout routines.

Transactions error notications

The application can register an error notication routine. The stack invokes the errornotication routine when the transaction layer encounters a network error while thetransaction layer is sending a SIP message. I the application does not register an errornotication routine, the stack will not send notications in case o a network error.

Dialog delete noticationI the stack is congured to maintain dialogs, the application can register a callback routine.The stack invokes the callback routine when a dialog is deleted. I the application does not

register a callback routine, the stack will not send notications when a dialog is deleted.Transaction state transition notications

An application can register a routine that is invoked when a transaction changes state. Theroutine is invoked with the transaction handle, the message that resulted in the transition,and the previous and current states. I an application does not register this routine, the stackwill not send notications when a transaction changes state.

Dialog state transition notications

I the stack is congured to maintain dialogs, the application can register a callback routine.The stack invokes the callback routine when a dialog changes state. The callback routine isinvoked with the dialog handle, the message that resulted in the transition, and the previousand current state. I an application does not register this routine, the stack will not sendnotications when a dialog changes state.

Connection Manager Interaces

Applications must register the interaces in this section with the SIP library.

Send routine The stack calls this routine to send SIP messages.

Hold/Release unctions The application must provide unctions to increment anddecrement reerence counts on a connection object.

Connection attributes. The application must register unctions to query the ollowingattributes o a connection object:

is_stream The connection is a byte-stream

SIP Stack Initialization



17/92

is_reliable The connection is reliable

remote address Remote endpoint inormation

local address Local endpoint inormation

transport The transport type

The application can register the ollowing timer attributes that theAPI uses to obtain timer values or a connection object:

Timer1 This value denes the RTT estimate

Timer2 This value denes the maximum retrieval interval ornon-INVITE requests and INVITE responses

Timer4 This value denes the maximum duration that amessage remains in the network

TimerD This value denes the wait time or responseretransmits

I an application does not speciy values or these timer attributes,

the stack uses deault values.

Custom Header Table

An application can register a table o custom headers with the library. The table must includeparsing unctions or those headers. The application can include standard headers in the table.I the application includes standard headers in the custom header table, the stack uses theparsing unctions that are dened in the custom header table instead o the built-in parsingunctions.

Header Management LayerThis layer provides interaces that enable an application to create, parse, modiy, and examine

SIP messages. A SIP message consists o a start line, a variable number o headers, and anoptional message body. The start line and headers are terminated by a single CarriageReturn/Line Feed (CRLF) character. The message body is preceded by an empty line thatcontains only a CRLF. SIP allows the combination o multiple headers o the same name typeunder one header. A single header can have multiple values. A header value consists o anumber o descriptive parameters and an optional name-value pair. The Backus-Naur Form(BNF) or a VIA header is dened in section 24 o RFC 3261 as the ollowing:

Header ManagementLayer

Chapter 2 Oracle Solaris SIP Internals 17


18/92

via = ("Via" / "v") HCOLON via-parm * (COMMA via-parm)via-parm = sent-protocol LWS sent-by *(SEMI via-params)via-params = via-ttl / via-maddr / via-branch / via-received / via-extension

The values ovia-parm are descriptive parameters. The values ovia-params are name-valuepairs. The combination ovia-parm and via-params constitute the value o the header. Thestack maintains a sip_header_name_value_t structure or each SIP header. In the case o aVIA header, the structure is sip_via_value_t. A header can have multiple values separated bya comma. A header with multiple values lists a sip_header_name_value_t structure or eachvalue. For example, a SIP header with multiple VIA headers would list multiplesip_via_value_t structures, with a corresponding via-parm parameter or each structure.

The SIP message contains a list o all the headers and the content. The stack uses the receiveunction that the application registered with the stack to pass the message to the application.

SIP messages implement a reerence count mechanism. An application can hold a reerence to aSIP message by using the sip_hold_msg() unction. An application can release a reerence to aSIP message by using the sip_free_msg() unction. The stack destroys messages whosereerence count drops to zero when the application calls the sip_free_msg() unction.

The stack can orward a SIP message to a SIP entity directly or ater modiying the message. Thestack cannot modiy a message ater sending it.

typedef struct sip_header_general {char *sip_hdr_start;char *sip_hdr_end;char *sip_hdr_current;sip_parsed_header_t *sip_hdr_parsed;

}sip_hdr_general_t;

typedef struct header_function_table {char *header_name;char *header_short_name;int (*header_parse_func)(struct sip_header *,

struct sip_parsed_header **);boolean_t (*header_check_compliance)(struct sip_parsed_header *);boolean_t (*header_is_equal)(struct sip_parsed_header *,

struct sip_parsed_header *);void (*header_free)(struct sip_parsed_header *);

}sip_header_function_t;

The SIP header contains a sip_header_general_t structure that provides pointers to the startand end o the header string. The structure also has a pointer to the current position in thestring that a parser can use when it is processing the header. When the stack parses a header orthe rst time, it caches the result in sip_hdr_parsed or uture reerence.

SIP allows the inclusion o custom message headers that are not dened in RFC 3261. Anapplication can provide a table o custom headers and parsing unctions to support those




19/92

custom headers. The application provides an array, sip_header_function_t, or this purpose.The table entries that the application provides override the header entries that are in the deaultunction table.

The library maintains a table that has an entry or each header that is dened in RFC 3261. Thistable species the header name in long orm, as well as the compact orm where present. Thetable also species the associated parsing unction and any other unctions listed in thesip_header_function_t array.

When the application deletes a header, the value o the sip_header_state attribute is set toSIP_HEADER_DELETED. Existing reerences to the header remain, but new lookups will not

return the deleted header. The library rees all o the message headers at the same time that thelibrary rees the message.

The ollowing structure represents a parsed SIP header:

typedef struct sip_parsed_header {int sip_parsed_header_version;struct sip_value *value;sip_header_t sip_header;

}sip_parsed_header_t;

The member value is a pointer to a sip_header_name_value_t structure. The stack sets thestructure as a result o parsing the SIP header. The rst eld o the sip_header_name_value_tstructure is always a sip_value_t structure. The ollowing code denes the sip_value_tstructure:

typedef struct sip_value {int sip_value_version;void *next;sip_param_t *param_list;sip_value_state_t value_state;sip_parsed_header_t *parsed_header;char *value_start;char *value_end;sip_str_t *sip_value_uri_str;sip_uri_t sip_value_parse_uri;

}sip_value_t;

The values in the param_list array is the list o parameters or the value that the system is

parsing. The ollowing code denes the sip_param_t structure:

typedef struct sip_param {sip_str_t param_name;sip_str_t param_value;struct sip_param *param_next;

}sip_param_t;

typedef struct sip_str {

char *sip_str_ptr;




20/92

int sip_str_len;}sip_str_t;

When the library deletes a value rom a header, the library sets the value o thesip_header_state attribute to SIP_HEADER_DELETED_VAL. The library also sets the value o thevalue_state attribute to SIP_VALUE_DELETED. Existing reerences to the value remain. Newlookups ignore the deleted value.

Traverse the ollowing hierarchy to get to a value rom a SIP message:

sip_msg_t -> sip_header_t -> sip_parsed_header_t -> sip__value_t

Using the ree unction that corresponds to a given structure also rees all o the structures thatare under it in the hierarchy.

The library perorms lazy header parsing. The library only parses or checks or complianceheaders whose values are used by the application. This behavior complies with section 16.3 oRFC 3261, RequestValidationand Reasonable syntax check. When the parser encounters aninvalid value, the parser sets the value_state attribute to SIP_VALUE_BAD.

Writing Parsers For Custom Headers

An application can dene custom headers or specialized versions o standard headers.Applications that dene headers must register parsing unctions with the library to supportthose headers. Use the ollowing structures to write parsing unctions:

sip_header_general_t This structure provides the start and end o a header within amessage. The parser sets the parsed header element to point to the

sip_parsed_header_t structure that the parser allocates.

sip_parsed_header_t The parser allocates and assigns this structure. The parser passesthis structure back to the caller.

sip_value_t The application denes the value o this structure depending onthe header. The rst element o the structure must besip_value_t. The parser creates a linked list o values i multiplevalues exist. The parser sets the value o the value eld in the

parsed header to the rst value. The application must provide anyaccess unction that value members require.



T ti M t L


21/92

Transaction Management LayerThe transaction management layer creates and maintains transaction states or both clients and

servers. The transaction management layer complies with Section 17 o RFC 3261.

The stack maintains a hash table o transactions. The index o this hash table is an MD5 hash.For messages that comply with RFC 3261, the MD5 hash is the hash o the branch ID. Formessages that comply with RFC 2543, the MD5 hash is o a combination o the branch ID,Call-ID, From, To, and Cseq elds. The stack uses the branch ID in the topmost VIA header toidentiy the RFC that a message complies with. Messages that comply with RFC 3261 prextheir branch ID with the string z9hG4bK.

The library initializes the transaction layer as part o the stack initialization. The library alsoinitializes the transaction error and state transition callback unctions i the applicationprovides them.

Transaction Creation And Maintenance

The stack scans the transaction hash table or an existing transaction when the stack receivesincoming requests and responses. I a transaction that matches an incoming response does notexist, the stack handles the transaction statelessly. When an incoming request requires the stackto create a transaction, the application noties the stack o the need to create a transaction whenthe application sends the response. In both cases, the stack passes the message to theapplication. I a request matches a transaction, the stack considers the request a retransmissionand the transaction layer retransmits the last response. The stack drops the incoming requestand does not pass the request to the application. The CANCEL request and an ACK or a non-2xx

response are exceptions to this behavior. A CANCEL request matches the INVITE transactionthat it is cancelling. An ACK or a non-2xx response also matches the INVITE request whoseresponse the ACK is acknowledging. In these two cases, the request is not a retransmission andthe stack sends the request sent to the application. I a response matches a transaction, the stackprocesses the response and stateully passes the message to the application.

The stack only creates a transaction or an outgoing response when the application requests thetransaction creation by using the sip_sendmsg() unction. The stack only creates a transaction

or outgoing requests i the application requests the transaction creation by using thesip_sendmsg() unction. The stack caches the transaction creating message and the lastmessage that was sent on a transaction. This cache acilitates retransmissions and theprocessing o retransmitted requests. The stack initializes timers A, B, D, E, F, G, H, I, J and K ornew transactions. See Appendix A or more inormation about timers.

When a message causes a transaction to change states, the stack invokes a callback unction ithe application registered a callback unction with the stack.





22/92

Transaction Creation andACK Signal Generation

A SIP entity must send an ACK signal or each nal response that the SIP entity receives to an

INVITE request. The procedure or sending the ACK signal depends on the type o response. Fornal responses between 300 and 699, the transaction layer handles the ACK signal processing.For 2xx responses, the application generates the ACK signal. In all cases, the application receivesthe response.

Transaction Deletion

The MD5 hash that is stored in the transaction is used to look up and delete the transactionrom the hash table. When a transaction enters a terminated state, the transaction managementlayer destroys the transaction i the reerence count drops to zero. I the application registered acallback unction during initialization, that callback unction noties the application when thetransaction changes state. I the application needs to use the transaction in the uture, it musthold a reerence to the transaction by using the sip_hold_trans() unction to prevent thestack rom destroying the transaction. Ater using the transaction the application must releasethe reerence by using the sip_release_trans() unction.

The our terminated states or transactions are listed below:

Client invite terminated Client non-invite terminated Server invite terminated Server non-invite terminated

Transaction Lookup

An application can look up a transaction or a SIP message by using the sip_get_trans()unction. A successul lookup returns the transaction and increments the transaction'sreerence count. The application must release the transaction by using thesip_release_trans() unction ater use.

Transaction Timers

The transaction layer maintains a set o timers or timing out transactions or sendingretransmissions. Appendix A lists these timers. I the application initializes timeout reporting,the transaction layer noties the application when a transaction times out.



Dialog ManagementLayer


23/92

Transaction And Network Errors

The transaction layer uses a cached connection object to send messages. In the event o a

network error, the transaction layer releases the connection object and calls the error callbackunction, i the application provided one. I the callback unction not does return a value o 0, ori the application does not provide a callback unction, the stack terminates the transaction andrees the associated resources.

Dialog Management LayerA dialog represents a persistent peer-to-peer relationship between two user agents. A dialogacilitates the sequencing o messages between the user agents and the proper routing orequests between the user agents. The dialog represents a context in which to interpret SIPmessages. A dialog is uniquely identied by a dialog id, which is a combination o the Call-ID,From,and To tags.

Dialog use is optional. You can create dialogs using INVITE and SUBSCRIBE as methods. Aresponse to an INVITE in the 101299 range combined with a To tag creates a dialog. A response

to a SUBSCRIBE in the 200299 range or a NOTIFY request creates a dialog. Provisional responsescreate dialogs that are marked as EARLY dialogs. Final responses in the 200299 range createdialogs that are marked as CONFIRMED dialogs. An EARLY dialog becomes a conrmed dialogwhen the stack receives a response in the 200299 range. I the application registers a callbackunction with the stack to send notication when a dialog changes state, the stack invokes thatunction.

An application can perorm dialog management internally, or delegate dialog management to

the stack. I the stack manages dialogs, the stack automatically creates and maintains dialogs.The stack also delivers any dialogs, matching any incoming messages to the application. I thestack is not managing dialogs, there is no dialog-related interaction between the application andthe stack.

UAC Dialog Creation

For clients, i the stack is congured to maintain dialogs, the stack creates a dialog or anincoming response to a dialog creating request. Dialog creating requests are either INVITE orSUBSCRIBE. For SUBSCRIBE requests, a corresponding NOTIFY request also creates a dialog. Thestack can create multiple dialogs or a single request i the application species multiple dialogsby using the sip_sendmsg() unction.

For servers, i the stack is congured to maintain dialogs, the stack creates a dialog when theapplication sends a response to the dialog creating request. The stack also creates a dialog when

itsends a NOTIFY request in response to a SUBSCRIBE request.

Dialog ManagementLayer


Message Formatting Layer


24/92

UAS Dialog Creation

When the stack receives a dialog creating request, it creates a partial dialog by using the request.

The stack sends the partial dialog to the application along with the request. The stack completesthe dialog when the application sends a response. Because the stack does not insert the partialdialog into a hash table, the stack does not return partial dialogs as results o a lookup. The stackstarts a timer when it creates the partial dialog. The timer's duration is set to the duration o anINVITE transaction timeout. I the UAS does not respond during this time interval, the stackdeletes the partial dialog. I the application registers a callback unction with the stack or dialogdeletion notications, the stack invokes the callback unction beore deleting the partial dialog.The stack also deletes the partial dialog i the response is outside the 100299 range.

Dialog Caching

For an incoming message, the stack sends any existing dialog, along with the message to theapplication. When the application's receive unction returns, the stack decrements the reerencecount to the dialog. I the dialog's reerence count is zero ater this decrement, the stack destroysthe dialog i the dialog is in a terminated state. I the application needs to use the dialog in the

uture, it must hold a reerence to the dialog by using the sip_hold_dialog() unction toprevent the stack rom destroying the dialog Ater using the dialog the application must releasethe reerence by using the sip_release_dialog() unction.

Dialog Termination, Deletion, and Notifcation

When the stack processes a SIP message, the processing can result in the termination o thedialog. A dialog marked as EARLY terminates i the nal response is not in the 200299 range, ori no response arrives. The termination mechanism or conrmed dialogs are method specic.The BYE method terminates an INVITE dialog and the session that is associated with it. Anapplication can explicitly delete a dialog by using the sip_delete_dialog() unction.

When the stack terminates a dialog, it noties the application i the application has registered acallback unction with the stack or this purpose.

Message Formatting LayerThe message ormatting layer represents the message in the orm that the next component orlayer requires.

g g y


Connection Manager


25/92

I the incoming message arrives over TCP, the message ormatting layer breaks the byte streamat message boundaries. The message ormatting layer parses the message in order to representthe message as a SIP message.

When the application is sending a message, the message ormatting layer copies all o themessage's headers and contents into a contiguous buer beore delivering the message to theapplication's send unction.

Receiving Messages

The application sends the incoming message to the stack along with the connection object. Ithe transport is TCP, the message ormatting layer breaks the byte stream at messageboundaries. The SIP message's Content-Length header determines the message boundaries. AContent-Length header must be present in every message delivered over TCP in order tocomply with RFC 3261. I the stack receives a message over TCP that does not contain aContent-Length header, the stack's behavior is unspecied.

The message ormatting layer holds excess data that is not part o the current message or use

with the next packet. When the system closes or reuses a connection, the connection managermust notiy the stack. Ater receiving the notication, the stack rees the data and resources thatthe stack allocated to that connection. The stack delivers the message to the application bycalling the receive unction. The application registers the receive unction with the stack duringstack initialization.

Sending Messages

An application sends a SIP message by using the sip_sendmsg() unction with the connectionobject and any message specic ags. The message ormatting layer adds a Content-Lengthheader and a line that contains only a Carriage Return/Line Feed (CRLF) character to themessage and delivers the packet to the next layer. The message ormatting layer copies all o theSIP message's headers and contents into a contiguous buer beore delivering the message tothe application's send unction. The connection manager provides the send unction.

Connection ManagerThe connection manager provides I/O unctionality. The connection manager is not part o thelibrary but interacts with the stack using well dened interaces. This section describes the usagemodel o the connection manager, its interace with the stack, and the requirements that areimposed by the library. The connection manager must register the ollowing mandatoryinteraces with the stack as part o stack initialization:


Connection Manager


26/92

int sip_conn_send(const sip_conn_object_t, char *, int);void sip_hold_conn_object(sip_conn_object_t);void sip_rel_conn_object(sip_conn_object_t);boolean_t sip_conn_is_reliable(sip_conn_object_t);

boolean_t sip_conn_is_stream(sip_conn_object_t);int sip_conn_remote_address(sip_conn_object_t,

struc sockaddr *, socklen_t *);int sip_conn_local_address(sip_conn_object_t,

struct sockaddr *, socklen_t *);int sip_conn_transport(sip_conn_object_t);

I the application uses timer values that are specic to a connection object, the application mustregister the ollowing interaces to provide those values or Timer 1, Timer 2, Timer 4, andTimer D:

int sip_conn_timer1(sip_conn_object_t);int sip_conn_timer2(sip_conn_object_t);int sip_conn_timer4(sip_conn_object_t);int sip_conn_timerd(sip_conn_object_t);

A connection object represents a connection. A connection is identied by the local endpoint,the remote endpoint, and the transport.

The library requires that the rst element o the connection object is a void pointer. The stackreserves this void pointer or its own use. The application must initialize each connection objectby calling the sip_init_conn_object() unction beore using the object. The connectionobject is opaque to the stack.

Connection Object

When the stack initializes a connection object, the stack sets the rst element o a connectionobject to point to a structure. The structure tracks transactions that cache the connection object.The stack also uses the structure to break a TCP stream at the message boundaries.

Because the library does not interact with listening endpoints, it does not impose any restrictionon creating or maintaining listening endpoints.

The connection manager maintains a unique connection object or each remote address, local

address, and transport tuple. This behavior is particularly important or UDP, where theunderlying endpoint does not uniquely identiy a local/remote endpoint pair.

Caching a Connection Object

The stack caches connection objects or use by the transaction layer. The stack increments thereerence count on the connection object to prevent the connection object rom being reed by

the system when the connection object is in use by the stack. When the transport protocol is


Connection Manager


27/92

TCP, the stack adds a reerence count on the connection object when the stack allocatesresources to break the TCP stream at message boundaries. The connection manager registersthe sip_hold_conn_object() and sip_rel_conn_object() unctions or the purposes o

holding and releasing connection objects.

Freeing a Connection Object

The connection manager can close a connection at any time. The connection manager cannotree the connection object while reerences to the connection object exist. To ree a connectionobject that has existing reerences, the connection manager calls the sip_conn_destroyed()

unction. The library provides this unction. When the connection manager invokes thesip_conn_destroyed() unction, the stack locates and terminates the transactions that arecaching the connection object. The stack rees any resources that had been allocated or TCPhandling ater terminating the transactions.

Sending Messages

When an application sends a message by using the sip_sendmsg() unction, the stack calls thesip_conn_send() unction. The connection manager registers the sip_conn_send() unctionwith the stack. The stack calls the sip_conn_send() unction ater the stack processes theoutbound message. In case o a network error, the application can dene the response o theconnection manager, including returning an error. The connection manager's behavior must beconsistent or all subsequent calls that use the same connection object. The connection managercan create a new connection to update an existing connection. The connection manager mustush any stale TCP data that is let in the connection object as a result o breaking the TCP

stream at message boundaries. The connection manager uses the library unctionsip_clear_stale_data() to ush any stale TCP data. The Connection Manager must notchange the transport type o a connection object.

Receiving Messages

The Connection Manager delivers new packets to the stack by calling thesip_process_new_packet(). Ater processing the message, the stack calls the receive callbackunction to pass the message to the application. The application must register the receivecallback unction with the stack at initialization. The stack rees the message and releases theconnection object when the application's receive unction returns. To queue a message, anapplication must manage the reerence counts on the connection object as described in theCaching Connection Objects section. The application uses the sip_hold_msg() andsip_free_msg() unctions to manage a SIP message's reerence counts.


Timer ManagementLayer


28/92

Transaction Layer and I/O Errors

The transaction layer uses a cached connection object to send messages such as retransmitting

requests or responses. In the event o a network error, the transaction layer releases theconnection object. I the application registered a callback unction or transaction errornotication, the transaction layer invokes that unction. I the application did not register acallback unction or transaction error notication, or i the callback unction returns a nonzerovalue, the stack terminates the transaction. I the callback unction returns a value o zero, thestack does not release the cached object.

Timer Management LayerThe timer management acility mimics the timeout and un-timeout unctionality o the UNIXkernel. A thread maintains a list o timer objects sorted by time. The thread invokes the callbackunction at the interval that the timer species.

The stack initializes the timer layer during stack initialization. Initializing the timer layer startsthe timer thread.

The sip_timeout() unction takes the ollowing arguments:

The callback unction to use The time interval to wait beore invoking the callback unction The argument to pass to the callback unction

The return value o the timeout unction is a timeout identier. The tack can cancel a timeoutby passing the timeout ID o the timeout to cancel to the sip_untimeout() unction

Generating Call-ID, From and To tags, Branch-ID andCseqThe library provides the sip_guid() unction to generate unique identiers or the Call-ID,From,and To tags. The stack generates the identier by combining the upper 32 bits that arereturned by the gethrtime() unction with a 32bit random number rom the /dev/urandom

pseudo-device. The stack randomly replaces numbers in the result with alphabetic characters.The applicatioon is responsible or reeing the string that is returned by the sip_guid()unction.

The library provides the sip_branchid() unction to generate Branch-ID elds. I theapplication invokes the sip_branchid() unction without a SIP message, or i the SIP messagedoes not have a VIA header, the stack orms a Branch-ID eld by using the sip_guid()unction. I the SIP message already has a VIA header, the stack generates the Branch-ID by

using the MD5 hash o the ollowing elds:


MultithreadingSupport


29/92

To tag From tag Call-ID

Request URI Topmost VIA header Sequence number rom the Cseq header

All branch identiers begin with the string z9hG4bK. This behavior complies with RFC 3261.The application is responsible or reeing the string that is returned by the sip_branchid()unction.

An application can use the sip_get_cseq() or sip_get_rseq() unctions to obtain the initialsequence number. The sip_get_cseq() and sip_get_rseq() unctions use the 31 mostsignicant bits o the value that is returned by the time(2) unction call.

Multithreading SupportThe library is completely multithreaded with respect to handling headers and header values.

Multiple application threads can work on the same header o a message. When the stack or theapplication deletes a header or one o the values in a header, the stack marks the header asdeleted. Headers marked as deleted are not available via lookups.

Calling the sip_free_msg() unction to ree a SIP message deletes the message i the reerencecount or the message alls to zero. You can increment the reerence count on a message byusing the sip_hold_msg() unction.



30/92

30


31/92

Multithreading and URI Support

This chapter gives details about the multithreading and URI support eatures o the SIP library.

URI SupportThe library supports all o the URI types that are dened in section 25 o RFC 3261.

The library provides access unctions to obtain a URI rom a SIP header. Other access unctionsobtain various URI components rom the SIP header. To obtain a SIP URI, get the URI valuerom a SIP header, then parse the value into its components by using thesip_get_uri_parsed() unction.

3C H A P T E R 3

31


32/92

32


33/92

SIP API Functions

This section describes the unctions in the SIP API.

Stack Initialization Functionint sip_stack_init(sip_stack_int_t *stack_init);

This unction initializes the SIP stack. This is the stack initialization structure:

typedef struct sip_stack_init_s {int sip_version;uint32_t sip_stack_flags;sip_io_pointers_t *sip_io_pointers;sip_ulp_pointers_t *sip_ulp_pointers;

sip_header_function_t *sip_function_table;}sip_stack_init_t;

The structure has the ollowing elements:

sip_version The value o this variable is equal to the value o theSIP_STACK_VERSION attribute.

sip_stack_flags Set the value o this variable to SIP_STACK_DIALOGS to make the stackmanage dialogs.

sip_io_pointers The values in this eld provide the connection manager interaces.

sip_ulp_pointers The values in this eld contain the upper layer registrations. Upperlayer registrations are unctions that the application must registerwith the stack during initialization.

sip_function_table The values in this eld are the custom headers that the applicationregisters and the parsing unctions that are associated with those

headers. The application can speciy the ollowing elements or eachcustom header:

4C H A P T E R 4

33

Message AllocationFunctions


34/92

header_name

header_short_name (optional) header_parse_func

header_check_compliance (optional) header_is_equal (optional) header_free

Message Allocation Functionssip_msg_t sip_new_msg();

The sip_new_msg() unction allocates and returns a SIP message.

void sip_free_msg(sip_msg_t sip_msg);

The sip_free_msg() unction rees the resources that are associated with a SIP message. Theunction decrements the reerence count. I the decremented reerence count is zero, theunction destroys the SIP message. I the decremented reerence count is not zero, the unctiondoes not destroy the SIP message until the last thread that holds a reerence to the message

releases that reerence.

void sip_hold_msg(sip_msg_t sip_msg);

Threads use the sip_hold_msg() unction to hold a reerence to the SIP message. A SIPmessage persists while the number o reerences to the message is greater than zero.

SIP Header Addition FunctionsAll o the unctions that are described in this section, with the exception o thesip_add_param() unction, take the SIP message as the rst argument. These unctions alsotake header specic attributes as arguments.

int sip_add_header(sip_msg_t sip_msg, char *header_string);

The sip_add_header() unction takes a SIP header string as the second argument and appends

it to the SIP message. This unction creates the SIP header by appending a CRLF to the valueprovided in theheader_stringparameter, then adding it to the end o the SIP message.

sip_header_t sip_add_param(sip_header_t sip_header, char *param, int *error);

The sip_add_param() unction adds the value in theparam parameter to the SIP header in therst argument. The value o theparam parameter cannot be null. The unction returns theheader with the parameter added.


SIP Header Addition Functions


35/92

Note Adding a parameter with this unction creates a new header and marks the previousheader as deleted. Developers working on multi-threaded applications should monitor headers

that are being modied by multiple threads simultaneously.

All o the ollowing header adding unctions add a CRLF to the header beore adding the headerto the SIP message.

int sip_add_from(sip_msg_t sip_msg, char *display_name, char *rom_uri, char*rom_tag, boolean_t add_aquot, char *rom_param);

The sip_add_from() unction appends a FROM header to a SIP message. This unction createsthe header using thedisplay_name,rom_uri androm_tagparameters. The calling thread mustprovide the URI in therom_uriparameter. I the calling thread provides the value o thedisplay_nameparameter, the value o theadd_aquotparameter must be B_TRUE. This value othe add_aquotparameter encloses URI within the delimiting characters < and >.Ithedisplay_nameparameter has a value, this unction quotes that name within " characters andadds the quoted name to the header. I the values in therom_tagparameter are NULL, theresulting SIP header does not contain a TAG parameter. You can speciy any generic parameter

in arom_paramparameter.

Note Only one o the pair o parametersrom_tagorrom_param can have a non-NULLvalue.I both parameters have non-NULLvalues, the resultingFROMheader contains only theTAGparameter.

int sip_add_to(sip_msg_t sip_msg, char *display_name, char *to_uri, char *to_tag,boolean_t add_aquot, char *to_param);

The sip_add_to() unction appends a TO header to a SIP message. This unction creates theheader using thedisplay_name, to_uri and to_tagparameters. The calling thread must providethe URI in the to_uri parameter. I the calling thread provides the value o thedisplay_nameparameter, the value o theadd_aquotparameter must be B_TRUE. This value o the add_aquotparameter encloses the URI within the delimiting characters < and >. I the display_nameparameter has a value, this unction quotes that name within " characters and adds the quoted

name to the header. I the values in the to_tagparameter are NULL, the resulting SIP header doesnot contain a TAG parameter. You can speciy any generic parameter in a to_param parameter.

Note Only one o the pair o parameters to_tagor to_param can have a non-NULLvalue. Iboth parameters have non-NULLvalues, the resultingTO header contains only theTAGparameter.

Chapter 4 SIP API Functions 35



36/92

int sip_add_contact(sip_msg_t sip_msg, char *display_name, char *contact_uri,boolean_t add_aquot, char *contact_param);

The sip_add_contact() unction appends a CONTACT header to a SIP message. This unctioncreates the header using the display_name and contact_uriparameters. The calling thread mustprovide the URI in the contact_uriparameter. I the calling thread provides the value o thedisplay_nameparameter, the value o theadd_aquotparameter must be B_TRUE. This value othe add_aquotparameter encloses the URI within the delimiting characters < and >.Ithedisplay_nameparameter has a value, this unction quotes that name within " characters andadds the quoted name to the header. You can speciy any generic parameter in a contact_paramparameter.

int sip_add_via(sip_msg_t sip_msg, char *protocol_transport, char *sent_by_host, intsent_by_port, char *via_params);

The sip_add_via() unction appends a VIA header to the SIP message that is specied by thevalue o the sip_msgparameter. The VIA header has the transport protocol that is specied intheprotocol_transportparameter. The VIA header has the IP address or hostname that isspecied by the sent_by_hostparameter. The VIA header has the port that is specied in the

sent_by_portparameter. I the sent_by_portparameter has a value o zero, the resulting VIAheader does not have any port inormation. The VIA header's protocol is set to SIP and theversion is set to 2.0. Speciy any header-specic parameters in thevia_paramsparameter. Forexample, you can speciy the branch parameter in thevia_paramsparameter with the string"branch=x9hG4b-mybranchid".

int sip_add_branchid_to_via(sip_msg_t sip_msg, char *branchid);

The sip_add_branchid_to_via() unction adds a branch parameter to the topmost VIA

header in the SIP message. The branch parameter cannot already exist in the VIA header.

Note Adding a parameter with this unction creates a new header and marks the previousheader as deleted. Developers working on multi-threaded applications should monitor headersthat are being modied by multiple threads simultaneously.

int sip_add_maxforward(sip_msg_t sip_msg, uint_t maxorward);

The sip_add_maxforward() unction appends a Max-Forwards header. The value o the headeris equal to the value o the maxorwardparameter.

int sip_add_callid(sip_msg_t sip_msg, char *callid);

The sip_add_callid() unction appends a Call-ID header to the SIP message by using thevalue o the callidparameter. I thecallidparameter has a value oNULL, the sip_add_callid()unction generates a random value or the Call-ID header.




37/92

int sip_add_cseq(sip_msg_t sip_msg, sip_method_t method, uint32_t cseq);

The sip_add_cseq() unction appends a CSeq header using the method and the value ocseqprovided. Themethodcan take on the ollowing values:

INVITE

ACK

OPTIONS

BYE

CANCEL

REGISTER

REFER

INFO SUBSCRIBE

NOTIFY

PRACK

The value o the cseq parameter must be a positive integer.

int sip_add_content_type(sip_msg_t sip_msg, char *, char *);

The sip_add_content_type() unction adds a Content-Type header using the type andsubtype specied in the arguments. The type and subtype cannot be null.

int sip_add_content(sip_msg_t sip_msg, char *contents);

The sip_add_content() unction adds the message body to the SIP message. The value o thecontentsparameter must be a null-terminated string.

int sip_add_accept(sip_msg_t sip_msg, char *type, char *subtype, char *mparams,

char *params);

The sip_add_accept() unction adds an Accept header using the values o the type andsubtypeparameters. I the values o the type and subtype parameters are NULL, the unction addsan emptyAccept header. I the value o the type parameter is not NULL and the value o thesubtype parameter is NULL, the unction adds an Accept header that uses the value o the typeparameter or the header's type value. The value o the subtype parameter or this header is equalto *. You can provide media and acceptparameters by passing them as themparams and

params arguments.int sip_add_accept_enc(sip_msg_t sip_msg, char *code, char *params);

The sip_add_accept_enc() unction adds an Accept-Encoding header with the coding valuethat is specied in the code parameter. You can provide acceptance parameters in theparamsargument.

int sip_add_accept_lang(sip_msg_t sip_msg, char *lang, char *params);




38/92

The sip_add_accept_lang() unction adds an Accept-Language header with the languagethat is specied in the langparameter. You can provide acceptance parameters in theparamsargument.

int sip_add_alert_info(sip_msg_t sip_msg, char *alert, char *params);

The sip_add_alert_info() unction adds an Alert-Info header with the alert parameter thatis specied in the alertparameter. You can provide alert parameters in theparams argument.

int sip_add_allow(sip_msg_t sip_msg, sip_method_t method);

The sip_add_allow() unction adds an ALLOW header with the method that is specied in themethodparameter. These are the valid values or themethodparameter:

INVITE

ACK

OPTIONS

BYE

CANCEL

REGISTER

REFER

INFO SUBSCRIBE

NOTIFY

PRACK

int sip_add_call_info(sip_msg_t sip_msg, char *uri, char *params);

The sip_add_call_info() unction adds a Call-Info header by using the URI passed in thevalue o the uri parameter. You can provide URI parameters in the value o theparams

parameter.

int sip_add_content_disp(sip_msg_t sip_msg, char *dis_type, char *params);

The sip_add_content_disp() unction adds a Content-Disposition header using the displaytype that is given bythe value o the disp_typeparameter. You can provide dispositionparameters in the value o theparams parameter.

int sip_add_content_enc(sip_msg_t sip_msg, char *code);

The sip_add_content_enc() adds a Content-Encoding header using the content encodingthat is given bythe value o the code parameter.

int sip_add_content_lang(sip_msg_t sip_msg, char *lang);

The sip_add_content_lang() adds a Content-Language header using the language that isgiven by the value o the langparameter.

int sip_add_date(sip_msg_tsip_msg

, char*date

);


Th i dd h d i h l i i h d



39/92

The sip_add_date() unction adds a Date header using the value given in the date parameter.This value is a string rom the SIP-Date eld. See section 25.1 o RFC 3261 or moreinormation.

int sip_add_error_info(sip_msg_t sip_msg, char *uri, char *params);

The sip_add_error_info() unction adds an Error-Info header using the value orerror-uri that is specied in the uri parameter. You can provide URI parameters in the valueo theparams parameter.

int sip_add_expires(sip_msg_t sip_msg, int secs);

The sip_add_expires() unction adds an Expires header that uses the number o seconds that

is specied by the value o the secs parameter.

int sip_add_in_reply_to(sip_msg_t sip_msg, char *reply_id);

The sip_add_in_reply_to() unction adds an In-Reply-To header using the value or callidthat is passed by the reply_idparameter.

int sip_add_mime_version(sip_msg_t sip_msg, char *version);

The sip_add_mime_version() unction adds a Mime-Version header using the version numberthat is specied by the value o the version parameter.

int sip_add_min_expires(sip_msg_t sip_msg, int secs);

The sip_add_min_expires() unction adds a Min-Expires header using number o secondsthat is specied by the value o the secs parameter.

int sip_add_org(sip_msg_t sip_msg, char *org);

The sip_add_org() unction adds an Organization header. The header has the value that isspecied in theorgparameter.

int sip_add_priority(sip_msg_t sip_msg, char *prio);

The sip_add_priority() unction adds a Priority header. The header has the value that isspecied in theprio parameter.

int sip_add_reply_to(sip_msg_t sip_msg, char *display_name, char *addr, char

*plist, boolean_t add_aquot);

The sip_add_reply_to() unction appends a REPLY-TO header to a SIP message. This unctioncreates the header using the display_name and addrparameters, in addition to any parametersyou speciy inplist. I the value o the add_aquotparameter is B_TRUE, this unction encloses thevalue o the addrparameter within the delimiting characters < and >.Ithe display_nameparameter has a value, the value o the add_aquotparameter must be B_TRUE.


i t i dd t did( i t ip h *di pl h *u i



40/92

int sip_add_passertedid(sip_msg_t sip_msg, char *display_name, char *uri,boolean_t add_aquot);

The sip_add_passertedid() unction appends a P-ASSERTED-IDENTITY header to a SIPmessage. This unction creates the header using thedisplay_name and uri parameters. Theuricannot have a null value. I the value o the add_aquotparameter is B_TRUE, this unctionencloses the value o the uri parameter within the delimiting characters < and >. I thedisplay_nameparameter has a value, the value o the add_aquotparameter must be B_TRUE.

int sip_add_ppreferredid(sip_msg_t sip_msg, char *display_name, char *uri,boolean_t add_aquot);

The sip_add_ppreferredid() unction appends a P-PREFERRED-IDENTITY header to a SIPmessage. This unction creates the header using thedisplay_name and uri parameters. Theuricannot have a null value. I the value o the add_aquotparameter is B_TRUE, this unctionencloses the value o the uri parameter within the delimiting characters < and >.

int sip_add_require(sip_msg_t sip_msg, char *req);

The sip_add_require() unction adds a Require header by using the value ooption-tag thatis specied in the req parameter.

int sip_add_retry_after(sip_msg_t sip_msg, int secs, char *cmt, char *params);

The sip_add_retry_after() unction adds a Retry-After header with a value equal to thenumber o seconds that is specied by the value o the secs parameter. You can provide retryparameters in the value o theparams parameter. You can provide comments in the value o thecmtparameter.

int sip_add_route(sip_msg_t sip_msg, char *display_name, char *route_uri, char

*route_param);

The sip_add_route() unction appends a ROUTE header to a SIP message. This unction createsthe header using thedisplay_name and route_uriparameters, in addition to any parameters thatyou speciy in route_param. This unction encloses the value o the route_uriparameter withinthe delimiting characters < and > beore adding that value to the header.

int sip_add_record_route(sip_msg_t sip_msg, char *display_name, char *route_uri,char *route_param);

The sip_add_record_route() unction appends a RECORD-ROUTE header to a SIP message.This unction creates the header using thedisplay_name and route_uriparameters, in additionto any parameters that you speciy in route_param. This unction encloses the value o theroute_uriparameter within the delimiting characters < and > beore adding that value to theheader.

int sip_add_server(sip_msg_t sip_msg, char *svr_val);


The sip add server() unction adds a Server header by using the value o server val that is

SIP Request and ResponseCreation Functions


41/92

The sip_add_server() unction adds a Server header by using the value oserver-val that isgiven by the svr_val parameter.

int sip_add_subject(sip_msg_t sip_msg, char *subject);

The sip_add_subject() unction adds a Subject header with the value given in the subjectparameter.

int sip_add_supported(sip_msg_t sip_msg, char *support);

The sip_add_supported() unction adds a Supported header with the value ooption-tagthat is given in the supportparameter.

int sip_add_tstamp(sip_msg_t sip_msg, char *time, char *delay);

The sip_add_tstamp() unction adds a Timestamp header using the timestamp value that isgiven in the time parameter. I the value o the delay is not NULL, this unction adds the delayvalue given in the *delay parameter.

int sip_add_unsupported(sip_msg_t sip_msg, char *unsupport);

The sip_add_unsupported() unction adds an Unsupported header using the value or

option-tag that is specied by the unsupportparameter.int sip_add_user_agent(sip_msg_t sip_msg, char *usr);

The sip_add_user_agent() unction adds a User-Agent header using the value orserver-val that is specied by the usrparameter.

int sip_add_warning(sip_msg_t sip_msg, int code, char *addr, char *msg);

The sip_add_warning() unction adds a Warning header using the warning code that isspecied by the value o the code parameter. The unction uses the warning agent that isspecied by the value o the addrparameter. The unction uses the warning text that is speciedbythe value o the msgparameter.

SIP Request and Response Creation Functions

int sip_add_response_line(sip_msg_t sip_response, int response, char*response_code);

The sip_add_response_line() unction adds a response line that uses the values that arepassed in the response and response_codeparameters. The response_codeparameter is thereason phrase or the response. The value o the response_codeparameter cannot be NULL. TheSIP version in the response line is SIP/2.0. The sip_add_request_line() unction adds a CRLF


to the response line beore adding the line to the SIP message For the response listed in Section

SIP Request and ResponseCreation Functions


42/92

to the response line beore adding the line to the SIP message. For the response listed in Section21 o RFC 3261, obtain the value o the response_codeparameter by using thesip_get_resp_desc() unction.

int sip_add_request_line(sip_msg_t sip_request, sip_method_t method, char*request_uri);

The sip_add_request_line() unction adds a request line to a SIP message using the methodand the request URI. The request URI cannot be NULL.The method can take on the ollowing

values:

INVITE

ACK

OPTIONS

BYE

CANCEL

REGISTER

REFER

INFO

SUBSCRIBE

NOTIFY

PRACK

The added request line has a SIP version o SIP/2.0. The API adds a CRLF to the request linebeore adding the line to the SIP message.

sip_msg_t sip_create_response(sip_msg_t sip_request, int response, char*response_code, char *totag, char *contacturi);

The sip_create_response() unction creates a response or the SIP request that is provided bythe sip_requestparameter. The response and *response_codeparameters serve the same purposeas in the sip_add_response_line() unction. You can speciy a tag value that thesip_create_response() unction adds to the TO header. I you do not speciy the tag value, thisunction adds a tag value unless the response is 100 (Trying). In this case, the application mustspecically add the tag. The SIP response message is created by adding a Response line by usingthe response and *response_codeparameters with a SIP version o SIP/2.0. This unction thencopies the ollowing headers rom the request to the response message:

All VIA headers FROM header TO header Call-ID header Cseq header All Record-Route headers

The sip_create_response() unction returns the resulting SIP response message.


sip msg t sip create dialog req(sip method t method, sip dialog t dialog, char

Header and Message Copying Functions


43/92

p_ g_ p_ _ g_ q( p_ _ , p_ g_ g,*transport, char *sent_by, int sent_by_port, char *via_param, uint32_t maxorward,int cseq);

The sip_create_dialog_req() unction creates an in-dialog request using the state that ismaintained in thedialogparameter. This unction uses the method that is specied in themethodparameter to create the request line. The request URI is either the contact URI rom thespecied dialog or the rst URI rom the Route set, i that set is present. For more details on theRoute set, see section 12.2 o RFC 3261. The FROM, TO, CONTACT and Call-ID headers are addedto the request using the state that is maintained in the dialog. The Max-Forwards header isadded using the value o the maxorwardparameter. I the value o the cseq parameter is notnegative, this unction adds the Cseq header using the provided value. In all other cases, thisunction increments the dialog's local cseq and uses the result as the sequence number.

This unction adds a VIA header to the request. This unction constructs the VIA header byusing the values in the transport, sent_by,and sent_by_portparameters, as well as any valuesyou speciy in the via_paramsparameter. The VIA header's protocol is SIP and the versionnumber is 2.0.

int sip_create_OKack(sip_msg_t response, sip_msg_t ack_msg, char *transport, char

*sent_by, int sent_by_port, char *via_params);

The sip_create_OKack() unction constructs an ACK signal or a nal 2xx response, incompliance with section 13.2.2.4 o RC 3261. The value o the response parameter is the 2xxresponse.

This unction adds a VIA header to the request. This unction constructs the VIA header byusing the values in the transport, sent_by,and sent_by_portparameters, as well as any valuesyou speciy in the via_paramsparameter. The VIA header's protocol is SIP and the versionnumber is 2.0.

Header and Message Copying Functionsint sip_copy_start_line(sip_msg_t rom, sip_msg_t to);

The sip_copy_start_line() unction copies the rst line o the SIP message. The rst line is

either the request or the response line. The line is copied rom the position that is indicated bythe value omsg_from to the position that is indicated by the value omsg_to.

int sip_copy_header(sip_msg_t sip_msg, sip_header_t sip_header, char *param);

The sip_copy_header() unction creates a new SIP header using the values given by thesip_headerandparam parameters, i the values or these parameters are not NULL. Thisunction adds the new header to the message that is indicated by the value o the sip_msg

parameter.


int sip_copy_header_by_name(sip_msg_t rom, sip_msg_t to, char *header_name,

Header andValue Deleting Functions


44/92

char *param);

The sip_copy_header_by_name() unction copies the header given by the value o theheader_name parameter rom the position specied in msg_from to the position specied inmsg_to. The value o the header_nameparameter can be either the long name or the compactname. The unction creates a new SIP header using the contents o the header_name eld inmsg_from, then adds the value o theparam parameter i that value is not NULL. The unctionadds the resulting header to msg_to.

int sip_copy_all_headers(sip_msg_t rom, sip_msg_t to);

The sip_copy_all_headers() unction copies all o the headers, except or the start line, romthe SIP message indicated in therom parameter to the SIP message indicated in the toparameter. The API will not copy headers rom a message that is marked as deleted.

sip_msg_t sip_clone_msg(const sip_msg_t sip_msg);

The sip_clone_msg() unction returns a message that is a copy o the SIP message that isindicated by the value o the sip_msgparameter. The unction returns a message that containsall o the headers and the contents that are present in the SIP message that is indicated by the

value o the sip_msgparameter.

Header andValue Deleting Functionsvoid sip_delete_start_line(sip_msg_t sip_msg);

The sip_delete_start_line() unction deletes the start line rom the SIP message that is

indicated by the value o the sip_msgparameter. The start line can be either the request line orthe response line.

int sip_delete_header(sip_header_t sip_header);

The sip_delete_header() unction deletes the header that is indicated by the value o thesip_headerparameter rom its associated SIP message. The unction marks that header asdeleted. The stack destroys that header when the SIP message is destroyed.

int sip_delete_header_by_name(sip_msg_t sip_msg, char *header_name);

The sip_delete_header_by_name() unction deletes the header that is specied by the value othe header_nameparameter rom the SIP message that is indicated by the value o the sip_msgparameter. The value o theheader_nameparameter can be either the long name or thecompact name or the SIP header. This unction marks the header as deleted. The stack destroysthis header when it destroys the SIP message.

int sip_delete_value(sip_header_t header, sip_header_value_t value);


The sip_delete_value() unction deletes the value that is specied by the sip_valueparameter

Value Retrievaland ResponseDescription Functions


45/92

rom the header that is specied by the sip_headerparameter. The stack marks the value asdeleted and destroys the value when it destroys the header.

Header

Documents

820-0643 - SIP API Developer's Guide