9528a4045f08d308774c8f6a30f3059f00631e66
[sip-router] / doc / seruser / apps.sgml
1     <chapter>
2         <title>Application Writing</title>
3         <para>
4             <application moreinfo="none">ser</application> offers several
5             ways to couple its functionality with applications. The coupling
6             is bidirectional: <application moreinfo="none">ser</application>
7             can utilize external applications and external applications can
8             utilize <application moreinfo="none">ser</application>. 
9             An example of the former direction would be an external program
10             determining a least-cost route for a called destination  using 
11             a pricing table. An example of the latter case
12             is a web application for server provisioning.
13             Such an application may want to send instant 
14             messages, query all current user's locations and monitor server
15             health. An existing web interface to <application moreinfo="none">ser</application>,
16             <application moreinfo="none">serweb</application>, actually
17             does all of it. 
18         </para>
19         <para>
20             The easiest, language-independent way of using external logic 
21             from <application moreinfo="none">ser</application> is provided
22             by exec module. exec module allows <application moreinfo="none">ser</application>
23             to start external programs on receipt of a request. The
24             programs can execute arbitrary logic and/or affect routing of SIP
25             requests. A great benefit of this programming method is it
26             is language-independent. Programmers may use programming languages
27             that are effective or with which they are best familiar.
28             <xref linkend="usingexec"> gives additional examples illustrating 
29             use of the exec module.
30         </para>
31         <para>
32             Another method for extending <application moreinfo="none">ser</application>
33             capabilities is to write new modules in C. This method takes
34             deeper understanding of <application moreinfo="none">ser</application>
35             internals but gains the highest flexibility. Modules can implement
36             arbitrary brand-new commands upon which <application moreinfo="none">ser</application>
37             scripts can rely on. Guidelines on module programming can be
38             found in <application moreinfo="none">ser</application>
39             programmer's handbook available from iptel.org website.
40         </para>
41         <para>
42             To address needs of applications wishing to leverage
43             <application moreinfo="none">ser</application>,
44             <application moreinfo="none">ser</application> exports
45             parts of its functionality via its built-in
46             "Application FIFO server". This is a simple textual
47             interface that allows any external applications
48             to communicate with the server. It can be used to
49             send instant messages, manipulate user contacts,
50             watch server health, etc. Programs written in any
51             language (PHP, shell scripts, Perl, C, etc.) can
52             utilize this feature. How to use it is shown in
53             <xref linkend="fifoserver">.
54         </para>
55
56
57         <section id="usingexec">
58             <title>Using exec Module</title>
59             <para>
60                 
61                 The easiest way is to couple <application moreinfo="none">ser</application>
62                 with external applications via the <emphasis>exec</emphasis>
63                 module. This module allows execution of logic and URI manipulation 
64                 by external applications on request receipt. While very
65                 simple, many useful services can be
66                 implemented this way. External applications can be written in
67                 any programming language and do not be aware of SIP at all.
68                 <application moreinfo="none">ser</application> interacts with
69                 the application via standard input/output and environment 
70                 variables.
71                 
72
73             </para>
74         
75
76             <para>
77                 For example, an external shell script
78                 may send an email whenever a request for a user arrives.
79             </para>
80
81             <example>
82                 <title>Using exec: Step 1</title>
83                 <programlisting format="linespecific">
84 # send email if a request for user "jiri" arrives
85 if (uri=~"^sip:jiri@") {
86      exec_msg("echo 'body: call arrived'|mail -s 'call for you' jiri");
87 }
88                 </programlisting>
89             </example> <!-- step 1 -->
90             <para>
91                 In this example, the <command moreinfo="none">exec_msg</command> 
92                 action starts an external shell. It passes a received SIP request
93                 to shell's input. In the shell, <command>mail</command> command
94                 is called to send a notification by e-mail.
95                 The script however features several simplifications:
96                 <orderedlist inheritnum="ignore" continuation="restarts">
97                     <listitem>
98                         <para>
99                             The email notification does not tell who was calling.
100                         </para>
101                     </listitem>
102                     <listitem>
103                         <para>
104                             The logic is not general: it only supports one well-known user (jiri).
105                         </para>
106                     </listitem>
107                     <listitem>
108                         <para>
109                             The logic is stateless. It will be executed on
110                             every retransmission.
111                         </para>
112                     </listitem>
113                     <listitem>
114                         <para>
115                             It is a script fragment not explaining the 
116                             context. This particular example may be for
117                             example used to report on missed calls.
118                         </para>
119                     </listitem>
120                 </orderedlist>
121                 All of these simplifications are addressed step-by-step
122                 in the following examples.
123             </para>
124             <example> <!-- step 2: who called me -->
125                 <title>Using exec: Step 2, Who Called Me</title>
126                 <para>
127                     This example shows how to display caller's address
128                     in email notification. The trick is easy: process
129                     request received on shell programm's input
130                     and grep From header field.
131                 </para>
132                 <programlisting format="linespecific">
133 &execstep2;
134                 </programlisting>
135                 <para>
136                         The following two figures show an example SIP request and
137                         email notification generated on its receipt.
138                         
139                     <screen format="linespecific">
140
141 <![CDATA[
142 INVITE sip:jiri@iptel.org SIP/2.0
143 Via: SIP/2.0/UDP 195.37.77.100:5040
144 Max-Forwards: 10
145 From: "alice" <sip:alice@iptel.org>;tag=76ff7a07-c091-4192-84a0-d56e91fe104f
146 To: <sip:jiri@iptel.org>
147 Call-ID: d10815e0-bf17-4afa-8412-d9130a793d96@213.20.128.35
148 CSeq: 2 INVITE
149 Contact: <sip:123.20.128.35:9315>
150 Content-Type: application/sdp
151 Content-Length: 451
152
153 --- SDP payload snipped ---
154 ]]>
155
156                     </screen>
157                 
158                     email received:
159                 
160                         <screen format="linespecific">
161 <![CDATA[
162 Date: Thu, 12 Dec 2002 14:25:02 +0100
163 From: root <root@cat.iptel.org>
164 To: jiri@cat.iptel.org
165 Subject: request for you
166
167 From: "alice" <sip:alice@iptel.org>;tag=76ff7a07-c091-4192-84a0-d56e91fe104f
168 request received
169 ]]>
170                     </screen>
171                 </para>
172                 <para>
173                     There is another way to learn values of request
174                     header fields, simpler than use of <command moreinfo="none">grep</command>. 
175                     <application moreinfo="none">ser</application>
176                     parses header fields and passes their values in 
177                     environment variables. Their names correspond
178                     to header field names prefixed with "SIP_HF_".
179                 <programlisting format="linespecific">
180 # send email if a request for "jiri" arrives
181 if (uri=~"^sip:jiri@") {
182      exec_msg("echo request received from $SIP_HF_FROM | mail -s 'request for you' jiri");
183 };
184                 </programlisting>
185                     Moreover, several other values are passed in environment
186                     variables. <varname>SIP_TID</varname> is a token uniquely identifying 
187                     transaction, to which the request belongs. <varname>SIP_DID</varname>
188                     includes to-tag, and is empty in requests creating a dialog.
189                     <varname>SIP_SRCIP</varname> includes IP address, from which the
190                     request was sent. <varname>SIP_RURI</varname> and <varname>SIP_ORURI</varname>
191                     include current request-uri and original request-uri respectively,
192                     <varname>SIP_USER</varname> and <varname>SIP_OUSER</varname> username
193                     parts of these. The following listing shows environment variables
194                     passed to a shell script on receipt of the previous message:
195                     <programlisting format="linespecific">
196 <![CDATA[
197 SIP_HF_MAX_FORWARDS=10
198 SIP_HF_VIA=SIP/2.0/UDP 195.37.77.100:5040
199 SIP_HF_CSEQ=2 INVITE
200 SIP_HF_FROM="alice" <sip:alice@iptel.org>;tag=76ff7a07-c091-4192-84a0-d56e91fe104f
201 SIP_ORUI=sip:jiri@iptel.org
202 SIP_HF_CONTENT_LENGTH=451
203 SIP_TID=3b6b8295db0835815847b1f35f3b29b8
204 SIP_DID=
205 SIP_RURI=iptel.org
206 SIP_HF_TO=<sip:jiri@iptel.org>
207 SIP_OUSER=jiri
208 SIP_HF_CALLID=d10815e0-bf17-4afa-8412-d9130a793d96@213.20.128.35
209 SIP_SRCIP=195.37.77.100
210 SIP_HF_CONTENT_TYPE=application/sdp
211 SIP_HF_CONTACT=<sip:123.20.128.35:9315>
212 ]]>
213                     </programlisting>
214                                     
215                 </para>
216             </example> <!-- step 2, who called me -->
217
218
219             <example>  <!-- step 3,  make the script work for anyone -->
220                 <title>Using exec: step 3, Make The Script Work For Anyone</title>
221                 <para>
222                     A drawback of the previous example is it works only
223                     for one well-known user: request URI is matched against
224                     his SIP address and notification is sent to his hard-wired email
225                     address. In real scenarios, one would like
226                     to enable such a service for all users without enumerating
227                     their addresses in the script. The missing piece
228                     is translation of user's SIP name to his email address.
229                     This information is maintained in subscriber profiles,
230                     stored in MySQL by <application moreinfo="none">ser</application>.
231                     To translate the username to email address, the executed script
232                     needs to query the MySQL database. That is what this example
233                     shows. First, an SQL query is constructed which looks up
234                     email address of user, for whom a request arrived. If the
235                     query does not return a valid email address, the script
236                     returns with an error status and <application moreinfo="none">ser</application>
237                     script replies with "user does not exist". Otherwise
238                     an email notification is sent.
239                 
240                     <programlisting format="linespecific">
241 &execstep3;
242                     </programlisting>
243                 </para>
244             </example> <!-- step 3 make the script work for anyone -->
245             <example> <!-- step 4, stateful processing -->
246                 <title>Adding Stateful Processing</title>
247                 <para>
248                     The previously improved example still features a shortcoming.
249                     When a message retransmission arrives due to a nework
250                     mistake such as lost reply, the email notification is
251                     executed again and again. That happens because the script
252                     is stateless, i.e., no track of current transactions is
253                     kept. The script does not know whether a request is
254                     a new or a retransmitted one. Transaction management may
255                     be introduced by use of tm module as described in
256                     <xref linkend="statefulua">. In the script,
257                     <command moreinfo="none">t_newtran</command> is first
258                     called to absorb requests retransmission -- if they
259                     occur, script does not continue. Then, as in the previous
260                     example, an exec module action is called. Eventually,
261                     a reply is sent statefully.
262                     <note>
263                         <para>
264                             Note carefuly: it is important that the stateful
265                             reply processing (<command moreinfo="none">t_reply</command>)
266                             is used as opposed to using stateless replies
267                             (<command moreinfo="none">sl_send_reply</command>).
268                             Otherwise, the outgoing reply would not affect
269                             transactional context and would not be resent on
270                             receipt of a request retransmission.
271                         </para>
272                     </note>
273                     <programlisting format="linespecific">
274 &execstep4;
275                     </programlisting>
276                     
277                 </para>
278             </example> <!-- step 4,  stateful processing -->
279             <example> <!-- step 5, full exec use -->
280                 <title>Full Example of exec Use</title>
281                 <para>
282                     The last example iteration shows how to integrate the
283                     email notification on missed calls with the default
284                     <application moreinfo="none">ser</application> script
285                     (see <xref linkend="defaultscript">). It generates an
286                     email for every call invitation to an off-line user.
287                     <programlisting format="linespecific">
288 &execstep5;
289                     </programlisting>
290                 </para>
291                     
292                 <para>
293                     Production "missed calls" services may want to 
294                     report on calls missed for other reasons than
295                     being off-line too. Particularly, users may wish to be
296                     reported calls missed due to call cancellation,
297                     busy status or a downstream failure. Such missed
298                     calls can be easily reported to syslog or mysql
299                     using the acc module (see <xref linkend="missedcalls">).
300                     The other, more general way, is to return to request
301                     processing on receipt of a negative reply.
302                     (see <xref linkend="replyprocessingsection">). Before
303                     a request is forwarded, it is labeled to be
304                     re-processed in a <command moreinfo="none">failure_route</command>
305                     on receipt of a negative reply -- this is what
306                     <command moreinfo="none">t_on_failure</command> action
307                     is used for. It does not matter what caused the transaction
308                     to fail -- it may be unresponsive downstream server,
309                     server responding with 6xx, or server sending a 487
310                     reply, because an INVITE was cancelled. When any such
311                     circumstances occur (i.e., transaction does not complete
312                     with a 2xx status code), <command moreinfo="none">failure_route</command>
313                     is entered.
314                 </para>
315                 <para>
316                     The following <application moreinfo="none">ser</application>
317                     script reports missed calls in all possible cases.
318                     It reports them when a user is off-line as well as when
319                     a user is on-line, but INVITE transaction does not complete
320                     successfully.
321                     <programlisting format="linespecific">
322 &execstep5b;
323                     </programlisting>
324                 </para>
325                 
326             </example> <!-- step 5, full exec use -->
327
328         </section> <!-- using exec -->
329
330         <section id="fifoserver">
331             <title>Application FIFO Server</title>
332
333             <para>
334             Application FIFO server is a very powerful method to program
335             SIP services. The most valuable benefit
336             is it works with SIP-unaware applications
337             written in any programming language. Textual nature of the
338             FIFO interface allows for easy integration with a lot of
339             existing programs. Today, <application moreinfo="none">ser</application>'s
340             complementary web-interface, <application moreinfo="none">serweb</application>,
341             written in PHP, leverages the FIFO interface when displaying
342             and changing user location records stored in server's memory.
343             It uses this interface to send instant messages too, without
344             any knowledge of underlying <acronym>SIP</acronym> stack.
345             Another application relying on the FIFO interface is 
346             <application moreinfo="none">serctl</application>, <application moreinfo="none">ser</application>
347             management utility. The command-line utility can browse
348             server's in-memory user-location database, display 
349             running processes and operational statistics.
350             </para>
351             <para>
352                 The way the FIFO server works is similar to how 
353                 <filename moreinfo="none">/proc</filename> filesystem works
354                 on some operating systems. It provides a human-readable way
355                 to access <application moreinfo="none">ser</application>'s
356                 internals. Applications dump their requests into the FIFO
357                 server and receive a status report when request processing
358                 completes. <application moreinfo="none">ser</application>
359                 exports a lot of its functionality located in both the
360                 core and external modules through the FIFO server. 
361                 </para>
362             <para>
363                 FIFO requests are formed easily. They begin with a command
364                 enclosed in colons and followed by name of file or pipe (relative
365                 to <filename moreinfo="none">/tmp/</filename> path), to which
366                 a reply should be printed. The first request line may be
367                 followed by additional lines with command-specific 
368                 parameters. For example, the <command moreinfo="none">t_uac_dlg</command>
369                 FIFO command for initiating a transaction allows 
370                 to pass additional header fields and message body to
371                 a newly created transaction. Each request is terminated by
372                 an empty line. Whole requests must be sent by applications
373                 atomically in a single batch to avoid mixing with
374                 requests from other applications. Requests are sent to
375                 pipe at which <application moreinfo="none">ser</application>
376                 listens (filename configured by the <varname>fifo</varname> config
377                 file option).
378             </para>
379             <para>
380                 An easy way to use the FIFO interface is via the
381                 <application moreinfo="none">serctl</application>
382                 command-line tool. When called along with "fifo",
383                 FIFO command name, and optional parameters, the tool
384                 generates a FIFO request and prints request result.
385                 The following example shows use of this tool with
386                 the <command moreinfo="none">uptime</command> and
387                 <command moreinfo="none">which</command> commands.
388                 <command moreinfo="none">uptime</command> returns
389                 server's running time, <command moreinfo="none">which</command>
390                 returns list of available FIFO commands. Note that only
391                 the built-in FIFO command set is displayed as no modules
392                 were loaded in this example.
393                 <example>
394                     <title>Use of <application moreinfo="none">serctl</application> 
395                     to Access FIFO Server</title>
396                     <programlisting format="linespecific">
397 [jiri@cat test]$ serctl fifo uptime
398 Now: Fri Dec  6 17:56:10 2002
399 Up Since: Fri Dec  6 17:56:07 2002
400 Up time: 3 [sec]
401
402 [jiri@cat test]$ serctl fifo which
403 ps
404 which
405 version
406 uptime
407 print
408                     </programlisting>
409                 </example>
410                 The request which the <application moreinfo="none">serctl</application>
411                 command-line tool sent to FIFO server looked like this:
412                 <example>
413                     <title><command moreinfo="none">uptime</command> FIFO Request</title>
414                     <programlisting format="linespecific">
415 :uptime:ser_receiver_1114
416                     </programlisting>
417                 </example>
418                 This request contains no parameters and consists only of
419                 command name enclosed in colons and name of file, to which
420                 a reply should be printed. FIFO replies consist of a status
421                 line followed by optional parameters. The status line consists,
422                 similarly to <acronym>SIP</acronym> reply status, of 
423                 a three-digit status code and a reason phrase. Status codes
424                 with leading digit 2 (200..299) are considered positive,
425                 any other values indicate an error. For example, FIFO server
426                 returns "500" if execution of a non-existing FIFO command is 
427                 requested.
428                 <example>
429                     <title>FIFO Errors</title>
430                     <programlisting format="linespecific">
431 [jiri@cat sip_router]$ serctl fifo foobar
432 500 command 'foobar' not available
433                     </programlisting>
434                 </example>
435
436                 <example>
437                     <title>Showing User Contacts Using serctl</title>
438                     <para>
439                         Another example of use of FIFO is accessing server's
440                         in-memory user location database. That's a very powerful
441                         feature: web applications and other tools can use it
442                         to gain users access to the database. They can add new
443                         contacts (like permanent gateway destinations), remove
444                         and review users' whereabouts. The example here utilizes
445                         FIFO command <command>ul_show_contact</command> to
446                         retrieve current whereabouts of user "jiri".
447                         <programlisting>
448 <![CDATA[
449 [jiri@fox ser]$ serctl fifo ul_show_contact location jiri
450 <sip:195.37.78.160:14519>;q=0.00;expires=1012
451 ]]>
452                         </programlisting>
453                     </para>
454                 </example>
455             </para>
456             <para>
457                 The user location example demonstrates an essential feature
458                 of the FIFO server: extensibility. It is able to export new 
459                 commands implemented in new modules.
460                 Currently, usrloc module exports FIFO
461                 commands for maintaining in-memory user location
462                 database and tm module exports FIFO commands for
463                 management of SIP transactions. See the 
464                 example in 
465                 <filename moreinfo="none">examples/web_im/send_im.php</filename>
466                 for how to initiate a SIP transaction
467                 (instant message)
468                 from a PHP script via the FIFO server. This example
469                 uses FIFO command 
470                 <command moreinfo="none">t_uac_dlg</command>. The command
471                 is followed by parameters: header fields and 
472                 message body. The same FIFO command can be used from
473                 other environments to send instant messages too. The
474                 following example shows how to send instant messages
475                 from a shell script.
476                 <example>
477                     <title>Sending IM From Shell Script</title>
478                     <programlisting format="linespecific">
479 #!/bin/sh
480 #
481 # call this script to send an instant message; script parameters
482 # will be displayed in message body
483 #
484 # paremeters mean: message type, request-URI, outbound server is
485 # left blank ("."), required header fields From and To follow,
486 # then optional header fields terminated by dot and optional
487 # dot-terminated body
488
489 cat &gt; /tmp/ser_fifo &lt;&lt;EOF
490 :t_uac_dlg:hh
491 NOTIFY
492 sip:receiver@127.0.0.1
493 .
494 From: sip:originator@foo.bar
495 To: sip:receiver@127.0.0.1
496 foo: bar_special_header
497 x: y
498 p_header: p_value
499 Contact: &lt;sip:devnull@192.168.0.100:9&gt;
500 Content-Type: text/plain; charset=UTF-8
501 .
502 Hello world!!!! $@
503 .
504 EOF
505                     </programlisting>
506                 </example>
507                 </para>
508             <example>
509                 <title>Manipulation of User Contacts</title>
510                 <para>
511                     The following example shows use of FIFO server to change 
512                     user's contacts. This may be very practical, if for example
513                     a user wishes to set up his cell phone number as his temporary
514                     contact. The cell phone, which is behind a PSTN gateway, cannot
515                     register automatically using SIP. The user needs to set 
516                     forwarding manually through some convenient web interface.
517                     The web interface needs to have the ability to upload new user's
518                     contacts to <application moreinfo="none">ser</application>.
519                     This is what the <command moreinfo="none">ul_add</command> FIFO
520                     command is good for. Paremeterized by user's name, table name,
521                     expiration time and weight, it allows external applications to
522                     introduce new contacts to server's in-memory user location table.
523                 </para>
524                 <para>
525                     The example is borrowed from <application moreinfo="none">serweb</application>,
526                     <application moreinfo="none">ser</application>'s web 
527                     PHP-written interface.
528                     It consists of a short "stub" function which carries out
529                     all mechanics of FIFO communication and of forming the FIFO
530                     request.
531                 </para>
532                 <programlisting format="linespecific">
533 <![CDATA[
534
535 /* construct and send a FIFO command; the command parameters $sip_address, 
536    $expires are PHP variables originating from an HTML form
537  */
538         $fifo_cmd=":ul_add:".$config->reply_fifo_filename."\n".
539                 $config->ul_table."\n".                 //table
540                 $user_id."\n".          //username
541                 $sip_address."\n".                              //contact
542                 $expires."\n".                                  //expires
543                 $config->ul_priority."\n\n";            //priority
544                 $message=write2fifo($fifo_cmd, $errors, $status);
545
546 /* .......... snip .................. */
547
548 /* this is the stub function for communicating with FIFO server.
549    it dumps a request to FIFO server, opens a reply FIFO and
550    reads server's reply from it
551 */
552 function write2fifo($fifo_cmd, &$errors, &$status){
553         global $config;
554
555         /* open fifo now */
556         $fifo_handle=fopen( $config->fifo_server, "w" );
557         if (!$fifo_handle) {
558                 $errors[]="sorry -- cannot open fifo"; return;
559         }
560         
561         /* create fifo for replies */
562         @system("mkfifo -m 666 ".$config->reply_fifo_path );
563
564         /* add command separator */
565         $fifo_cmd=$fifo_cmd."\n";
566         
567         /* write fifo command */
568         if (fwrite( $fifo_handle, $fifo_cmd)==-1) {
569             @unlink($config->reply_fifo_path);
570             @fclose($fifo_handle);
571                 $errors[]="sorry -- fifo writing error"; return;
572         }
573         @fclose($fifo_handle);
574         
575         /* read output now */
576         @$fp = fopen( $config->reply_fifo_path, "r");
577         if (!$fp) {
578             @unlink($config->reply_fifo_path);
579                 $errors[]="sorry -- fifo reading error"; return;
580         }
581
582         $status=fgetS($fp,256);
583         if (!$status) {
584             @unlink($config->reply_fifo_path);
585                 $errors[]="sorry -- fifo reading error"; return;
586         }
587         
588         $rd=fread($fp,8192);
589         @unlink($config->reply_fifo_path);
590         
591         return $rd;
592 }
593 ]]>                
594                 </programlisting>
595             </example>
596             <para>
597                 See
598                 <xref linkend="fiforeference"> for a complete listing
599                 of FIFO commands available with current 
600                 <application moreinfo="none">ser</application>
601                 distribution.
602             </para>
603             <section>
604                 <title>Advanced Example: Click-To-Dial</title>
605                 <para>
606                     A very useful SIP application is phonebook with
607                     "click-to-dial" feature. It allows users to keep their 
608                     phonebooks on the web and dial by clicking on an entry. 
609                     The great advantage is that you can use the phonebook 
610                     alone with any phone you have. If you temporarily use 
611                     another phone, upgrade it permanently with another make, 
612                     or use multiple phones in parallel, your phonebook will 
613                     stay with you on the web. You just need to click an entry 
614                     to initiate a call. Other scenario using "click-to-dial"
615                     feature includes "click to be connected with our
616                     sales representative".
617                 </para>
618                 <para>
619                     There are basically two ways how to build such a feature:
620                     distributed and centralized. We prefer the distributed
621                     approach since it is very robust and leight-weighted.
622                     The "click-to-dial" application just needs to instruct
623                     the calling user to call a destination and that's it.
624                     (That's done using "REFER" method.)
625                     Then, the calling user takes over whereas the initating
626                     application disappears from signaling and
627                     is no longer involved in subsequent communication. Which
628                     is good because such a simple design scales well. 
629                 </para>
630                 <para>
631                     The other design alternative is use of a B2BUA 
632                     <footnote>
633                         <para>
634                             See <filename moreinfo="none">
635                                 draft-ietf-sipping-3pcc-02.txt 
636                             </filename>  for more details.
637                         </para>
638                     </footnote>
639                     which acts as a "middleman" involved in signaling during the
640                     whole session. It is complex: ringing needs to be achieved
641                     using a media server, it introduces session state,
642                     mangling of SIP payloads, complexity when QoS reservation
643                     is used and possibly other threats which result from 
644                     e2e-unfriendly design. The only benefit
645                     is it works even for poor phones which do not support
646                     REFER -- which should not matter because you do not wish
647                     to buy such.
648                 </para>
649                 <para>
650                     So how does "distributed click-to-dial" application
651                     work? It is simple. The core piece is sending a REFER
652                     request to the calling party. REFER method is typically
653                     used for call transfer and it means "set up a call 
654                     to someone else". 
655                     </para>
656                 <para>
657                     There is an issue -- most phones
658                     don't accept unsolicited REFER. If a malicious
659                     user made your phone to call thirty destinations without
660                     your agreement, you would certainly not appreciate it.
661                     The workaround is that first of all the click-to-dial
662                     application gives you a "wrapper call". If you accept it, 
663                     the application will send a REFER which will be considered
664                     by the phone as a part of approved communication and
665                     granted. Be aware that without cryptography, 
666                     security is still weak. Anyone who saw an INVITE can 
667                     generate an acceptable REFER.
668                                 <note>
669                                         <para>
670                                                 The wrapper INVITE may or may not be used
671                                                 in future. The internet draft
672                                                 draft-ietf-sipping-service-examples
673                                                 mentiones the click-to-dial application
674                                                 without use of the dummy INVITE. As of
675                                                 today, most telephones do need it.
676                                         </para>
677                                 </note>
678                     <example>
679                         <title>Call-Flow for Click-To-Dial Using REFER</title>
680
681                         <programlisting format="linespecific">
682
683         CTD                  Caller               Callee
684             #1 INVITE
685             ----------------->
686                              ...
687                              caller answers
688             #2 200
689             <-----------------
690             #3 ACK
691             ----------------->
692             #4 REFER
693             ----------------->
694             #5 202
695             <-----------------
696             #6 BYE
697             ----------------->
698             #7 200
699             <-----------------
700                                   #8 INVITE
701                                   ------------------>
702                                   #9 180 ringing
703                                   <------------------
704
705
706 #1 click-to-dial (CTD) is started and the "wrapper call" is initiated
707 INVITE caller
708 From: controller
709 To: caller
710 SDP: on hold
711
712 #2 calling user answes
713 200 OK
714 From: controller
715 To: caller
716
717 #3 CTD acknowledges
718 ACK caller
719 From controller
720 To: caller
721
722 #4 CTD initiates a transfer
723 REFER caller
724 From: controller
725 To: caller
726 Refer-To: callee
727 Refered-By: controller
728
729 #5 caller confirms delivery of REFER
730 202 Accepted
731 From: controller
732 To: caller
733
734 #6 CTD terminates the wrapper call -- it is no longer needed
735 BYE caller
736 From: controller
737 To: caller
738
739 #7 BYE is confirmed
740 200 Ok
741 From: controller
742 To: caller
743
744 #8 caller initates transaction solicited through REFER
745 INVITE callee
746 From: caller
747 To: callee
748 Referred-By: controller
749
750 #9 that's it -- it is now up to callee to answer the INVITE
751 180 ringing
752 From: caller
753 To: callee
754                         </programlisting>
755
756                     </example>
757                 </para>
758                 <para>
759                     Implementation of this scenario is quite
760                     straight-forward: you initiate INVITE, BYE and
761                     REFER transaction.
762
763
764
765                     Source code of the example written in Bourne shell
766                     is available in source distrubtion, in 
767                     <filename moreinfo="none">examples/ctd.sh</filename>.
768                     A PHP implementation exists as well as a part of
769                         <application>serweb</application>.
770                 </para>
771                 <example>
772                     <title>Running the CTD Example</title>
773                     <programlisting format="linespecific">
774 [jiri@cat examples]$ ./ctd.sh 
775 destination unspecified -- taking default value sip:23@192.168.2.16
776 caller unspecified -- taking default value sip:113311@192.168.2.16
777 invitation succeeded
778 refer succeeded
779 bye succeeded
780                     </programlisting>
781                 </example>
782             </section> <!-- click-to-dial -->
783 <!-- for some reason, this does not work :-(
784
785                 <example>
786                     <title>Initiating a SIP Transaction from PHP via FIFO</title>
787
788
789                     <programlisting format="linespecific">
790                         <textobject>
791                             <textdata fileref="../../examples/web_im/send_im.php" format="linespecific">
792                         </textobject>
793                             
794                     </programlisting>
795
796                     
797                 </example>
798 -->
799
800         </section> <!-- FIFO server -->
801     </chapter>
802