Browse code

modules: readme files regenerated - dlgs ... [skip ci]

Kamailio Dev authored on 09/07/2020 13:31:14
Showing 1 changed files
... ...
@@ -26,26 +26,44 @@ Daniel-Constantin Mierla
26 26
         3. Parameters
27 27
 
28 28
               3.1. active_lifetime (int)
29
-              3.2. timer_interval (int)
29
+              3.2. init_lifetime (int)
30
+              3.3. finish_lifetime (int)
31
+              3.4. timer_interval (int)
30 32
 
31 33
         4. Functions
32 34
 
33 35
               4.1. dlgs_init(src, dst, data)
34
-              4.2. dlgs_update(src)
36
+              4.2. dlgs_update()
37
+              4.3. dlgs_count(field, op, data)
38
+              4.4. dlgs_tags_add(vtag)
39
+              4.5. dlgs_tags_rm(vtag)
40
+              4.6. dlgs_tags_count(vtag)
35 41
 
36 42
         5. RPC Commands
37 43
 
38
-              5.1. rpc.list
39
-              5.2. rpc.stats
44
+              5.1. dlgs.list
45
+              5.2. dlgs.briefing
46
+              5.3. dlgs.get
47
+              5.4. dlgs.getall
48
+              5.5. dlgs.stats
40 49
 
41 50
    List of Examples
42 51
 
43 52
    1.1. Set active_lifetime parameter
44
-   1.2. Set timer_interval parameter
45
-   1.3. dlgs_init usage
46
-   1.4. dlgs_update usage
47
-   1.5. dlgs.list usage
48
-   1.6. dlgs.stats usage
53
+   1.2. Set init_lifetime parameter
54
+   1.3. Set finish_lifetime parameter
55
+   1.4. Set timer_interval parameter
56
+   1.5. dlgs_init usage
57
+   1.6. dlgs_update usage
58
+   1.7. dlgs_count usage
59
+   1.8. dlgs_tags_add usage
60
+   1.9. dlgs_tags_rm usage
61
+   1.10. dlgs_tags_count usage
62
+   1.11. dlgs.list usage
63
+   1.12. dlgs.briefing usage
64
+   1.13. dlgs.get usage
65
+   1.14. dlgs.get usage
66
+   1.15. dlgs.stats usage
49 67
 
50 68
 Chapter 1. Admin Guide
51 69
 
... ...
@@ -60,17 +78,26 @@ Chapter 1. Admin Guide
60 78
    3. Parameters
61 79
 
62 80
         3.1. active_lifetime (int)
63
-        3.2. timer_interval (int)
81
+        3.2. init_lifetime (int)
82
+        3.3. finish_lifetime (int)
83
+        3.4. timer_interval (int)
64 84
 
65 85
    4. Functions
66 86
 
67 87
         4.1. dlgs_init(src, dst, data)
68
-        4.2. dlgs_update(src)
88
+        4.2. dlgs_update()
89
+        4.3. dlgs_count(field, op, data)
90
+        4.4. dlgs_tags_add(vtag)
91
+        4.5. dlgs_tags_rm(vtag)
92
+        4.6. dlgs_tags_count(vtag)
69 93
 
70 94
    5. RPC Commands
71 95
 
72
-        5.1. rpc.list
73
-        5.2. rpc.stats
96
+        5.1. dlgs.list
97
+        5.2. dlgs.briefing
98
+        5.3. dlgs.get
99
+        5.4. dlgs.getall
100
+        5.5. dlgs.stats
74 101
 
75 102
 1. Overview
76 103
 
... ...
@@ -106,11 +133,14 @@ Chapter 1. Admin Guide
106 133
 3. Parameters
107 134
 
108 135
    3.1. active_lifetime (int)
109
-   3.2. timer_interval (int)
136
+   3.2. init_lifetime (int)
137
+   3.3. finish_lifetime (int)
138
+   3.4. timer_interval (int)
110 139
 
111 140
 3.1. active_lifetime (int)
112 141
 
113
-   The lifetime in seconds of a dialog in memory.
142
+   The lifetime in seconds of an active dialog in memory. A dialog is
143
+   considered active after the ACK of 200OK for INVITE.
114 144
 
115 145
    Default value is 10800 (3 hours).
116 146
 
... ...
@@ -119,14 +149,42 @@ Chapter 1. Admin Guide
119 149
 modparam("dlgs", "active_lifetime", 3600)
