Browse code

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

Kamailio Dev authored on 09/04/2021 14:16:14
Showing 1 changed files
... ...
@@ -9,7 +9,7 @@ Edited by
9 9
 
10 10
 Wolfgang Kampichler
11 11
 
12
-   Copyright © 2018-2020 Wolfgang Kampichler
12
+   Copyright © 2018-2021 Wolfgang Kampichler
13 13
      __________________________________________________________________
14 14
 
15 15
    Table of Contents
... ...
@@ -27,13 +27,20 @@ Wolfgang Kampichler
27 27
               3.1. exact_type (int)
28 28
               3.2. response_time (int)
29 29
               3.3. location_type (string)
30
-              3.4. geoheader_type (int)
31
-              3.5. geoheader_order (int)
30
+              3.4. post_request (int)
31
+              3.5. location_profile (int)
32
+              3.6. geoheader_type (int)
33
+              3.7. geoheader_order (int)
34
+              3.8. recursion (int)
35
+              3.9. verbose (int)
32 36
 
33 37
         4. Functions
34 38
 
35 39
               4.1. lost_held_query(con, [id,] pidf-lo, url, error)
36
-              4.2. lost_query(con, [pidf-lo, urn,] uri, name, error)
40
+              4.2. lost_held_dereference(url, rtime, rtype, pidf-lo,
41
+                      error)
42
+
43
+              4.3. lost_query(con, [pidf-lo, urn,] uri, name, error)
37 44
 
38 45
         5. Counters
39 46
         6. Remarks
... ...
@@ -43,10 +50,15 @@ Wolfgang Kampichler
43 50
    1.1. Set exact_type parameter
44 51
    1.2. Set response_time parameter
45 52
    1.3. Set location_type parameter
46
-   1.4. Set geoheader_type parameter
47
-   1.5. Set geoheader_order parameter
48
-   1.6. lost_held_query() usage
49
-   1.7. lost() usage
53
+   1.4. Set post_request parameter
54
+   1.5. Set location_profile parameter
55
+   1.6. Set geoheader_type parameter
56
+   1.7. Set geoheader_order parameter
57
+   1.8. Set recursion parameter
58
+   1.9. Set verbose parameter
59
+   1.10. lost_held_query() usage
60
+   1.11. lost_held_dereference() usage
61
+   1.12. lost() usage
50 62
 
51 63
 Chapter 1. Admin Guide
52 64
 
... ...
@@ -63,13 +75,18 @@ Chapter 1. Admin Guide
63 75
         3.1. exact_type (int)
64 76
         3.2. response_time (int)
65 77
         3.3. location_type (string)
66
-        3.4. geoheader_type (int)
67
-        3.5. geoheader_order (int)
78
+        3.4. post_request (int)
79
+        3.5. location_profile (int)
80
+        3.6. geoheader_type (int)
81
+        3.7. geoheader_order (int)
82
+        3.8. recursion (int)
83
+        3.9. verbose (int)
68 84
 
69 85
    4. Functions
70 86
 
71 87
         4.1. lost_held_query(con, [id,] pidf-lo, url, error)
72
-        4.2. lost_query(con, [pidf-lo, urn,] uri, name, error)
88
+        4.2. lost_held_dereference(url, rtime, rtype, pidf-lo, error)
89
+        4.3. lost_query(con, [pidf-lo, urn,] uri, name, error)
73 90
 
74 91
    5. Counters
75 92
    6. Remarks
... ...
@@ -98,6 +115,13 @@ Chapter 1. Admin Guide
98 115
    parsed and represented as PIDF-LO and location URI to dereference
99 116
    location via HTTP(S).
100 117
 
