Browse code

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

Kamailio Dev authored on 03/05/2021 09:16:14
Showing 1 changed files
... ...
@@ -376,8 +376,15 @@ r(pidf)\n");
376 376
      * pidf-lo - the PIDF-LO returned in the HELD locationRequest response
377 377
      * error - any error code returned in the HELD response
378 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.
379
+   The return value is 200..203 on success, 400 if an internal error
380
+   occured, or 500 if an error code is returned in the HELD response.
381
+   Success codes in detail are as follows:
382
+     * 200 - received 200 OK, but neither location-info nor locationURI
383
+       element found
384
+     * 201 - received 200 OK with locationURI (aka Location-by-Reference)
385
+     * 202 - received 200 OK with location-info element (aka
386
+       Location-by-Value)
387
+     * 203 - received 200 OK with location-info and locationURI element
381 388
 
382 389
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
383 390
    FAILURE_ROUTE, and BRANCH_ROUTE.
Browse code

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

Kamailio Dev authored on 19/04/2021 08:16:20
Showing 1 changed files
... ...
@@ -239,7 +239,7 @@ Chapter 1. Admin Guide
239 239
    findService contains only one location, which is selected via this
240 240
    parameter as follows:
241 241
      * 0 - takes the first location of any type
242
-     * 1 - takes the last last of any type
242
+     * 1 - takes the last location of any type
243 243
      * 2 - takes the first geodetic location
244 244
      * 3 - takes the first civic location
245 245
 
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");
Browse code

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

Kamailio Dev authored on 12/01/2021 11:01:20
Showing 1 changed files
... ...
@@ -27,6 +27,8 @@ 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 32
 
31 33
         4. Functions
32 34
 
... ...
@@ -41,8 +43,10 @@ Wolfgang Kampichler
41 43
    1.1. Set exact_type parameter
42 44
    1.2. Set response_time parameter
43 45
    1.3. Set location_type parameter
44
-   1.4. lost_held_query() usage
45
-   1.5. lost() usage
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
46 50
 
47 51
 Chapter 1. Admin Guide
48 52
 
... ...
@@ -59,6 +63,8 @@ Chapter 1. Admin Guide
59 63
         3.1. exact_type (int)
60 64
         3.2. response_time (int)
61 65
         3.3. location_type (string)
66
+        3.4. geoheader_type (int)
67
+        3.5. geoheader_order (int)
62 68
 
63 69
    4. Functions
64 70
 
... ...
@@ -131,6 +137,8 @@ Chapter 1. Admin Guide
131 137
    3.1. exact_type (int)
132 138
    3.2. response_time (int)
133 139
    3.3. location_type (string)
140
+   3.4. geoheader_type (int)
141
+   3.5. geoheader_order (int)
134 142
 
135 143
    Besides parameters listed, this module uses http_client therefore
136 144
    according parameters may apply.