120 150
 ...
121 151
 
122
-3.2. timer_interval (int)
152
+3.2. init_lifetime (int)
153
+
154
+   The lifetime in seconds of an initial dialog in memory. A dialog is in
155
+   initial state from the moment of creation until it gets to active
156
+   state. If the dialog stays longer in the initial state, then it is
157
+   destroyed by the next timer cleanup.
158
+
159
+   Default value is 180 (3 minutes).
160
+
161
+   Example 1.2. Set init_lifetime parameter
162
+...
163
+modparam("dlgs", "init_lifetime", 240)
164
+...
165
+
166
+3.3. finish_lifetime (int)
167
+
168
+   The lifetime in seconds of a finished dialog in memory. A dialog is
169
+   finished if the initial INVITE was not answered or the BYE was
170
+   received. Once this lifetime passes, the dialog record is removed from
171
+   memory by the next timer cleanup.
172
+
173
+   Default value is 10 (seconds).
174
+
175
+   Example 1.3. Set finish_lifetime parameter
176
+...
177
+modparam("dlgs", "finish_lifetime", 20)
178
+...
179
+
180
+3.4. timer_interval (int)
123 181
 
124 182
    The value in secods to run the timer callback function for cleaning up
125 183
    dialogs past the lifetime limit.
126 184
 
127 185
    Default value is 30.
128 186
 
129
-   Example 1.2. Set timer_interval parameter
187
+   Example 1.4. Set timer_interval parameter
130 188
 ...
131 189
 modparam("dlgs", "timer_interval", 60)
132 190
 ...
... ...
@@ -134,18 +192,23 @@ modparam("dlgs", "timer_interval", 60)
134 192
 4. Functions
135 193
 
136 194
    4.1. dlgs_init(src, dst, data)
137
-   4.2. dlgs_update(src)
195
+   4.2. dlgs_update()
196
+   4.3. dlgs_count(field, op, data)
197
+   4.4. dlgs_tags_add(vtag)
198
+   4.5. dlgs_tags_rm(vtag)
199
+   4.6. dlgs_tags_count(vtag)
138 200
 
139 201
 4.1.  dlgs_init(src, dst, data)
140 202
 
141 203
    Start track the dialog corresponding to the current SIP message. It has
142 204
    to be used for INVITE messages.
143 205
 
144
-   This function can be used from ANY_ROUTE.
206
+   This function can be used from REQUEST_ROUTE, BRANCH_ROUTE,
207
+   ONREPLY_ROUTE, ONSEND_ROUTE.
145 208
 
146
-   Example 1.3. dlgs_init usage
209
+   Example 1.5. dlgs_init usage
147 210
 ...
