<title>Application Writing</title>
	    <application moreinfo="none">ser</application> offers several
	    ways to couple its functionality with applications. The coupling
	    is bidirectional: <application moreinfo="none">ser</application>
	    can utilize external applications and external applications can
	    utilize <application moreinfo="none">ser</application>. 
	    An example of the former direction would be an external program
	    determining a least-cost route for a called destination  using 
	    a pricing table. An example of the latter case
	    is a web application for server provisioning.
	    Such an application may want to send instant 
	    messages, query all current user's locations and monitor server
	    health. An existing web interface to <application moreinfo="none">ser</application>,
	    <application moreinfo="none">serweb</application>, actually
	    does all of it. 
	    The easiest, language-independent way of using external logic 
	    from <application moreinfo="none">ser</application> is provided
	    by exec module. exec module allows <application moreinfo="none">ser</application>
	    to start external programs on receipt of a request. The
	    programs can execute arbitrary logic and/or affect routing of SIP
	    requests. A great benefit of this programming method is it
	    is language-independent. Programmers may use programming languages
	    that are effective or with which they are best familiar.
	    <xref linkend="usingexec"> gives additional examples illustrating 
	    use of the exec module.
	    Another method for extending <application moreinfo="none">ser</application>
	    capabilities is to write new modules in C. This method takes
	    deeper understanding of <application moreinfo="none">ser</application>
	    internals but gains the highest flexibility. Modules can implement
	    arbitrary brand-new commands upon which <application moreinfo="none">ser</application>
	    scripts can rely on. Guidelines on module programming can be
	    found in <application moreinfo="none">ser</application>
	    programmer's handbook available from iptel.org website.
	    To address needs of applications wishing to leverage
	    <application moreinfo="none">ser</application>,
	    <application moreinfo="none">ser</application> exports
	    parts of its functionality via its built-in
	    "Application FIFO server". This is a simple textual
	    interface that allows any external applications
	    to communicate with the server. It can be used to
	    send instant messages, manipulate user contacts,
	    watch server health, etc. Programs written in any
	    language (PHP, shell scripts, Perl, C, etc.) can
	    utilize this feature. How to use it is shown in
	    <xref linkend="fifoserver">.

	<section id="usingexec">
	    <title>Using exec Module</title>
		The easiest way is to couple <application moreinfo="none">ser</application>
		with external applications via the <emphasis>exec</emphasis>
		module. This module allows execution of logic and URI manipulation 
		by external applications on request receipt. While very
		simple, many useful services can be
		implemented this way. External applications can be written in
		any programming language and do not be aware of SIP at all.
		<application moreinfo="none">ser</application> interacts with
		the application via standard input/output and environment 


		For example, an external shell script
		may send an email whenever a request for a user arrives.

		<title>Using exec: Step 1</title>
		<programlisting format="linespecific">