... ...
@@ -182,6 +190,40 @@ Chapter 1. Admin Guide
182 190
     modparam("lost", "location_type, "civic geodetic locationURI")
183 191
     ...
184 192
 
193
+3.4. geoheader_type (int)
194
+
195
+   A Geolocation header may include a list of locationValues pointing to
196
+   either a Presence Information Data Format Location Object (PIDF-LO) in
197
+   the SIP body using a content-indirection (cid:) URI per RFC4483
198
+   (https://tools.ietf.org/html/rfc4483), or an http(s) URI pointing to an
199
+   external source. This parameter supports filtering of the following
200
+   types:
201
+     * 0 (any) - any URI (first or last)
202
+     * 1 (cid) - cid URI (aka Location-by-Value)
203
+     * 2 (http) - http URI (aka Location-by-Reference)
204
+     * 3 (https) - https URI (aka Location-by-Reference)
205
+
206
+   Default: 0 (any)
207
+
208
+   Example 1.4. Set geoheader_type parameter
209
+    ...
210
+    modparam("lost", "geoheader_type", 1)
211
+    ...
212
+
213
+3.5. geoheader_order (int)
214
+
215
+   A Geolocation header may include a list of locationValues. This
216
+   parameter sets the order of the URI used to retrieve location
217
+   information, either the first element of a certain type or the last.
218
+   Values are 0 (first) or 1 (last).
219
+
220
+   Default: 0 (first)
221
+
222
+   Example 1.5. Set geoheader_order parameter
223
+    ...
224
+    modparam("lost", "geoheader_order", 0)
225
+    ...
226
+
185 227
 4. Functions
186 228
 
187 229
    4.1. lost_held_query(con, [id,] pidf-lo, url, error)
... ...
@@ -210,7 +252,7 @@ Chapter 1. Admin Guide
210 252
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
211 253
    FAILURE_ROUTE, and BRANCH_ROUTE.
212 254
 
213
-   Example 1.4. lost_held_query() usage
255
+   Example 1.6. lost_held_query() usage
214 256
 ...
215 257
 modparam("http_client", "httpcon", "heldsrv=>http://service.org/api/held");
216 258
 ...
... ...
@@ -246,7 +288,7 @@ r(pidf)\n");
246 288
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
247 289
    FAILURE_ROUTE, and BRANCH_ROUTE.
248 290
 
249
-   Example 1.5. lost() usage
291
+   Example 1.7. lost() usage
250 292
 ...
251 293
 modparam("http_client", "httpcon", "heldsrv=>http://service.org/api/held");
252 294
 modparam("http_client", "httpcon", "lostsrv=>http://service.org/api/lost");
... ...
@@ -307,3 +349,6 @@ var(name)\n");
307 349
    Note: to test the module with a mapping service (LOST), an API key may
308 350
    be requested under the following link (search for "GET ACCESS"):
309 351
    https://gridgears.at/.
352
+
353
+   Note: in case modparam "geoheader_type" is set to 2 (http), the module
354
+   may use 3 (https) as fallback and vice versa.
Browse code

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

Kamailio Dev authored on 30/11/2020 08:16:16
Showing 1 changed files
... ...
@@ -179,7 +179,7 @@ Chapter 1. Admin Guide
179 179
 
180 180
    Example 1.3. Set location_type parameter
181 181
     ...
182
-    modparam("http_client", "location_type, "civic geodetic locationURI")
182
+    modparam("lost", "location_type, "civic geodetic locationURI")
183 183
     ...
184 184
 
185 185
 4. Functions
... ...
@@ -221,7 +221,7 @@ $var(err)");
221 221
 xlog("L_INFO", "HELD locationRequest: Result code $var(res)\nUrl: $var(url)\n$va
222 222
 r(pidf)");
223 223
 ...
224
-$var(res) = lost_held_query("heldsrv", "$var(pidf)", "$var(url)"", "$var(err)");
224
+$var(res) = lost_held_query("heldsrv", "$var(pidf)", "$var(url)", "$var(err)");
225 225
 xlog("L_INFO", "HELD locationRequest: Result code $var(res)\nUrl: $var(url)\n$va
226 226
 r(pidf)\n");
227 227
 ...
Browse code

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

Kamailio Dev authored on 08/07/2020 20:46:11
Showing 1 changed files
... ...
@@ -9,7 +9,7 @@ Edited by
9 9
 
10 10
 Wolfgang Kampichler
11 11
 
12
-   Copyright © 20018-2020 Wolfgang Kampichler
12
+   Copyright © 2018-2020 Wolfgang Kampichler
13 13
      __________________________________________________________________
14 14
 
15 15
    Table of Contents
... ...
@@ -198,7 +198,7 @@ Chapter 1. Admin Guide
198 198
      * pidf-lo - the PIDF-LO returned in the HELD locationRequest response
199 199
      * url - the location reference returned in the HELD locationRequest
200 200
        response - this reference may be added as Geolocation header value
201
-       and forwarded downstream Note: to work properly, it is required to
201
+       and forwarded downstream. Note: to work properly, it is required to
202 202
        include "locationURI" in the location_type parameter.
203 203
      * error - any error code returned in the HELD locationRequest
204 204
        response
... ...
@@ -293,7 +293,7 @@ var(name)\n");
293 293
    standard libcurl-7.19.7-52 has a memory leak. To fix this memory,
294 294
    install libcurl from city-fan repository. More details at:
295 295
    https://www.digitalocean.com/community/questions/how-to-upgrade-curl-in
296
-   -centos6
296
+   -centos6.
297 297
 
298 298
    Note: http_client_query exported by the http_client API returns by
299 299
    default the first line of the HTTP response, but the lost module
... ...
@@ -303,3 +303,7 @@ var(name)\n");
303 303
    http_client module parameter query_result to 0. More details at:
304 304
    https://www.kamailio.org/docs/modules/devel/modules/http_client.html#ht
305 305
    tp_client.p.query_result.
306
+
307
+   Note: to test the module with a mapping service (LOST), an API key may
308
+   be requested under the following link (search for "GET ACCESS"):
309
+   https://gridgears.at/.
Browse code

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

Kamailio Dev authored on 26/03/2020 21:46:08
Showing 1 changed files
... ...
@@ -198,7 +198,8 @@ Chapter 1. Admin Guide
198 198
      * pidf-lo - the PIDF-LO returned in the HELD locationRequest response
199 199
      * url - the location reference returned in the HELD locationRequest
200 200
        response - this reference may be added as Geolocation header value
201
-       and forwarded downstream
201
+       and forwarded downstream Note: to work properly, it is required to
202
+       include "locationURI" in the location_type parameter.
202 203
      * error - any error code returned in the HELD locationRequest
203 204
        response
204 205
 
Browse code

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

Kamailio Dev authored on 23/03/2020 22:01:10
Showing 1 changed files
... ...
@@ -23,6 +23,11 @@ Wolfgang Kampichler
23 23
               2.2. External Libraries or Applications
24 24
 
25 25
         3. Parameters
26
+
27
+              3.1. exact_type (int)
28
+              3.2. response_time (int)
29
+              3.3. location_type (string)
30
+
26 31
         4. Functions
27 32
 
28 33
               4.1. lost_held_query(con, [id,] pidf-lo, url, error)
... ...
@@ -33,8 +38,11 @@ Wolfgang Kampichler
33 38
 
34 39
    List of Examples
35 40
 
36
-   1.1. lost_held_query() usage
37
-   1.2. lost() usage
41
+   1.1. Set exact_type parameter
42
+   1.2. Set response_time parameter
43
+   1.3. Set location_type parameter
44
+   1.4. lost_held_query() usage
45
+   1.5. lost() usage
38 46
 
39 47
 Chapter 1. Admin Guide
40 48
 
... ...
@@ -47,6 +55,11 @@ Chapter 1. Admin Guide
47 55
         2.2. External Libraries or Applications
48 56
 
49 57
    3. Parameters
58
+
59
+        3.1. exact_type (int)
60
+        3.2. response_time (int)
61
+        3.3. location_type (string)
62
+
50 63
    4. Functions
51 64
 
52 65
         4.1. lost_held_query(con, [id,] pidf-lo, url, error)
... ...
@@ -84,12 +97,12 @@ Chapter 1. Admin Guide
84 97
    query routing information for a given (geodetic or civic) location and
85 98
    a service URN. Both, PIDF-LO and service URN may be provided as
86 99
    function parameter, or are taken from the request message if
87
-   applicable. The findServiceResponse is parsed and represented asdisplay
88
-   name and SIP URI typically used as next hop in a Route header.
100
+   applicable. The findServiceResponse is parsed and represented as
101
+   display name and SIP URI typically used as next hop in a Route header.
89 102
 
90 103
    The http_client module use the CURL library setting up connections. The
91
-   CURL library by default use the system configured DNS resolvers, not
92
-   the Kamailio resolver.
104
+   CURL library by default use the system configured DNS resolver, not the
105
+   Kamailio resolver.
93 106
 
94 107
    The module is limited to using HTTP and HTTPS protocols.
95 108
 
... ...
@@ -115,9 +128,60 @@ Chapter 1. Admin Guide
115 128
 
116 129
 3. Parameters
117 130
 
118
-   This module has no specific paramater but uses http_client therfore
131
+   3.1. exact_type (int)
132
+   3.2. response_time (int)
133
+   3.3. location_type (string)
134
+
135
+   Besides parameters listed, this module uses http_client therefore
119 136
    according parameters may apply.
120 137
 
138
+3.1. exact_type (int)
139
+
140
+   Indicates to the location server that the contents of the
141
+   "location_type" parameter must be strictly followed. Values are 0
142
+   (false) or 1 (true).
143
+
144
+   Default: 0 (false)
145
+
146
+   Example 1.1. Set exact_type parameter
147
+    ...
148
+    modparam("lost", "exact_type", 1)
149
+    ...
150
+
151
+3.2. response_time (int)
152
+
153
+   A time value indicating to the location server how long the client is
154
+   prepared to wait for a response.
155
+
156
+   The value is expressed as a non-negative integer in units of
157
+   milliseconds. Note: The time value is indicative only.
158
+
159
+   Default: 0 (response time not set)
160
+
161
+   Example 1.2. Set response_time parameter
162
+    ...
163
+    modparam("lost", "response_time", 5000)
164
+    ...
165
+
166
+3.3. location_type (string)
167
+
168
+   The "locationType" element contains a list of types that are requested.
169
+   Values are "any", "geodetic", "civic" or "locationURI" and
170
+   combinations.
171
+     * any - returns location information in all forms available
172
+     * geodetic - returns a location by value in the form of a geodetic
173
+       location
174
+     * civic - returns a location by value in the form of a civic address
175
+     * locationURI - returns a set of location URIs (location by
176
+       reference)
177
+
178
+   Default: "geodetic locationURI".
179
+
180
+   Example 1.3. Set location_type parameter
181
+    ...
182
+    modparam("http_client", "location_type, "civic geodetic locationURI")
183
+    ...
184
+
121 185
 4. Functions
122 186
 
123 187
    4.1. lost_held_query(con, [id,] pidf-lo, url, error)
... ...
@@ -128,8 +192,8 @@ Chapter 1. Admin Guide
128 192
    Sends a HELD locationRequest to a given connection. The device identity
129 193
    is either specified, or the P-A-I header value, or the From header
130 194
    value.
131
-     * con - the name of an existing HTTP connection, definied by a
132
-       httpcon modparam
195
+     * con - the name of an existing HTTP connection, defined by a httpcon
196
+       modparam
133 197
      * id - the device id used in the HELD locationRequest
134 198
      * pidf-lo - the PIDF-LO returned in the HELD locationRequest response
135 199
      * url - the location reference returned in the HELD locationRequest
... ...
@@ -145,7 +209,7 @@ Chapter 1. Admin Guide
145 209
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
146 210
    FAILURE_ROUTE, and BRANCH_ROUTE.
147 211
 
148
-   Example 1.1. lost_held_query() usage
212
+   Example 1.4. lost_held_query() usage
149 213
 ...
150 214
 modparam("http_client", "httpcon", "heldsrv=>http://service.org/api/held");
151 215
 ...
... ...
@@ -167,7 +231,7 @@ r(pidf)\n");
167 231
    are either specified, or, if omitted, parsed from the message body
168 232
    (PIDF-LO) and request line (URN). Either "pidf-lo" or "urn" can be set
169 233
    to an empty string in order to be ignored.
170
-     * con - the name of an existing HTTP connection definied by a httpcon
234
+     * con - the name of an existing HTTP connection defined by a httpcon
171 235
        modparam
172 236
      * pidf-lo - the PIDF-LO used to create the LOST findService request
173 237
      * urn - the URN used to create the LOST findService request
... ...
@@ -181,7 +245,7 @@ r(pidf)\n");
181 245
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
182 246
    FAILURE_ROUTE, and BRANCH_ROUTE.
183 247
 
184
-   Example 1.2. lost() usage
248
+   Example 1.5. lost() usage
185 249
 ...
186 250
 modparam("http_client", "httpcon", "heldsrv=>http://service.org/api/held");
187 251
 modparam("http_client", "httpcon", "lostsrv=>http://service.org/api/lost");
... ...
@@ -231,10 +295,10 @@ var(name)\n");
231 295
    -centos6
232 296
 
233 297
    Note: http_client_query exported by the http_client API returns by
234
-   default the first line of the HTTP response (query_params.oneline = 1),
235
-   but the lost module requires the complete response message, which
236
-   requires query_params.oneline set to 0. In the case lost_query is used
237
-   with the default http_client API, dereferencing location via HTTP
238
-   provided with the Geolocation header causes an error. Therefore, to
239
-   work properly, it requires to set http_client module parameter
240
-   query_result to 0.
298
+   default the first line of the HTTP response, but the lost module
299
+   requires the complete response message, otherwise dereferencing
300
+   location via the HTTP URL provided with the Geolocation header causes
301
+   an error. Therefore, to work properly, it is required to set the
302
+   http_client module parameter query_result to 0. More details at:
303
+   https://www.kamailio.org/docs/modules/devel/modules/http_client.html#ht
304
+   tp_client.p.query_result.
Browse code

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

Kamailio Dev authored on 08/03/2020 08:46:21
Showing 1 changed files
... ...
@@ -9,7 +9,7 @@ Edited by
9 9
 
10 10
 Wolfgang Kampichler
11 11
 
12
-   Copyright © 20018-2019 Wolfgang Kampichler
12
+   Copyright © 20018-2020 Wolfgang Kampichler
13 13
      __________________________________________________________________
14 14
 
15 15
    Table of Contents
... ...
@@ -60,9 +60,9 @@ Chapter 1. Admin Guide
60 60
    SIP requests may be forwarded based on a location provided with the
61 61
    request or retrieved from a specific location server using an identity
62 62
    (HELD). This module implements the basic functionality to get or parse
63
-   location information and to query a mapping service (LOST) in order to
64
-   get next hop based on location and service urn either specified or
65
-   provided with the request.
63
+   location information (civic and geodetic) and to query a mapping
64
+   service (LOST) in order to get next hop based on location and service
65
+   urn either specified or provided with the request.
66 66
 
67 67
    This module implements protocol functions that use the http_client api
68 68
    to fetch data from external LOST and HELD servers. The module is using
... ...
@@ -81,11 +81,11 @@ Chapter 1. Admin Guide
81 81
 
82 82
    The function lost_query allows Kamailio to assemble a LOST findService
83 83
    request as defined in RFC5222 (https://tools.ietf.org/html/rfc5255) to
84
-   query routing information for a given (geodetic) location and a service
85
-   URN. Both, PIDF-LO and service URN may be provided as function
86
-   parameter, or are taken from the request message if applicable. The
87
-   findServiceResponse is parsed and represented asdisplay name and SIP
88
-   URI typically used as next hop in a Route header.
84
+   query routing information for a given (geodetic or civic) location and
85
+   a service URN. Both, PIDF-LO and service URN may be provided as
86
+   function parameter, or are taken from the request message if
87
+   applicable. The findServiceResponse is parsed and represented asdisplay
88
+   name and SIP URI typically used as next hop in a Route header.
89 89
 
90 90
    The http_client module use the CURL library setting up connections. The
91 91
    CURL library by default use the system configured DNS resolvers, not
... ...
@@ -196,24 +196,24 @@ $var(id) = "urn:service:sos";
196 196
 $var(res) = lost_query("lostsrv", "$var(pidf)", "$var(urn)", "$var(uri)", "$var(
197 197
 name)", "$var(err)");
198 198
 xlog("L_INFO", "LOST findService: Result code $var(res)\nUri: $var(uri)\nName: $
199
-var(uri)\n");
199
+var(name)\n");
200 200
 ...
201 201
 # LOST findService request - pidf-lo as parameter, urn taken from request line
202 202
 $var(res) = lost_query("lostsrv", "$var(pidf)", "", "$var(uri)", "$var(name)", "
203 203
 $var(err)");
204 204
 xlog("L_INFO", "LOST findService: Result code $var(res)\nUri: $var(uri)\nName: $
205
-var(uri)\n");
205
+var(name)\n");
206 206
 ...
207 207
 # LOST findService request - urn as parameter, pidf-lo taken from message body
208 208
 $var(res) = lost_query("lostsrv", "", "$var(urn)", "$var(uri)", "$var(name)", "$
209 209
 var(err)");
210 210
 xlog("L_INFO", "LOST findService: Result code $var(res)\nUri: $var(uri)\nName: $
211
-var(uri)\n");
211
+var(name\n");
212 212
 ...
213 213
 # LOST findService request - pidf-lo and urn taken from message
214 214
 $var(res) = lost_query("lostsrv", "$var(uri)", "$var(name)", "$var(err)");
215 215
 xlog("L_INFO", "LOST findService: Result code $var(res)\nUri: $var(uri)\nName: $
216
-var(uri)\n");
216
+var(name)\n");
217 217
 ...
218 218
 
219 219
 5. Counters
... ...
@@ -236,5 +236,5 @@ var(uri)\n");
236 236
    requires query_params.oneline set to 0. In the case lost_query is used
237 237
    with the default http_client API, dereferencing location via HTTP
238 238
    provided with the Geolocation header causes an error. Therefore, to
239
-   work properlu=y, it requires to set http_client module parameter
239
+   work properly, it requires to set http_client module parameter
240 240
    query_result to 0.
Browse code

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

Kamailio Dev authored on 19/08/2019 09:47:13
Showing 1 changed files
... ...
@@ -230,9 +230,11 @@ var(uri)\n");
230 230
    https://www.digitalocean.com/community/questions/how-to-upgrade-curl-in
231 231
    -centos6
232 232
 
233
-   Note: http_client_query exported by the http_client API returns the
234
-   first line of the HTTP response (query_params.oneline = 1), but the
235
-   lost module requires the complete response message, which requires
236
-   query_params.oneline set to 0. In the case lost_query is used with the
237
-   default http_client API, dereferencing location via HTTP provided with
238
-   the Geolocation header causes an error.
233
+   Note: http_client_query exported by the http_client API returns by
234
+   default the first line of the HTTP response (query_params.oneline = 1),
235
+   but the lost module requires the complete response message, which
236
+   requires query_params.oneline set to 0. In the case lost_query is used
237
+   with the default http_client API, dereferencing location via HTTP
238
+   provided with the Geolocation header causes an error. Therefore, to
239
+   work properlu=y, it requires to set http_client module parameter
240
+   query_result to 0.
Browse code

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

Kamailio Dev authored on 16/08/2019 21:01:36
Showing 1 changed files
... ...
@@ -1,4 +1,3 @@
1
-
2 1
 LOST Module
3 2
 
4 3
 Wolfgang Kampichler
... ...
@@ -219,7 +218,7 @@ var(uri)\n");
219 218
 
220 219
 5. Counters
221 220
 
222
-   This module has no specific counters but uses http_client therfore
221
+   This module has no specific counters but uses http_client therefore
223 222
    according counters may apply.
224 223
 
225 224
 6. Remarks
Browse code

lost: initial checkin of README file

Henning Westerholt authored on 16/08/2019 06:09:52
Showing 1 changed files
1 1
new file mode 100644
... ...
@@ -0,0 +1,239 @@
1
+
2
+LOST Module
3
+
4
+Wolfgang Kampichler
5
+
6
+   Frequentis AG
7
+   DEC112 (funded by netidee)
8
+
9
+Edited by
10
+
11
+Wolfgang Kampichler
12
+
13
+   Copyright © 20018-2019 Wolfgang Kampichler
14
+     __________________________________________________________________
15
+
16
+   Table of Contents
17
+
18
+   1. Admin Guide
19
+
20
+        1. Overview
21
+        2. Dependencies
22
+
23
+              2.1. Kamailio Modules
24
+              2.2. External Libraries or Applications
25
+
26
+        3. Parameters
27
+        4. Functions
28
+
29
+              4.1. lost_held_query(con, [id,] pidf-lo, url, error)
30
+              4.2. lost_query(con, [pidf-lo, urn,] uri, name, error)
31
+
32
+        5. Counters
33
+        6. Remarks
34
+
35
+   List of Examples
36
+
37
+   1.1. lost_held_query() usage
38
+   1.2. lost() usage
39
+
40
+Chapter 1. Admin Guide
41
+
42
+   Table of Contents
43
+
44
+   1. Overview
45
+   2. Dependencies
46
+
47
+        2.1. Kamailio Modules
48
+        2.2. External Libraries or Applications
49
+
50
+   3. Parameters
51
+   4. Functions
52
+
53
+        4.1. lost_held_query(con, [id,] pidf-lo, url, error)
54
+        4.2. lost_query(con, [pidf-lo, urn,] uri, name, error)
55
+
56
+   5. Counters
57
+   6. Remarks
58
+
59
+1. Overview
60
+
61
+   SIP requests may be forwarded based on a location provided with the
62
+   request or retrieved from a specific location server using an identity
63
+   (HELD). This module implements the basic functionality to get or parse
64
+   location information and to query a mapping service (LOST) in order to
65
+   get next hop based on location and service urn either specified or
66
+   provided with the request.
67
+
68
+   This module implements protocol functions that use the http_client api
69
+   to fetch data from external LOST and HELD servers. The module is using
70
+   the http_client concept of "connections" to define properties of HTTP
71
+   sessions. A connection has one or multiple servers and a set of
72
+   settings that apply to the specific connection.
73
+
74
+   The function lost_held_query allows Kamailio to assemble a HELD
75
+   locationRequest as defined in RFC6155
76
+   (https://tools.ietf.org/html/rfc6155) to query location information
77
+   represented as PIDF-LO for a given identity (in most cases a SIP URI).
78
+   The identity may be a specific parameter or taken from the
79
+   P-Asserted-Identity or From header. The locationRequest response is
80
+   parsed and represented as PIDF-LO and location URI to dereference
81
+   location via HTTP(S).
82
+
83
+   The function lost_query allows Kamailio to assemble a LOST findService
84
+   request as defined in RFC5222 (https://tools.ietf.org/html/rfc5255) to
85
+   query routing information for a given (geodetic) location and a service
86
+   URN. Both, PIDF-LO and service URN may be provided as function
87
+   parameter, or are taken from the request message if applicable. The
88
+   findServiceResponse is parsed and represented asdisplay name and SIP
89
+   URI typically used as next hop in a Route header.
90
+
91
+   The http_client module use the CURL library setting up connections. The
92
+   CURL library by default use the system configured DNS resolvers, not
93
+   the Kamailio resolver.
94
+
95
+   The module is limited to using HTTP and HTTPS protocols.
96
+
97
+2. Dependencies
98
+
99
+   2.1. Kamailio Modules
100
+   2.2. External Libraries or Applications
101
+
102
+2.1. Kamailio Modules
103
+
104
+   The following modules must be loaded before this module:
105
+     * HTTP_CLIENT - the http_client module should be loaded first in
106
+       order to initialize connections properly.
107
+     * TLS - if you use TLS connections (https) the tls module should be
108
+       loaded first in order to initialize OpenSSL properly.
109
+
110
+2.2. External Libraries or Applications
111
+
112
+   The following libraries or applications must be installed before
113
+   running Kamailio with this module loaded:
114
+     * libcurl
115
+     * libxml2
116
+
117
+3. Parameters
118
+
119
+   This module has no specific paramater but uses http_client therfore
120
+   according parameters may apply.
121
+
122
+4. Functions
123