118
+   The function lost_held_dereference allows Kamailio to assemble a HELD
119
+   dereference request as defined in RFC6155
120
+   (https://tools.ietf.org/html/rfc6753) to dereference location
121
+   information represented as PIDF-LO for a given URL. Required parameters
122
+   are an URL, responseTime, and responseType. The response is represented
123
+   as PIDF-LO.
124
+
101 125
    The function lost_query allows Kamailio to assemble a LOST findService
102 126
    request as defined in RFC5222 (https://tools.ietf.org/html/rfc5255) to
103 127
    query routing information for a given (geodetic or civic) location and
... ...
@@ -137,8 +161,12 @@ Chapter 1. Admin Guide
137 161
    3.1. exact_type (int)
138 162
    3.2. response_time (int)
139 163
    3.3. location_type (string)
140
-   3.4. geoheader_type (int)
141
-   3.5. geoheader_order (int)
164
+   3.4. post_request (int)
165
+   3.5. location_profile (int)
166
+   3.6. geoheader_type (int)
167
+   3.7. geoheader_order (int)
168
+   3.8. recursion (int)
169
+   3.9. verbose (int)
142 170
 
143 171
    Besides parameters listed, this module uses http_client therefore
144 172
    according parameters may apply.
... ...
@@ -161,14 +189,15 @@ Chapter 1. Admin Guide
161 189
    A time value indicating to the location server how long the client is
162 190
    prepared to wait for a response.
163 191
 
164
-   The value is expressed as a non-negative integer in units of
192
+   The value is expressed as integer, either -1 'emergencyDispatch', 0
193
+   'emergencyRouting', a non-negative integer (>0) in units of
165 194
    milliseconds. Note: The time value is indicative only.
166 195
 
167
-   Default: 0 (response time not set)
196
+   Default: 0 ('emergencyRouting')
168 197
 
169 198
    Example 1.2. Set response_time parameter
170 199
     ...
171
-    modparam("lost", "response_time", 5000)
200
+    modparam("lost", "response_time", 0)
172 201
     ...
173 202
 
174 203
 3.3. location_type (string)
... ...
@@ -187,10 +216,41 @@ Chapter 1. Admin Guide
187 216
 
188 217
    Example 1.3. Set location_type parameter
189 218
     ...
190
-    modparam("lost", "location_type, "civic geodetic locationURI")
219
+    modparam("lost", "location_type", "civic geodetic locationURI")
191 220
     ...
192 221
 
193
-3.4. geoheader_type (int)
222
+3.4. post_request (int)
223
+
224
+   Dereferencing the location can be done using either the HTTP GET or
225
+   POST method. This parameter globally defines whether only HTTP POST
226
+   method should be used. Values are 0 (GET) or 1 (POST).
227
+
228
+   Default: 0 (GET)
229
+
230
+   Example 1.4. Set post_request parameter
231
+    ...
232
+    modparam("lost", "post_request", 1)
233
+    ...
234
+
235
+3.5. location_profile (int)
236
+
237
+   A Presence Information Data Format Location Object (PIDF-LO) may
238
+   contain geodetic or civic location profile or combinations. A LoST
239
+   findService contains only one location, which is selected via this
240
+   parameter as follows:
241
+     * 0 - takes the first location of any type
242
+     * 1 - takes the last last of any type
243
+     * 2 - takes the first geodetic location
244
+     * 3 - takes the first civic location
245
+
246
+   Default: 0 (first).
247
+
248
+   Example 1.5. Set location_profile parameter
249
+    ...
250
+    modparam("lost", "location_profile, 2)
251
+    ...
252
+
253
+3.6. geoheader_type (int)
194 254
 
195 255
    A Geolocation header may include a list of locationValues pointing to
196 256
    either a Presence Information Data Format Location Object (PIDF-LO) in
... ...
@@ -205,12 +265,12 @@ Chapter 1. Admin Guide
205 265
 
206 266
    Default: 0 (any)
207 267
 
208
-   Example 1.4. Set geoheader_type parameter
268
+   Example 1.6. Set geoheader_type parameter
209 269
     ...
210 270
     modparam("lost", "geoheader_type", 1)
211 271
     ...
212 272
 
213
-3.5. geoheader_order (int)
273
+3.7. geoheader_order (int)
214 274
 
215 275
    A Geolocation header may include a list of locationValues. This
216 276
    parameter sets the order of the URI used to retrieve location
... ...
@@ -219,15 +279,51 @@ Chapter 1. Admin Guide
219 279
 
220 280
    Default: 0 (first)
221 281
 
222
-   Example 1.5. Set geoheader_order parameter
282
+   Example 1.7. Set geoheader_order parameter
223 283
     ...
224 284
     modparam("lost", "geoheader_order", 0)
225 285
     ...
226 286
 
287
+3.8. recursion (int)
288
+
289
+   A Geolocation header may include a list of locationValues. This
290
+   parameter sets the order of the URI used to retrieve location
291
+   information, either the first element of a certain type or the last.
292
+   Values are 0 (first) or 1 (last).
293
+
294
+   Default: 1 (allowed)
295
+
296
+   Example 1.8. Set recursion parameter
297
+    ...
298
+    modparam("lost", "recursion", 0)
299
+    ...
300
+
301
+3.9. verbose (int)
302
+
303
+   Detailed output of LoST findService, redirect or error response as
304
+   shown below. Values are 0 (disabled) or 1 (enabled).
305
+    ### LOST expires:   [2031-01-27T14:54:21+00:00]
306
+    ### LOST lastUpdated:       [2021-01-29T14:54:21+00:00]
307
+    ### LOST source:    [ecrf.demo.gridgears.xx]
308
+    ### LOST sourceId:  [06ac5b1c-d6c8-42bd-a667-5d1b90bb3d95]
309
+    ### LOST displayName:       [Polizeinotruf (de)]
310
+    ### LOST serviceNumber:     [112]
311
+    ### LOST service:   [urn:service:sos]
312
+    ### LOST uri:       [sip:112@demo.dec112.xx]
313
+    ### LOST via:       [ecrf.demo.gridgears.xx]
314
+
315
+   Default: 0
316
+
317
+   Example 1.9. Set verbose parameter
318
+    ...
319
+    modparam("lost", "verbose", 1)
320
+    ...
321
+
227 322
 4. Functions
228 323
 
229 324
    4.1. lost_held_query(con, [id,] pidf-lo, url, error)
230
-   4.2. lost_query(con, [pidf-lo, urn,] uri, name, error)
325
+   4.2. lost_held_dereference(url, rtime, rtype, pidf-lo, error)
326
+   4.3. lost_query(con, [pidf-lo, urn,] uri, name, error)
231 327
 
232 328
 4.1.  lost_held_query(con, [id,] pidf-lo, url, error)
233 329
 
... ...
@@ -242,8 +338,7 @@ Chapter 1. Admin Guide
242 338
        response - this reference may be added as Geolocation header value
243 339
        and forwarded downstream. Note: to work properly, it is required to
244 340
        include "locationURI" in the location_type parameter.
245
-     * error - any error code returned in the HELD locationRequest
246
-       response
341
+     * error - any error code returned in the HELD response
247 342
 
248 343
    The return value is 200 on success, 400 if an internal error occured,
249 344
    or 500 if an error code is returned in the HELD locationRequest
... ...
@@ -252,7 +347,7 @@ Chapter 1. Admin Guide
252 347
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
253 348
    FAILURE_ROUTE, and BRANCH_ROUTE.
254 349
 
255
-   Example 1.6. lost_held_query() usage
350
+   Example 1.10. lost_held_query() usage
256 351
 ...
257 352
 modparam("http_client", "httpcon", "heldsrv=>http://service.org/api/held");
258 353
 ...
... ...
@@ -268,7 +363,38 @@ xlog("L_INFO", "HELD locationRequest: Result code $var(res)\nUrl: $var(url)\n$va
268 363
 r(pidf)\n");
269 364
 ...
270 365
 
271
-4.2.  lost_query(con, [pidf-lo, urn,] uri, name, error)
366
+4.2.  lost_held_dereference(url, rtime, rtype, pidf-lo, error)
367
+
368
+   Sends a HELD POST locationRequest to a given URL. Attributes are
369
+   responseTime and resposeType. The locationType property "exact" is set
370
+   to "false".
371
+     * url - a URL received via Geolocation header to dereference location
372
+     * rtime - the response time as defined in Section 3.2, “response_time
373
+       (int)”
374
+     * rtype - the response type (location) as defined in Section 3.3,
375
+       “location_type (string)”
376
+     * pidf-lo - the PIDF-LO returned in the HELD locationRequest response
377
+     * error - any error code returned in the HELD response
378
+
379
+   The return value is 200 on success, 400 if an internal error occured,
380
+   or 500 if an error code is returned in the HELD response.
381
+
382
+   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
383
+   FAILURE_ROUTE, and BRANCH_ROUTE.
384
+
385
+   Example 1.11. lost_held_dereference() usage
386
+...
387
+# HELD location dereference
388
+if ($hdr(Geolocation)=~"^<http.*$") {
389
+    $var(url) = $(hdr(Geolocation){s.select,0,;});
390
+    $var(res) = lost_held_dereference("$(var(url){s.unbracket})", "emergencyDisp
391
+atch", "civic geodetic", "$var(pidf)", "$var(err)");
392
+    xlog("L_INFO", "HELD location dereference: Result code $var(res)\n$var(pidf)
393
+");
394
+...
395
+}
396
+
397
+4.3.  lost_query(con, [pidf-lo, urn,] uri, name, error)
272 398
 
273 399
    Sends a LOST findService request to a given connection. PIDF-LO and URN
274 400
    are either specified, or, if omitted, parsed from the message body
... ...
@@ -288,7 +414,7 @@ r(pidf)\n");
288 414
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
289 415
    FAILURE_ROUTE, and BRANCH_ROUTE.
290 416
 
291
-   Example 1.7. lost() usage
417
+   Example 1.12. lost() usage
292 418
 ...
293 419
 modparam("http_client", "httpcon", "heldsrv=>http://service.org/api/held");
294 420
 modparam("http_client", "httpcon", "lostsrv=>http://service.org/api/lost");