# send email if a request for user "jiri" arrives
if (uri=~"^sip:jiri@") {
     exec_msg("echo 'body: call arrived'|mail -s 'call for you' jiri");
	    </example> <!-- step 1 -->
		In this example, the <command moreinfo="none">exec_msg</command> 
		action starts an external shell. It passes a received SIP request
		to shell's input. In the shell, <command>mail</command> command
		is called to send a notification by e-mail.
		The script however features several simplifications:
		<orderedlist inheritnum="ignore" continuation="restarts">
			    The email notification does not tell who was calling.
			    The logic is not general: it only supports one well-known user (jiri).
			    The logic is stateless. It will be executed on
			    every retransmission.
			    It is a script fragment not explaining the 
			    context. This particular example may be for
			    example used to report on missed calls.
		All of these simplifications are addressed step-by-step
		in the following examples.
	    <example> <!-- step 2: who called me -->
		<title>Using exec: Step 2, Who Called Me</title>
		    This example shows how to display caller's address
		    in email notification. The trick is easy: process
		    request received on shell programm's input
		    and grep From header field.
		<programlisting format="linespecific">
			The following two figures show an example SIP request and
			email notification generated on its receipt.
		    <screen format="linespecific">

INVITE sip:jiri@iptel.org SIP/2.0
Via: SIP/2.0/UDP
Max-Forwards: 10
From: "alice" <sip:alice@iptel.org>;tag=76ff7a07-c091-4192-84a0-d56e91fe104f
To: <sip:jiri@iptel.org>
Call-ID: d10815e0-bf17-4afa-8412-d9130a793d96@
Contact: <sip:>
Content-Type: application/sdp
Content-Length: 451

--- SDP payload snipped ---

		    email received:
			<screen format="linespecific">
Date: Thu, 12 Dec 2002 14:25:02 +0100
From: root <root@cat.iptel.org>
To: jiri@cat.iptel.org
Subject: request for you

From: "alice" <sip:alice@iptel.org>;tag=76ff7a07-c091-4192-84a0-d56e91fe104f
request received
		    There is another way to learn values of request
		    header fields, simpler than use of <command moreinfo="none">grep</command>. 
		    <application moreinfo="none">ser</application>
		    parses header fields and passes their values in 
		    environment variables. Their names correspond
		    to header field names prefixed with "SIP_HF_".
		<programlisting format="linespecific">
# send email if a request for "jiri" arrives
if (uri=~"^sip:jiri@") {
     exec_msg("echo request received from $SIP_HF_FROM | mail -s 'request for you' jiri");
		    Moreover, several other values are passed in environment
		    variables. <varname>SIP_TID</varname> is a token uniquely identifying 
		    transaction, to which the request belongs. <varname>SIP_DID</varname>
		    includes to-tag, and is empty in requests creating a dialog.
		    <varname>SIP_SRCIP</varname> includes IP address, from which the
		    request was sent. <varname>SIP_RURI</varname> and <varname>SIP_ORURI</varname>
		    include current request-uri and original request-uri respectively,
		    <varname>SIP_USER</varname> and <varname>SIP_OUSER</varname> username
		    parts of these. The following listing shows environment variables
		    passed to a shell script on receipt of the previous message:
		    <programlisting format="linespecific">
SIP_HF_FROM="alice" <sip:alice@iptel.org>;tag=76ff7a07-c091-4192-84a0-d56e91fe104f
	    </example> <!-- step 2, who called me -->

	    <example>  <!-- step 3,  make the script work for anyone -->
		<title>Using exec: step 3, Make The Script Work For Anyone</title>
		    A drawback of the previous example is it works only
		    for one well-known user: request URI is matched against
		    his SIP address and notification is sent to his hard-wired email
		    address. In real scenarios, one would like
		    to enable such a service for all users without enumerating
		    their addresses in the script. The missing piece
		    is translation of user's SIP name to his email address.
		    This information is maintained in subscriber profiles,
		    stored in MySQL by <application moreinfo="none">ser</application>.
		    To translate the username to email address, the executed script
		    needs to query the MySQL database. That is what this example
		    shows. First, an SQL query is constructed which looks up
		    email address of user, for whom a request arrived. If the
		    query does not return a valid email address, the script
		    returns with an error status and <application moreinfo="none">ser</application>
		    script replies with "user does not exist". Otherwise
		    an email notification is sent.
		    <programlisting format="linespecific">
	    </example> <!-- step 3 make the script work for anyone -->
	    <example> <!-- step 4, stateful processing -->
		<title>Adding Stateful Processing</title>
		    The previously improved example still features a shortcoming.
		    When a message retransmission arrives due to a nework
		    mistake such as lost reply, the email notification is
		    executed again and again. That happens because the script
		    is stateless, i.e., no track of current transactions is
		    kept. The script does not know whether a request is
		    a new or a retransmitted one. Transaction management may
		    be introduced by use of tm module as described in
		    <xref linkend="statefulua">. In the script,
		    <command moreinfo="none">t_newtran</command> is first
		    called to absorb requests retransmission -- if they
		    occur, script does not continue. Then, as in the previous
		    example, an exec module action is called. Eventually,
		    a reply is sent statefully.
			    Note carefuly: it is important that the stateful
			    reply processing (<command moreinfo="none">t_reply</command>)
			    is used as opposed to using stateless replies
			    (<command moreinfo="none">sl_send_reply</command>).
			    Otherwise, the outgoing reply would not affect
			    transactional context and would not be resent on
			    receipt of a request retransmission.
		    <programlisting format="linespecific">
	    </example> <!-- step 4,  stateful processing -->
	    <example> <!-- step 5, full exec use -->
		<title>Full Example of exec Use</title>
		    The last example iteration shows how to integrate the
		    email notification on missed calls with the default
		    <application moreinfo="none">ser</application> script
		    (see <xref linkend="defaultscript">). It generates an
		    email for every call invitation to an off-line user.
		    <programlisting format="linespecific">
		    Production "missed calls" services may want to 
		    report on calls missed for other reasons than
		    being off-line too. Particularly, users may wish to be
		    reported calls missed due to call cancellation,
		    busy status or a downstream failure. Such missed
		    calls can be easily reported to syslog or mysql
		    using the acc module (see <xref linkend="missedcalls">).
		    The other, more general way, is to return to request
		    processing on receipt of a negative reply.
		    (see <xref linkend="replyprocessingsection">). Before
		    a request is forwarded, it is labeled to be
		    re-processed in a <command moreinfo="none">failure_route</command>
		    on receipt of a negative reply -- this is what
		    <command moreinfo="none">t_on_failure</command> action
		    is used for. It does not matter what caused the transaction
		    to fail -- it may be unresponsive downstream server,
		    server responding with 6xx, or server sending a 487
		    reply, because an INVITE was cancelled. When any such
		    circumstances occur (i.e., transaction does not complete
		    with a 2xx status code), <command moreinfo="none">failure_route</command>
		    is entered.
		    The following <application moreinfo="none">ser</application>
		    script reports missed calls in all possible cases.
		    It reports them when a user is off-line as well as when
		    a user is on-line, but INVITE transaction does not complete
		    <programlisting format="linespecific">
	    </example> <!-- step 5, full exec use -->

	</section> <!-- using exec -->

	<section id="fifoserver">
	    <title>Application FIFO Server</title>

	    Application FIFO server is a very powerful method to program
	    SIP services. The most valuable benefit
	    is it works with SIP-unaware applications
	    written in any programming language. Textual nature of the
	    FIFO interface allows for easy integration with a lot of
	    existing programs. Today, <application moreinfo="none">ser</application>'s
	    complementary web-interface, <application moreinfo="none">serweb</application>,
	    written in PHP, leverages the FIFO interface when displaying
	    and changing user location records stored in server's memory.
	    It uses this interface to send instant messages too, without
	    any knowledge of underlying <acronym>SIP</acronym> stack.
	    Another application relying on the FIFO interface is 
	    <application moreinfo="none">serctl</application>, <application moreinfo="none">ser</application>
	    management utility. The command-line utility can browse
	    server's in-memory user-location database, display 
	    running processes and operational statistics.
		The way the FIFO server works is similar to how 
		<filename moreinfo="none">/proc</filename> filesystem works
		on some operating systems. It provides a human-readable way
		to access <application moreinfo="none">ser</application>'s
		internals. Applications dump their requests into the FIFO
		server and receive a status report when request processing
		completes. <application moreinfo="none">ser</application>
		exports a lot of its functionality located in both the
		core and external modules through the FIFO server. 
		FIFO requests are formed easily. They begin with a command
		enclosed in colons and followed by name of file or pipe (relative
		to <filename moreinfo="none">/tmp/</filename> path), to which
		a reply should be printed. The first request line may be
		followed by additional lines with command-specific 
		parameters. For example, the <command moreinfo="none">t_uac_dlg</command>
		FIFO command for initiating a transaction allows 
		to pass additional header fields and message body to
		a newly created transaction. Each request is terminated by
		an empty line. Whole requests must be sent by applications
		atomically in a single batch to avoid mixing with
		requests from other applications. Requests are sent to
		pipe at which <application moreinfo="none">ser</application>
		listens (filename configured by the <varname>fifo</varname> config
		file option).
		An easy way to use the FIFO interface is via the
		<application moreinfo="none">serctl</application>
		command-line tool. When called along with "fifo",
		FIFO command name, and optional parameters, the tool
		generates a FIFO request and prints request result.
		The following example shows use of this tool with
		the <command moreinfo="none">uptime</command> and
		<command moreinfo="none">which</command> commands.
		<command moreinfo="none">uptime</command> returns
		server's running time, <command moreinfo="none">which</command>
		returns list of available FIFO commands. Note that only
		the built-in FIFO command set is displayed as no modules
		were loaded in this example.
		    <title>Use of <application moreinfo="none">serctl</application> 
		    to Access FIFO Server</title>
		    <programlisting format="linespecific">
[jiri@cat test]$ serctl fifo uptime
Now: Fri Dec  6 17:56:10 2002
Up Since: Fri Dec  6 17:56:07 2002
Up time: 3 [sec]

[jiri@cat test]$ serctl fifo which
		The request which the <application moreinfo="none">serctl</application>
		command-line tool sent to FIFO server looked like this:
		    <title><command moreinfo="none">uptime</command> FIFO Request</title>
		    <programlisting format="linespecific">
		This request contains no parameters and consists only of
		command name enclosed in colons and name of file, to which
		a reply should be printed. FIFO replies consist of a status
		line followed by optional parameters. The status line consists,
		similarly to <acronym>SIP</acronym> reply status, of 
		a three-digit status code and a reason phrase. Status codes
		with leading digit 2 (200..299) are considered positive,
		any other values indicate an error. For example, FIFO server
		returns "500" if execution of a non-existing FIFO command is 
		    <title>FIFO Errors</title>
		    <programlisting format="linespecific">
[jiri@cat sip_router]$ serctl fifo foobar
500 command 'foobar' not available

		    <title>Showing User Contacts Using serctl</title>
			Another example of use of FIFO is accessing server's
			in-memory user location database. That's a very powerful
			feature: web applications and other tools can use it
			to gain users access to the database. They can add new
			contacts (like permanent gateway destinations), remove
			and review users' whereabouts. The example here utilizes
			FIFO command <command>ul_show_contact</command> to
			retrieve current whereabouts of user "jiri".
[jiri@fox ser]$ serctl fifo ul_show_contact location jiri
		The user location example demonstrates an essential feature
		of the FIFO server: extensibility. It is able to export new 
		commands implemented in new modules.
		Currently, usrloc module exports FIFO
		commands for maintaining in-memory user location
		database and tm module exports FIFO commands for
		management of SIP transactions. See the 
		example in 
		<filename moreinfo="none">examples/web_im/send_im.php</filename>
		for how to initiate a SIP transaction
		(instant message)
		from a PHP script via the FIFO server. This example
		uses FIFO command 
		<command moreinfo="none">t_uac_dlg</command>. The command
		is followed by parameters: header fields and 
		message body. The same FIFO command can be used from
		other environments to send instant messages too. The
		following example shows how to send instant messages
		from a shell script.
		    <title>Sending IM From Shell Script</title>
		    <programlisting format="linespecific">
# call this script to send an instant message; script parameters
# will be displayed in message body
# paremeters mean: message type, request-URI, outbound server is
# left blank ("."), required header fields From and To follow,
# then optional header fields terminated by dot and optional
# dot-terminated body

cat &gt; /tmp/ser_fifo &lt;&lt;EOF
From: sip:originator@foo.bar
To: sip:receiver@
foo: bar_special_header
x: y
p_header: p_value
Contact: &lt;sip:devnull@;
Content-Type: text/plain; charset=UTF-8
Hello world!!!! $@
		<title>Manipulation of User Contacts</title>
		    The following example shows use of FIFO server to change 
		    user's contacts. This may be very practical, if for example
		    a user wishes to set up his cell phone number as his temporary
		    contact. The cell phone, which is behind a PSTN gateway, cannot
		    register automatically using SIP. The user needs to set 
		    forwarding manually through some convenient web interface.
		    The web interface needs to have the ability to upload new user's
		    contacts to <application moreinfo="none">ser</application>.
		    This is what the <command moreinfo="none">ul_add</command> FIFO
		    command is good for. Paremeterized by user's name, table name,
		    expiration time and weight, it allows external applications to
		    introduce new contacts to server's in-memory user location table.
		    The example is borrowed from <application moreinfo="none">serweb</application>,
		    <application moreinfo="none">ser</application>'s web 
		    PHP-written interface.
		    It consists of a short "stub" function which carries out
		    all mechanics of FIFO communication and of forming the FIFO
		<programlisting format="linespecific">

/* construct and send a FIFO command; the command parameters $sip_address, 
   $expires are PHP variables originating from an HTML form
		$config->ul_table."\n".			//table
		$user_id."\n".		//username
		$sip_address."\n".				//contact
		$expires."\n".					//expires
		$config->ul_priority."\n\n";		//priority
		$message=write2fifo($fifo_cmd, $errors, $status);

/* .......... snip .................. */

/* this is the stub function for communicating with FIFO server.
   it dumps a request to FIFO server, opens a reply FIFO and
   reads server's reply from it
function write2fifo($fifo_cmd, &$errors, &$status){
	global $config;

	/* open fifo now */
	$fifo_handle=fopen( $config->fifo_server, "w" );
	if (!$fifo_handle) {
		$errors[]="sorry -- cannot open fifo"; return;
	/* create fifo for replies */
	@system("mkfifo -m 666 ".$config->reply_fifo_path );

	/* add command separator */
	/* write fifo command */
	if (fwrite( $fifo_handle, $fifo_cmd)==-1) {
		$errors[]="sorry -- fifo writing error"; return;
	/* read output now */
	@$fp = fopen( $config->reply_fifo_path, "r");
	if (!$fp) {
		$errors[]="sorry -- fifo reading error"; return;

	if (!$status) {
		$errors[]="sorry -- fifo reading error"; return;
	return $rd;
		<xref linkend="fiforeference"> for a complete listing
		of FIFO commands available with current 
		<application moreinfo="none">ser</application>
		<title>Advanced Example: Click-To-Dial</title>
		    A very useful SIP application is phonebook with
		    "click-to-dial" feature. It allows users to keep their 
		    phonebooks on the web and dial by clicking on an entry. 
		    The great advantage is that you can use the phonebook 
		    alone with any phone you have. If you temporarily use 
		    another phone, upgrade it permanently with another make, 
		    or use multiple phones in parallel, your phonebook will 
		    stay with you on the web. You just need to click an entry 
		    to initiate a call. Other scenario using "click-to-dial"
		    feature includes "click to be connected with our
		    sales representative".
		    There are basically two ways how to build such a feature:
		    distributed and centralized. We prefer the distributed
		    approach since it is very robust and leight-weighted.
		    The "click-to-dial" application just needs to instruct
		    the calling user to call a destination and that's it.
		    (That's done using "REFER" method.)
		    Then, the calling user takes over whereas the initating
		    application disappears from signaling and
		    is no longer involved in subsequent communication. Which
		    is good because such a simple design scales well. 
		    The other design alternative is use of a B2BUA 
			    See <filename moreinfo="none">
			    </filename>  for more details.
		    which acts as a "middleman" involved in signaling during the
		    whole session. It is complex: ringing needs to be achieved
		    using a media server, it introduces session state,
		    mangling of SIP payloads, complexity when QoS reservation
		    is used and possibly other threats which result from 
		    e2e-unfriendly design. The only benefit
		    is it works even for poor phones which do not support
		    REFER -- which should not matter because you do not wish
		    to buy such.
		    So how does "distributed click-to-dial" application
		    work? It is simple. The core piece is sending a REFER
		    request to the calling party. REFER method is typically
		    used for call transfer and it means "set up a call 
		    to someone else". 
		    There is an issue -- most phones
		    don't accept unsolicited REFER. If a malicious
		    user made your phone to call thirty destinations without
		    your agreement, you would certainly not appreciate it.
		    The workaround is that first of all the click-to-dial
		    application gives you a "wrapper call". If you accept it, 
		    the application will send a REFER which will be considered
		    by the phone as a part of approved communication and
		    granted. Be aware that without cryptography, 
		    security is still weak. Anyone who saw an INVITE can 
		    generate an acceptable REFER.
			<title>Call-Flow for Click-To-Dial Using REFER</title>

			<programlisting format="linespecific">

        CTD                  Caller               Callee
            #1 INVITE
                             caller answers
            #2 200
            #3 ACK
            #4 REFER
            #5 202
            #6 BYE
            #7 200
                                  #8 INVITE
                                  #9 180 ringing

#1 click-to-dial (CTD) is started and the "wrapper call" is initiated
INVITE caller
From: controller
To: caller
SDP: on hold

#2 calling user answes
200 OK
From: controller
To: caller

#3 CTD acknowledges
ACK caller
From controller
To: caller

#4 CTD initiates a transfer
REFER caller
From: controller
To: caller
Refer-To: callee
Refered-By: controller

#5 caller confirms delivery of REFER
202 Accepted
From: controller
To: caller

#6 CTD terminates the wrapper call -- it is no longer needed
BYE caller
From: controller
To: caller

#7 BYE is confirmed
200 Ok
From: controller
To: caller

#8 caller initates transaction solicited through REFER
INVITE callee
From: caller
To: callee
Referred-By: controller

#9 that's it -- it is now up to callee to answer the INVITE
180 ringing
From: caller
To: callee

		    Implementation of this scenario is quite
		    straight-forward: you initiate INVITE, BYE and
		    REFER transaction.

		    Source code of the example written in Bourne shell
		    is available in source distrubtion, in 
		    <filename moreinfo="none">examples/ctd.sh</filename>.
		    A PHP implementation exists as well as a part of
		    <title>Running the CTD Example</title>
		    <programlisting format="linespecific">
[jiri@cat examples]$ ./ctd.sh 
destination unspecified -- taking default value sip:23@
caller unspecified -- taking default value sip:113311@
invitation succeeded
refer succeeded
bye succeeded
	    </section> <!-- click-to-dial -->
<!-- for some reason, this does not work :-(

		    <title>Initiating a SIP Transaction from PHP via FIFO</title>

		    <programlisting format="linespecific">
			    <textdata fileref="../../examples/web_im/send_im.php" format="linespecific">


	</section> <!-- FIFO server -->