148
-request_route {
211
+onsend_route {
149 212
     ...
150 213
     if(is_method("INVITE")) {
151 214
         dlgs_init("$fu", "$tu", "my data");
... ...
@@ -154,42 +217,163 @@ request_route {
154 217
 }
155 218
 ...
156 219
 
157
-4.2.  dlgs_update(src)
220
+4.2.  dlgs_update()
158 221
 
159
-   Update dialog state.
222
+   Update dialog state. It has to be used for SIP requests only, the SIP
223
+   responses are handled automatically.
160 224
 
161
-   This function can be used from ONSEND_ROUTE.
225
+   This function can be used from REQUEST_ROUTE, BRANCH_ROUTE,
226
+   ONSEND_ROUTE.
162 227
 
163
-   Example 1.4. dlgs_update usage
228
+   Example 1.6. dlgs_update usage
164 229
 ...
165
-onsend_route {
230
+request_route {
166 231
     ...
167
-    if(is_method("INVITE|ACK|BYE")) {
168
-        dlgs_init("$fu", "$tu", "my data");
232
+    if(is_method("ACK|BYE|CANCEL")) {
233
+        dlgs_update();
169 234
     }
170 235
     ...
171 236
 }
172 237
 ...
173 238
 
239
+4.3.  dlgs_count(field, op, data)
240
+
241
+   Return the number of dialogs matching the filter specified by the
242
+   parameters. It does not count the dialogs that are finished (not
243
+   answered or terminated with BYE).
244
+
245
+   The field parameter can be: 'src', 'dst', 'data' to specify what dialog
246
+   attribute has to be used for matching. It can be also 'any' to get the
247
+   count of all ongoing dialogs.
248
+
249
+   The op parameter can be: 'eq' - equal; 'ne' - not equal; 're' - regex;
250
+   'sw' - start with; 'fm' - fnmatch.
251
+
252
+   In case of error or no dialog matched, it returns -1 or other negative
253
+   (false) value.
254
+
255
+   This function can be used from ANY_ROUTE.
256
+
257
+   Example 1.7. dlgs_count usage
258
+...
259
+request_route {
260
+    ...
261
+    $var(count) = dlgs_count("src", "eq", "$fu");
262
+    if($var(count) > 0) {
263
+        # caller has ongoing dialogs
264
+    }
265
+    ...
266
+    $var(allcalls) = dlgs_count("any", "eq", "*");
267
+    if($var(allcalls) > 0) {
268
+        # there are ongoing dialogs
269
+    }
270
+    ...
271
+}
272
+...
273
+
274
+4.4.  dlgs_tags_add(vtag)
275
+
276
+   Add a tag to current dialog.
277
+
278
+   This function can be used from ANY_ROUTE.
279
+
280
+   Example 1.8. dlgs_tags_add usage
281
+...
282
+request_route {
283
+    ...
284
+    dlgs_tags_add("$si");
285
+    ...
286
+}
287
+...
288
+
289
+4.5.  dlgs_tags_rm(vtag)
290
+
291
+   Remove a tag from current dialog.
292
+
293
+   This function can be used from ANY_ROUTE.
294
+
295
+   Example 1.9. dlgs_tags_rm usage
296
+...
297
+request_route {
298
+    ...
299
+    dlgs_tags_rm("$si");
300
+    ...
301
+}
302
+...
303
+
304
+4.6.  dlgs_tags_count(vtag)
305
+
306
+   Count all tags for ongoing dialogs matching the parameter.
307
+
308
+   It returns -1 if no tag for ongoing dialogs is matched or there was an
309
+   error.
310
+
311
+   This function can be used from ANY_ROUTE.
312
+
313
+   Example 1.10. dlgs_tags_count usage
314
+...
315
+request_route {
316
+    ...
317
+    $var(tcount) = dlgs_tags_count("$si");
318
+    ...
319
+}
320
+...
321
+
174 322
 5. RPC Commands
175 323
 
176
-   5.1. rpc.list
177
-   5.2. rpc.stats
324
+   5.1. dlgs.list
325
+   5.2. dlgs.briefing
326
+   5.3. dlgs.get
327
+   5.4. dlgs.getall
328
+   5.5. dlgs.stats
178 329
 
179
-5.1.  rpc.list
330
+5.1.  dlgs.list
180 331
 
181 332
    List dialog records.
182 333
 
183
-   Example 1.5. dlgs.list usage
334
+   Example 1.11. dlgs.list usage
184 335
 ...
185 336
 kamctl rpc dlgs.list
186 337
 ...
187 338
 
188
-5.2.  rpc.stats
339
+5.2.  dlgs.briefing
340
+
341
+   List dialog records with fewer attributes per record.
342
+
343
+   Example 1.12. dlgs.briefing usage
344
+...
345
+kamctl rpc dlgs.briefing
346
+...
347
+
348
+5.3.  dlgs.get
349
+
350
+   Prototype: dlgs.get field op data
351
+
352
+   List first dialog record matching the filter. The parameters have the
353
+   same meaning like those for dlgs_count(...).
354
+
355
+   Example 1.13. dlgs.get usage
356
+...
357
+kamctl rpc dlgs.get src eq sip:alice@sipserver.com
358
+...
359
+
360
+5.4.  dlgs.getall
361
+
362
+   Prototype: dlgs.getall field op data
363
+
364
+   List all dialog records matching the filter. The parameters have the
365
+   same meaning like those for dlgs_count(...).
366
+
367
+   Example 1.14. dlgs.get usage
368
+...
369
+kamctl rpc dlgs.get src eq sip:alice@sipserver.com
370
+...
371
+
372
+5.5.  dlgs.stats
189 373
 
190 374
    Return dialog statistics.
191 375
 
192
-   Example 1.6. dlgs.stats usage
376
+   Example 1.15. dlgs.stats usage
193 377
 ...
194 378
 kamctl rpc dlgs.stats
195 379
 ...