Merge branch 'master' into treimann/acc-cdr
[sip-router] / modules_k / dialog / doc / dialog_devel.xml
1 <?xml version="1.0" encoding='ISO-8859-1'?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4
5 <!-- Include general documentation entities -->
6 <!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
7 %docentities;
8
9 ]>
10 <!-- Module Developer's Guide -->
11
12 <chapter>
13         
14         <title>&develguide;</title>
15         <section>
16         <title>Available Functions</title>
17
18         <section>
19                 <title>
20                 <function moreinfo="none">register_dlgcb (dialog, type, cb, param, free_param_cb)</function>
21                 </title>
22                 <para>
23                 Register a new callback to the dialog.
24                 </para>
25                 <para>Meaning of the parameters is as follows:</para>
26                 <itemizedlist>
27                 <listitem>
28                         <para><emphasis>struct dlg_cell* dlg</emphasis> - dialog to 
29                         register callback to. If maybe NULL only for DLGCB_CREATED callback
30                         type, which is not a per dialog type.
31                         </para>
32                 </listitem>
33                 <listitem>
34                         <para><emphasis>int type</emphasis> - types of callbacks; more
35                         types may be register for the same callback function; only 
36                         DLGCB_CREATED must be register alone. Possible types:
37                         <itemizedlist>
38                         <listitem>
39                                 <para><emphasis>DLGCB_LOADED</emphasis>
40                                 </para>
41                         </listitem>
42                         <listitem>
43                                 <para><emphasis>DLGCB_CREATED</emphasis> - called when a new 
44                                 dialog is created - it's a global type (not associated to 
45                                 any dialog)
46                                 </para>
47                         </listitem>
48                         <listitem>
49                                 <para><emphasis>DLGCB_FAILED</emphasis> - called when the dialog
50                                 was negatively replied (non-2xx) - it's a per dialog type.
51                                 </para>
52                         </listitem>
53                         <listitem>
54                                 <para><emphasis>DLGCB_CONFIRMED</emphasis> - called when the 
55                                 dialog is confirmed (2xx replied) and the setup-concluding ACK
56                                 message from the caller has been seen - it's a per dialog type.
57                                 </para>
58                         </listitem>
59                         <listitem>
60                                 <para><emphasis>DLGCB_REQ_WITHIN</emphasis> - called when the 
61                                 dialog matches a sequential request - it's a per dialog type.
62                                 </para>
63                         </listitem>
64                         <listitem>
65                                 <para><emphasis>DLGCB_TERMINATED</emphasis> - called when the 
66                                 dialog is terminated via BYE - it's a per dialog type.
67                                 </para>
68                         </listitem>
69                         <listitem>
70                                 <para><emphasis>DLGCB_TERMINATED_CONFIRMED</emphasis> -
71                                 called when response to a BYE request is received - it's a
72                                 per dialog type.
73                                 </para>
74                         </listitem>
75                         <listitem>
76                                 <para><emphasis>DLGCB_EXPIRED</emphasis> - called when the 
77                                 dialog expires without receiving a BYE - it's a per dialog 
78                                 type.
79                                 </para>
80                         </listitem>
81                         <listitem>
82                                 <para><emphasis>DLGCB_EARLY</emphasis> - called when the
83                                 dialog is created in an early state (18x replied) - it's
84                                 a per dialog type.
85                                 </para>
86                         </listitem>
87                         <listitem>
88                                 <para><emphasis>DLGCB_RESPONSE_FWDED</emphasis> - called when
89                                 the dialog matches a reply to the initial INVITE request - it's
90                                 a per dialog type.
91                                 </para>
92                         </listitem>
93                         <listitem>
94                                 <para><emphasis>DLGCB_RESPONSE_WITHIN</emphasis> - called when
95                                 the dialog matches a reply to a subsequent in dialog request
96                                 - it's a per dialog type.
97                                 </para>
98                         </listitem>
99                         <listitem>
100                                 <para><emphasis>DLGCB_MI_CONTEXT</emphasis> - called when the
101                                 mi dlg_list_ctx command is invoked - it's a per dialog type.
102                                 </para>
103                         </listitem>
104                         <listitem>
105                                 <para><emphasis>DLGCB_SPIRALED</emphasis> - called when the
106                                 dialog matches a spiraling request - it's a per dialog type.
107                                 </para>
108                         </listitem>
109                         <listitem>
110                                 <para><emphasis>DLGCB_DESTROY</emphasis>
111                                 </para>
112                         </listitem>
113                         </itemizedlist>
114                         </para>
115                 </listitem>
116                 <listitem>
117                         <para><emphasis>dialog_cb cb</emphasis> - callback function to be 
118                         called. Prototype is: <quote>void (dialog_cb) 
119                         (struct dlg_cell* dlg, int type, struct dlg_cb_params * params);
120                         </quote>
121                         </para>
122                 </listitem>
123                 <listitem>
124                         <para><emphasis>void *param</emphasis> - parameter to be passed to
125                         the callback function.
126                         </para>
127                 </listitem>
128                 <listitem>
129                         <para><emphasis>param_free callback_param_free</emphasis> - 
130                         callback function to be called to free the param.
131                         Prototype is: <quote>void (param_free_cb) (void *param);</quote>
132                         </para>
133                 </listitem>
134
135                 </itemizedlist>
136         </section>
137
138
139         <section>
140                 <title>
141                 <function moreinfo="none">terminate_dlg (dlg, hdrs)</function>
142                 </title>
143                 <para>
144                 Terminate a Dialog
145                 </para>
146                 <para>Meaning of parameters is as follows:</para>
147                 <itemizedlist>
148                 <listitem>
149                         <para><emphasis>struct dlg_cell* dlg</emphasis> - dialog to 
150                         terminate.
151                         </para>
152                 </listitem>
153                 <listitem>
154                         <para><emphasis>str* hdrs</emphasis> - string containg extra headers (full format) 
155                         to be added to the BYE requests of the dialog.
156                         </para>
157                 </listitem>
158                 </itemizedlist>
159         </section>
160
161         </section>
162
163 </chapter>
164