Debian Codegraph @

src/modules/usrloc/README

raw
1 usrloc Module
2
3 Jan Janak
4
5 FhG FOKUS
6
7 Daniel-Constantin Mierla
8
9 <[email protected]>
10
11 Edited by
12
13 Jan Janak
14
15 Bogdan-Andrei Iancu
16
17 Carsten Bock
18
19 ng-voice GmbH
20
21 Copyright © 2003 FhG FOKUS
22
23 Copyright © 2005 Voice Sistem SRL
24
25 Copyright © 2015 ng-voice GmbH
26 __________________________________________________________________
27
28 Table of Contents
29
30 1. Admin Guide
31
32 1. Overview
33
34 1.1. Contact matching
35
36 2. Dependencies
37
38 2.1. Kamailio Modules
39 2.2. External Libraries or Applications
40
41 3. Parameters
42
43 3.1. nat_bflag (int)
44 3.2. user_column (string)
45 3.3. domain_column (string)
46 3.4. contact_column (string)
47 3.5. expires_column (string)
48 3.6. q_column (string)
49 3.7. callid_column (string)
50 3.8. cseq_column (string)
51 3.9. methods_column (string)
52 3.10. flags_column (string)
53 3.11. cflags_column (string)
54 3.12. user_agent_column (string)
55 3.13. received_column (string)
56 3.14. socket_column (string)
57 3.15. path_column (string)
58 3.16. ruid_column (string)
59 3.17. instance_column (string)
60 3.18. reg_id_column (string)
61 3.19. server_id_column (string)
62 3.20. connection_id_column (string)
63 3.21. keepalive_column (string)
64 3.22. partition_column (string)
65 3.23. use_domain (int)
66 3.24. desc_time_order (int)
67 3.25. timer_interval (int)
68 3.26. db_url (string)
69 3.27. db_mode (int)
70 3.28. db_load (int)
71 3.29. db_insert_update (int)
72 3.30. matching_mode (int)
73 3.31. cseq_delay (int)
74 3.32. fetch_rows (int)
75 3.33. hash_size (int)
76 3.34. preload (string)
77 3.35. db_update_as_insert (int)
78 3.36. db_check_update (int)
79 3.37. timer_procs (int)
80 3.38. xavp_contact (string)
81 3.39. db_ops_ruid (int)
82 3.40. handle_lost_tcp (int)
83 3.41. close_expired_tcp (int)
84 3.42. expires_type (int)
85 3.43. db_raw_fetch_type (int)
86 3.44. db_insert_null (int)
87 3.45. skip_remote_socket (int)
88 3.46. db_timer_clean (int)
89 3.47. rm_expired_delay (int)
90 3.48. server_id_filter (int)
91 3.49. version_table (int)
92 3.50. ka_mode (int)
93 3.51. ka_method (str)
94 3.52. ka_from (str)
95 3.53. ka_domain (str)
96 3.54. ka_filter (int)
97 3.55. ka_timeout (int)
98 3.56. ka_interval (int)
99 3.57. ka_randomize (int)
100 3.58. ka_loglevel (int)
101 3.59. ka_logmsg (str)
102 3.60. ka_reply_codes (str)
103 3.61. load_rank (int)
104 3.62. db_clean_tcp (int)
105
106 4. RPC Commands
107
108 4.1. ul.dump
109 4.2. ul.lookup table AOR
110 4.3. ul.rm table AOR
111 4.4. ul.rm_contact table AOR contact
112 4.5. ul.flush
113 4.6. ul.add
114 4.7. ul.db_users
115 4.8. ul.db_contacts
116 4.9. ul.db_expired_contacts
117
118 5. Statistics
119
120 5.1. users
121 5.2. contacts
122 5.3. expires
123 5.4. registered_users
124
125 2. Developer Guide
126
127 1. Available Functions
128
129 1.1. ul_register_domain(name)
130 1.2. ul_insert_urecord(domain, aor, rec)
131 1.3. ul_delete_urecord(domain, aor)
132 1.4. ul_delete_urecord_by_ruid(domain, ruid)
133 1.5. ul_get_urecord(domain, aor)
134 1.6. ul_lock_udomain(domain)
135 1.7. ul_unlock_udomain(domain)
136 1.8. ul_release_urecord(record)
137 1.9. ul_insert_ucontact(record, contact, expires, q, callid,
138 cseq, flags, cont, ua, sock)
139
140 1.10. ul_delete_ucontact (record, contact)
141 1.11. ul_get_ucontact(record, contact)
142 1.12. ul_get_all_ucontacts (buf, len, flags)
143 1.13. ul_update_ucontact(contact, expires, q, callid, cseq,
144 set, res, ua, sock)
145
146 1.14. ul_bind_ursloc(api)
147 1.15. ul_register_ulcb(type, callback, param)
148 1.16. ul_get_num_users()
149
150 List of Examples
151
152 1.1. Set nat_bflag parameter
153 1.2. Set user_column parameter
154 1.3. Set user_column parameter
155 1.4. Set contact_column parameter
156 1.5. Set expires_column parameter
157 1.6. Set q_column parameter
158 1.7. Set callid_column parameter
159 1.8. Set cseq_column parameter
160 1.9. Set methods_column parameter
161 1.10. Set flags_column parameter
162 1.11. Set cflags_column parameter
163 1.12. Set user_agent_column parameter
164 1.13. Set received_column parameter
165 1.14. Set socket_column parameter
166 1.15. Set path_column parameter
167 1.16. Set ruid_column parameter
168 1.17. Set instance_column parameter
169 1.18. Set reg_id_column parameter
170 1.19. Set server_id_column parameter
171 1.20. Set connection_id_column parameter
172 1.21. Set keepalive_column parameter
173 1.22. Set partition_column parameter
174 1.23. Set use_domain parameter
175 1.24. Set desc_time_order parameter
176 1.25. Set timer_interval parameter
177 1.26. Set db_url parameter
178 1.27. Set db_mode parameter
179 1.28. Set db_load parameter
180 1.29. Set db_insert_update parameter
181 1.30. Set matching_mode parameter
182 1.31. Set cseq_delay parameter
183 1.32. Set fetch_rows parameter
184 1.33. Set hash_size parameter
185 1.34. Set preload parameter
186 1.35. Set db_update_as_insert parameter
187 1.36. Set db_check_update parameter
188 1.37. Set timer_procs parameter
189 1.38. Set xavp_contact parameter
190 1.39. Set db_ops_ruid parameter
191 1.40. Set handle_lost_tcp parameter
192 1.41. Set close_expired_tcp parameter
193 1.42. Set expires_type parameter
194 1.43. Set db_raw_fetch_type parameter
195 1.44. Set db_insert_null parameter
196 1.45. Set skip_remote_socket parameter
197 1.46. Set db_timer_clean parameter
198 1.47. Set rm_expired_delay parameter
199 1.48. Set server_id_filter parameter
200 1.49. version_table parameter usage
201 1.50. ka_mode parameter usage
202 1.51. ka_method parameter usage
203 1.52. ka_from parameter usage
204 1.53. ka_domain parameter usage
205 1.54. ka_filter parameter usage
206 1.55. Set ka_timeout parameter
207 1.56. Set ka_interval parameter
208 1.57. Set ka_randomize parameter
209 1.58. ka_loglevel parameter usage
210 1.59. ka_logmsg parameter usage
211 1.60. ka_reply_codes parameter usage
212 1.61. load_rank parameter usage
213 1.62. db_clean_tcp parameter usage
214
215 Chapter 1. Admin Guide
216
217 Table of Contents
218
219 1. Overview
220
221 1.1. Contact matching
222
223 2. Dependencies
224
225 2.1. Kamailio Modules
226 2.2. External Libraries or Applications
227
228 3. Parameters
229
230 3.1. nat_bflag (int)
231 3.2. user_column (string)
232 3.3. domain_column (string)
233 3.4. contact_column (string)
234 3.5. expires_column (string)
235 3.6. q_column (string)
236 3.7. callid_column (string)
237 3.8. cseq_column (string)
238 3.9. methods_column (string)
239 3.10. flags_column (string)
240 3.11. cflags_column (string)
241 3.12. user_agent_column (string)
242 3.13. received_column (string)
243 3.14. socket_column (string)
244 3.15. path_column (string)
245 3.16. ruid_column (string)
246 3.17. instance_column (string)
247 3.18. reg_id_column (string)
248 3.19. server_id_column (string)
249 3.20. connection_id_column (string)
250 3.21. keepalive_column (string)
251 3.22. partition_column (string)
252 3.23. use_domain (int)
253 3.24. desc_time_order (int)
254 3.25. timer_interval (int)
255 3.26. db_url (string)
256 3.27. db_mode (int)
257 3.28. db_load (int)
258 3.29. db_insert_update (int)
259 3.30. matching_mode (int)
260 3.31. cseq_delay (int)
261 3.32. fetch_rows (int)
262 3.33. hash_size (int)
263 3.34. preload (string)
264 3.35. db_update_as_insert (int)
265 3.36. db_check_update (int)
266 3.37. timer_procs (int)
267 3.38. xavp_contact (string)
268 3.39. db_ops_ruid (int)
269 3.40. handle_lost_tcp (int)
270 3.41. close_expired_tcp (int)
271 3.42. expires_type (int)
272 3.43. db_raw_fetch_type (int)
273 3.44. db_insert_null (int)
274 3.45. skip_remote_socket (int)
275 3.46. db_timer_clean (int)
276 3.47. rm_expired_delay (int)
277 3.48. server_id_filter (int)
278 3.49. version_table (int)
279 3.50. ka_mode (int)
280 3.51. ka_method (str)
281 3.52. ka_from (str)
282 3.53. ka_domain (str)
283 3.54. ka_filter (int)
284 3.55. ka_timeout (int)
285 3.56. ka_interval (int)
286 3.57. ka_randomize (int)
287 3.58. ka_loglevel (int)
288 3.59. ka_logmsg (str)
289 3.60. ka_reply_codes (str)
290 3.61. load_rank (int)
291 3.62. db_clean_tcp (int)
292
293 4. RPC Commands
294
295 4.1. ul.dump
296 4.2. ul.lookup table AOR
297 4.3. ul.rm table AOR
298 4.4. ul.rm_contact table AOR contact
299 4.5. ul.flush
300 4.6. ul.add
301 4.7. ul.db_users
302 4.8. ul.db_contacts
303 4.9. ul.db_expired_contacts
304
305 5. Statistics
306
307 5.1. users
308 5.2. contacts
309 5.3. expires
310 5.4. registered_users
311
312 1. Overview
313
314 1.1. Contact matching
315
316 The User location module keeps a user location table and provides
317 access to the table for other modules. The module exports no functions
318 that can be used directly from routing scripts.
319
320 1.1. Contact matching
321
322 How the contacts are matched (for the same AOR - Address of Record) is
323 an important aspect of the usrloc module, especially in the context of
324 NAT traversal - this raises more problems since contacts from different
325 phones of the same user may overlap (if both are behind NATs with the
326 same configuration) or the re-register contact of the same phone may be
327 seen as a new one (due different binding via NAT).
328
329 The SIP RFC 3261 publishes a matching algorithm based only on the
330 contact string with Call-id and Cseq extra checking (if the Call-ID is
331 the same, it must have a higher Cseq number, otherwise it is invalid).
332 But as argued above, this is not enough in NAT traversal context, so
333 the Kamailio implementation of contact matching offers more algorithms:
334 * Contact based only - it is strict RFC 3261 compliancy - the Contact
335 URI is matched as string and extra checked via Call-ID and cseq (if
336 Call-ID is the same, it must have a higher cseq number, otherwise
337 it is invalid).
338 * Contact and Call-id based - it is an extension of the first case -
339 the contact and Call-ID must be matched as string; the cseq must be
340 higher than the previous one - so be careful how you deal with
341 REGISTER retransmissions in this case.
342 * contact and path based - it is an extension of the first case - the
343 contact and path must be matched as string; the cseq must be higher
344 than the previous one - so be careful how you deal with REGISTER
345 retransmissions in this case.
346 * Call-id only based - it is not according to RFC3261, as it will
347 check the Call-ID only (independent of the Contact-Header or Path).
348
349 To find out how to control/select the contact matching algorithm,
350 please see the module parameter matching_mode - Section 3.30,
351 “matching_mode (int)”.
352
353 2. Dependencies
354
355 2.1. Kamailio Modules
356 2.2. External Libraries or Applications
357
358 2.1. Kamailio Modules
359
360 The following modules must be loaded before this module:
361 * Optionally a database module.
362
363 2.2. External Libraries or Applications
364
365 The following libraries or applications must be installed before
366 running Kamailio with this module loaded:
367 * None.
368
369 3. Parameters
370
371 3.1. nat_bflag (int)
372 3.2. user_column (string)
373 3.3. domain_column (string)
374 3.4. contact_column (string)
375 3.5. expires_column (string)
376 3.6. q_column (string)
377 3.7. callid_column (string)
378 3.8. cseq_column (string)
379 3.9. methods_column (string)
380 3.10. flags_column (string)
381 3.11. cflags_column (string)
382 3.12. user_agent_column (string)
383 3.13. received_column (string)
384 3.14. socket_column (string)
385 3.15. path_column (string)
386 3.16. ruid_column (string)
387 3.17. instance_column (string)
388 3.18. reg_id_column (string)
389 3.19. server_id_column (string)
390 3.20. connection_id_column (string)
391 3.21. keepalive_column (string)
392 3.22. partition_column (string)
393 3.23. use_domain (int)
394 3.24. desc_time_order (int)
395 3.25. timer_interval (int)
396 3.26. db_url (string)
397 3.27. db_mode (int)
398 3.28. db_load (int)
399 3.29. db_insert_update (int)
400 3.30. matching_mode (int)
401 3.31. cseq_delay (int)
402 3.32. fetch_rows (int)
403 3.33. hash_size (int)
404 3.34. preload (string)
405 3.35. db_update_as_insert (int)
406 3.36. db_check_update (int)
407 3.37. timer_procs (int)
408 3.38. xavp_contact (string)
409 3.39. db_ops_ruid (int)
410 3.40. handle_lost_tcp (int)
411 3.41. close_expired_tcp (int)
412 3.42. expires_type (int)
413 3.43. db_raw_fetch_type (int)
414 3.44. db_insert_null (int)
415 3.45. skip_remote_socket (int)
416 3.46. db_timer_clean (int)
417 3.47. rm_expired_delay (int)
418 3.48. server_id_filter (int)
419 3.49. version_table (int)
420 3.50. ka_mode (int)
421 3.51. ka_method (str)
422 3.52. ka_from (str)
423 3.53. ka_domain (str)
424 3.54. ka_filter (int)
425 3.55. ka_timeout (int)
426 3.56. ka_interval (int)
427 3.57. ka_randomize (int)
428 3.58. ka_loglevel (int)
429 3.59. ka_logmsg (str)
430 3.60. ka_reply_codes (str)
431 3.61. load_rank (int)
432 3.62. db_clean_tcp (int)
433
434 3.1. nat_bflag (int)
435
436 The index of the branch flag to be used as NAT marker (if the contact
437 is or not natted). This is a branch flag and it will be imported and
438 used by all other modules depending of usrloc module.
439
440 Default value is “not set”.
441
442 Example 1.1. Set nat_bflag parameter
443 ...
444 modparam("usrloc", "nat_bflag", 3)
445 ...
446
447 3.2. user_column (string)
448
449 Name of database column containing usernames.
450
451 Default value is “username”.
452
453 Example 1.2. Set user_column parameter
454 ...
455 modparam("usrloc", "user_column", "username")
456 ...
457
458 3.3. domain_column (string)
459
460 Name of database column containing domains.
461
462 Default value is “domain”.
463
464 Example 1.3. Set user_column parameter
465 ...
466 modparam("usrloc", "domain_column", "domain")
467 ...
468
469 3.4. contact_column (string)
470
471 Name of database column containing contacts.
472
473 Default value is “contact”.
474
475 Example 1.4. Set contact_column parameter
476 ...
477 modparam("usrloc", "contact_column", "contact")
478 ...
479
480 3.5. expires_column (string)
481
482 Name of database column containing expires value.
483
484 Default value is “expires”.
485
486 Example 1.5. Set expires_column parameter
487 ...
488 modparam("usrloc", "expires_column", "expires")
489 ...
490
491 3.6. q_column (string)
492
493 Name of database column containing q values.
494
495 Default value is “q”.
496
497 Example 1.6. Set q_column parameter
498 ...
499 modparam("usrloc", "q_column", "q")
500 ...
501
502 3.7. callid_column (string)
503
504 Name of database column containing Call-ID values.
505
506 Default value is “callid”.
507
508 Example 1.7. Set callid_column parameter
509 ...
510 modparam("usrloc", "callid_column", "callid")
511 ...
512
513 3.8. cseq_column (string)
514
515 Name of database column containing Cseq.
516
517 Default value is “cseq”.
518
519 Example 1.8. Set cseq_column parameter
520 ...
521 modparam("usrloc", "cseq_column", "cseq")
522 ...
523
524 3.9. methods_column (string)
525
526 Name of database column containing supported methods.
527
528 Default value is “methods”.
529
530 Example 1.9. Set methods_column parameter
531 ...
532 modparam("usrloc", "methods_column", "methods")
533 ...
534
535 3.10. flags_column (string)
536
537 Name of database column to save the internal flags of the record.
538
539 Default value is “flags”.
540
541 Example 1.10. Set flags_column parameter
542 ...
543 modparam("usrloc", "flags_column", "flags")
544 ...
545
546 3.11. cflags_column (string)
547
548 Name of database column to save the branch/contact flags of the record.
549
550 Default value is “cflags”.
551
552 Example 1.11. Set cflags_column parameter
553 ...
554 modparam("usrloc", "cflags_column", "cflags")
555 ...
556
557 3.12. user_agent_column (string)
558
559 Name of database column containing user-agent values.
560
561 Default value is “user_agent”.
562
563 Example 1.12. Set user_agent_column parameter
564 ...
565 modparam("usrloc", "user_agent_column", "user_agent")
566 ...
567
568 3.13. received_column (string)
569
570 Name of database column containing the source IP, port, and protocol
571 from the REGISTER message.
572
573 Default value is “received”.
574
575 Example 1.13. Set received_column parameter
576 ...
577 modparam("usrloc", "received_column", "received")
578 ...
579
580 3.14. socket_column (string)
581
582 Name of database column containing the received socket information
583 (IP:port) for the REGISTER message.
584
585 Default value is “socket”.
586
587 Example 1.14. Set socket_column parameter
588 ...
589 modparam("usrloc", "socket_column", "socket")
590 ...
591
592 3.15. path_column (string)
593
594 Name of database column containing the Path header.
595
596 Default value is “path”.
597
598 Example 1.15. Set path_column parameter
599 ...
600 modparam("usrloc", "path_column", "path")
601 ...
602
603 3.16. ruid_column (string)
604
605 Name of database column containing the Kamailio record unique id.
606
607 Default value is “ruid”.
608
609 Example 1.16. Set ruid_column parameter
610 ...
611 modparam("usrloc", "ruid_column", "myruid")
612 ...
613
614 3.17. instance_column (string)
615
616 Name of database column containing the SIP instance ID (GRUU -
617 RFC5627). This is a unique device identifier - UUID.
618
619 Default value is “instance”.
620
621 Example 1.17. Set instance_column parameter
622 ...
623 modparam("usrloc", "instance_column", "myinstance")
624 ...
625
626 3.18. reg_id_column (string)
627
628 Name of database table column containing the value for reg-id.
629
630 Default value is “reg_id”.
631
632 Example 1.18. Set reg_id_column parameter
633 ...
634 modparam("usrloc", "reg_id_column", "r_id")
635 ...
636
637 3.19. server_id_column (string)
638
639 Name of database table column containing the value for server id.
640
641 Default value is “server_id”.
642
643 Example 1.19. Set server_id_column parameter
644 ...
645 modparam("usrloc", "server_id_column", "srv_id")
646 ...
647
648 3.20. connection_id_column (string)
649
650 Name of database table column containing the value for connection id.
651
652 Default value is “connection_id”.
653
654 Example 1.20. Set connection_id_column parameter
655 ...
656 modparam("usrloc", "connection_id_column", "con_id")
657 ...
658
659 3.21. keepalive_column (string)
660
661 Name of database table column containing the value for keepalive
662 status.
663
664 Default value is “keepalive”.
665
666 Example 1.21. Set keepalive_column parameter
667 ...
668 modparam("usrloc", "keepalive_column", "kalive")
669 ...
670
671 3.22. partition_column (string)
672
673 Name of database table column containing the value for partition id.
674
675 Default value is “partition”.
676
677 Example 1.22. Set partition_column parameter
678 ...
679 modparam("usrloc", "partition_column", "part")
680 ...
681
682 3.23. use_domain (int)
683
684 If the domain part of the user should be also saved and used for
685 identifying the user (along with the username part). Useful in multi
686 domain scenarios. Non 0 value means true.
687
688 Default value is “0 (false)”.
689
690 Example 1.23. Set use_domain parameter
691 ...
692 modparam("usrloc", "use_domain", 1)
693 ...
694
695 3.24. desc_time_order (int)
696
697 If the user's contacts should be kept timestamp ordered; otherwise the
698 contact will be ordered based on q value. Non 0 value means true.
699
700 Default value is “0 (false)”.
701
702 Example 1.24. Set desc_time_order parameter
703 ...
704 modparam("usrloc", "desc_time_order", 1)
705 ...
706
707 3.25. timer_interval (int)
708
709 Number of seconds between two timer runs. The module uses a timer to
710 delete expired contacts, synchronize with database, send keepalives and
711 other tasks, that need to be run periodically.
712
713 Default value is 60.
714
715 Example 1.25. Set timer_interval parameter
716 ...
717 modparam("usrloc", "timer_interval", 120)
718 ...
719
720 3.26. db_url (string)
721
722 URL of the database that should be used.
723
724 Default value is “mysql://kamailio:kamailiorw@localhost/kamailio”.
725
726 Example 1.26. Set db_url parameter
727 ...
728 modparam("usrloc", "db_url", "dbdriver://username:password@dbhost/dbname")
729 ...
730
731 3.27. db_mode (int)
732
733 The usrloc module can utilize a database for persistent contact
734 storage. If a database is used, the location database (contacts) will
735 survive machine restarts or software crashes. The disadvantage is that
736 accessing a database can be very time consuming. Therefore, usrloc
737 module implements four database accessing modes:
738 * 0 - This disables database completely. Only memory will be used.
739 Contacts will not survive restart. Use this value if you need a
740 really fast usrloc and contact persistence is not necessary or is
741 provided by other means.
742 * 1 - Write-Through scheme. All changes to usrloc are immediately
743 reflected in database too. This is very slow, but very reliable.
744 Use this scheme if speed is not your priority but need to make sure
745 that no registered contacts will be lost during crash or reboot.
746 * 2 - Write-Back scheme. This is a combination of previous two
747 schemes. All changes are made to memory and database
748 synchronization is done in the timer. The timer deletes all expired
749 contacts and flushes all modified or new contacts to database. Use
750 this scheme if you encounter high-load peaks and want them to
751 process as fast as possible. The mode will not help at all if the
752 load is high all the time. Also, latency of this mode is much lower
753 than latency of mode 1, but slightly higher than latency of mode 0.
754 * 3 - DB-Only scheme. No memory cache is kept, all operations being
755 directly performed with the database. The timer deletes all expired
756 contacts from database - cleans after clients that didn't
757 un-register or re-register. The mode is useful if you configure
758 more servers sharing the same DB without any replication at SIP
759 level. The mode may be slower due the high number of DB operation.
760 For example NAT pinging is a killer since during each ping cycle
761 all natted contact are loaded from the DB; The lack of memory
762 caching also disable the statistics exports.
763 * 4 - This uses database to load records at startup but uses only
764 memory during the runtime. Records are not written back at all, not
765 even at shutdown. Useful for scenarios when registrations are
766 replicated to a node that does the storage in a database during
767 runtime.
768
769 Warning
770
771 In case of crash or restart contacts that are in memory only and
772 haven't been flushed yet will get lost. If you want minimize the risk,
773 use shorter timer interval.
774
775 Default value is 0.
776
777 Example 1.27. Set db_mode parameter
778 ...
779 modparam("usrloc", "db_mode", 2)
780 ...
781
782 3.28. db_load (int)
783
784 Determine if the usrloc module should load contacts from the database
785 storage during module initialization. A value of 0 disables the loading
786 from the database, this parameter is ignored if db_mode 4 is set.
787
788 Default value is 1.
789
790 Example 1.28. Set db_load parameter
791 ...
792 modparam("usrloc", "db_load", 0)
793 ...
794
795 3.29. db_insert_update (int)
796
797 Determine if the usrloc module should do an update when a duplicate key
798 is found while inserting A value of 1 will activate update on duplicate
799 key
800
801 Default value is 0.
802
803 Example 1.29. Set db_insert_update parameter
804 ...
805 modparam("usrloc", "db_insert_update", 1)
806 ...
807
808 3.30. matching_mode (int)
809
810 What contact matching algorithm to be used. Refer to section ??? for
811 the description of the algorithms.
812
813 The parameter may take the following values:
814 * 0 - CONTACT ONLY based matching algorithm.
815 * 1 - CONTACT and CALLID based matching algorithm.
816 * 2 - CONTACT and PATH based matching algorithm. This mode is like
817 mode 0 but allows for duplicate contacts from differing paths. If
818 no path is available, it defaults to mode 0.
819 * 3 - CALLID only based matching algorithm. This mode will discard
820 any duplicate registration coming through different paths.
821
822 Default value is 0 (CONTACT_ONLY).
823
824 Example 1.30. Set matching_mode parameter
825 ...
826 modparam("usrloc", "matching_mode", 1)
827 ...
828
829 3.31. cseq_delay (int)
830
831 Delay (in seconds) for accepting as retransmissions register requests
832 with same Call-ID and Cseq. The delay is calculated starting from the
833 receiving time of the first register with that Call-ID and Cseq.
834
835 Retransmissions within this delay interval will be accepted and replied
836 as the original request, but no update will be done in location. If the
837 delay is exceeded, error is reported.
838
839 A value of 0 disable the retransmission detection.
840
841 Default value is “20 seconds”.
842
843 Example 1.31. Set cseq_delay parameter
844 ...
845 modparam("usrloc", "cseq_delay", 5)
846 ...
847
848 3.32. fetch_rows (int)
849
850 The number of the rows to be fetched at once from database when loading
851 the location records. This value can be used to tune the load time at
852 startup. For 1MB of private memory (default) it should be below 4000.
853 The database driver must support fetch_result() capability.
854
855 Default value is “2000”.
856
857 Example 1.32. Set fetch_rows parameter
858 ...
859 modparam("usrloc", "fetch_rows", 3000)
860 ...
861
862 3.33. hash_size (int)
863
864 The number of entries of the hash table used by usrloc to store the
865 location records is 2^hash_size. For hash_size=4, the number of slots
866 of the hash table is 16.
867
868 Default value is “10” (1024 slots).
869
870 Example 1.33. Set hash_size parameter
871 ...
872 modparam("usrloc", "hash_size", 12)
873 ...
874
875 3.34. preload (string)
876
877 Preload location table given as value. A location table is loaded based
878 on fixup of registrar functions, therefore you need to use this
879 parameter only to load tables that are not used by registrar module
880 directly in configuration file.
881
882 Default value is “NULL”.
883
884 Example 1.34. Set preload parameter
885 ...
886 modparam("usrloc", "preload", "location")
887 ...
888
889 3.35. db_update_as_insert (int)
890
891 Set this parameter if you want to do INSERT DB operations instead of
892 UPDATE DB operations. It is recommended to set this parameter if you
893 use Cassandra as a DB backend.
894
895 Default value is “0”.
896
897 Example 1.35. Set db_update_as_insert parameter
898 ...
899 modparam("usrloc", "db_update_as_insert", 1)
900 ...
901
902 3.36. db_check_update (int)
903
904 Set this parameter to 1 if you want to do DB INSERT if the number of
905 affected rows by contact DB UPDATE operation is 0. The database module
906 driver has to implement affected_rows() DB API function, otherwise this
907 parameter is ignored - e.g., MySQL and Postgres DB connectors offer
908 affected_rows().
909
910 Default value is “0” (no DB INSERT).
911
912 Example 1.36. Set db_check_update parameter
913 ...
914 modparam("usrloc", "db_check_update", 1)
915 ...
916
917 3.37. timer_procs (int)
918
919 Number of timer processes to be started by module. Timer processes take
920 care of checking expired records and synchronization with database. If
921 set to 0, no dedicated timer is started, the one from core will be
922 used.
923
924 If the number of timer processes is greater than 1, the workload of
925 synchronization and record expiration is split up among the multiple
926 processes. (Each process is assigned a range of slots from the internal
927 hash table, and is responsible for cleanup and storage on those slots.)
928
929 Default value is “0”.
930
931 Example 1.37. Set timer_procs parameter
932 ...
933 modparam("usrloc", "timer_procs", 4)
934 ...
935
936 3.38. xavp_contact (string)
937
938 The name of XAVP storing the attributes per contact. They are saved in
939 location record and restored at lookup. The tm module parameter
940 xavp_contact must also be set to the same value to use the
941 t_load_contacts and t_next_contacts functions.
942
943 Default value is “NULL”.
944
945 Example 1.38. Set xavp_contact parameter
946 ...
947 modparam("tm|usrloc", "xavp_contact", "ulattrs")
948 ...
949
950 3.39. db_ops_ruid (int)
951
952 If set to 1, database queries for update or delete are done using ruid
953 value. If it is set to 0, the old style using aor, contact and call-id
954 is done.
955
956 Default value is “1”.
957
958 Example 1.39. Set db_ops_ruid parameter
959 ...
960 modparam("usrloc", "db_ops_ruid", 0)
961 ...
962
963 3.40. handle_lost_tcp (int)
964
965 If set to 1, Kamailio will remove location records made via
966 TCP/TLS/WS/WSS transports when it looses corresponding tcp connections.
967 Does not currently work in DB-Only scheme.
968
969 Default value is “0”.
970
971 Example 1.40. Set handle_lost_tcp parameter
972 ...
973 modparam("usrloc", "handle_lost_tcp", 1)
974 ...
975
976 3.41. close_expired_tcp (int)
977
978 If set to 1, Kamailio will close the TCP connection when a contact has
979 expired, if the corresponding transport is TCP/TLS/WS/WSS.
980
981 Default value is “0”.
982
983 Example 1.41. Set close_expired_tcp parameter
984 ...
985 modparam("usrloc", "close_expired_tcp", 1)
986 ...
987
988 3.42. expires_type (int)
989
990 If set to 1, Kamailio expects to deal with BIGINT type on database
991 columns for expires and last modified values. It allows to handle
992 better the daylight time adjustments. If set to 0, those columns are
993 expected to be on default type 'DATETIME'. When it is 1, the database
994 columns types have to be changed manually to 'BIGINT'.
995
996 Default value is “0”.
997
998 Example 1.42. Set expires_type parameter
999 ...
1000 modparam("usrloc", "expires_type", 1)
1001 ...
1002
1003 3.43. db_raw_fetch_type (int)
1004
1005 This affect DB-only mode and controls what kind of raw query is used to
1006 fetch the contacts from database for specific needs (e.g., sending NAT
1007 keepalives). If it is set to 0, then the common SQL query is used
1008 (working for MySQL, PostgreSQL, ...). If it is set to 1, the query
1009 required by Oracle is used.
1010
1011 Default value is “0”.
1012
1013 Example 1.43. Set db_raw_fetch_type parameter
1014 ...
1015 modparam("usrloc", "db_raw_fetch_type", 1)
1016 ...
1017
1018 3.44. db_insert_null (int)
1019
1020 If set to 1, the insert operation to database will add null values in
1021 the statement. It has to be set to 1 for the database systems that do
1022 not have table definitions that create automatically the null fields
1023 (e.g., db_mongodb) for each stored record.
1024
1025 When set to 0, the fields that default to null are not added to the DB
1026 insert statement if they don't have a different value, making the query
1027 smaller.
1028
1029 Default value is “0” (don't add null fields in insert statement).
1030
1031 Example 1.44. Set db_insert_null parameter
1032 ...
1033 modparam("usrloc", "db_insert_null", 1)
1034 ...
1035
1036 3.45. skip_remote_socket (int)
1037
1038 If set to 1, Kamailio will skip location record when loading from
1039 database, if socket value of the record does not in kamailio listening
1040 socket list.
1041
1042 Default value is “0”.
1043
1044 Example 1.45. Set skip_remote_socket parameter
1045 ...
1046 modparam("usrloc", "skip_remote_socket", 1)
1047 ...
1048
1049 3.46. db_timer_clean (int)
1050
1051 Enable (1) or disable (0) cleaning of expired db records on timer basis
1052 for db_mode WRITE-BACK and WRITE-THROUGH. It uses the secondary timer
1053 process.
1054
1055 Default value is “0”.
1056
1057 Example 1.46. Set db_timer_clean parameter
1058 ...
1059 modparam("usrloc", "db_timer_clean", 1)
1060 ...
1061
1062 3.47. rm_expired_delay (int)
1063
1064 Specify the number of seconds to delay the removal of expired records.
1065 For now it works for DB_ONLY mode (db_mode=3).
1066
1067 Default value is “0”.
1068
1069 Example 1.47. Set rm_expired_delay parameter
1070 ...
1071 modparam("usrloc", "rm_expired_delay", 30)
1072 ...
1073
1074 3.48. server_id_filter (int)
1075
1076 Enable (1) or disable (0) filter records by server_id on load and
1077 during cleaning of expired db records. It could be useful when you want
1078 to use the same location table for several kamailio instances which are
1079 configured to work in db_mode=1 or db_mode=2 (cache modes). Otherwise
1080 one instance of proxy cleans records made by another proxy and that
1081 breaks its cache.
1082
1083 Default value is “0”.
1084
1085 Example 1.48. Set server_id_filter parameter
1086 ...
1087 modparam("usrloc", "server_id_filter", 1)
1088 ...
1089
1090 3.49. version_table (int)
1091
1092 If set to 0, the module will skip checking the version for location
1093 table.
1094
1095 Default value is “1 (check for table version)”.
1096
1097 Example 1.49. version_table parameter usage
1098 ...
1099 modparam("usrloc", "version_table", 0)
1100 ...
1101
1102 3.50. ka_mode (int)
1103
1104 Keepalive mode - control the internal keepalive mechanism. With this
1105 feature enabled, the module sends periodically (based on timer
1106 interval) SIP requests to location contacts and measures the round trip
1107 in microseconds (the round trip value can be seen in the response of
1108 the RPC command 'ul.dump').
1109
1110 Its value is a set of flags:
1111 * 0 - if the value is zero, no keepalive is sent
1112 * 1 (bit 1 set) - if set to 1, the keepalive is enabled for all
1113 contacts
1114 * 2 (bit 2 set) - the keepalive is sent only for natted contacts
1115 (nat_bflag set)
1116 * 4 (bit 3 set) - the keepalive is sent only for UDP contacts
1117
1118 For example, if set to 6, then keepalive is sent only natted UDP
1119 contacts.
1120
1121 Note: the internal keepalive of usrloc module conflicts in some way
1122 with the keepalive done by nathelper module. It is recommended to
1123 enable only one.
1124
1125 Note: the internal keepalive is for the moment implemented only for
1126 contact records stored in memory.
1127
1128 Note: it is recommended to set 'timer_procs' parameter in order to have
1129 dedicated timer processes for usrloc module and off-load the keepalive
1130 sending process from the core timers.
1131
1132 Note: Keepalives will be sent to the IP and port using the transport
1133 defined in the “received” column. If not set, then keepalives will be
1134 sent to the AOR using UDP as a default transport. If available, the TCP
1135 connection will be re-used for WS, TCP and TLS.
1136
1137 Default value is “0 (keepalive disabled)”.
1138
1139 Example 1.50. ka_mode parameter usage
1140 ...
1141 modparam("usrloc", "ka_mode", 1)
1142 ...
1143
1144 3.51. ka_method (str)
1145
1146 The SIP method type for keepalive requests.
1147
1148 Default value is “OPTIONS”.
1149
1150 Example 1.51. ka_method parameter usage
1151 ...
1152 modparam("usrloc", "ka_method", "NOTIFY")
1153 ...
1154
1155 3.52. ka_from (str)
1156
1157 The SIP URI to be set in the From header of the keepalive requests.
1158
1159 Default value is “sip:[email protected]”.
1160
1161 Example 1.52. ka_from parameter usage
1162 ...
1163 modparam("usrloc", "ka_from", "sip:[email protected]")
1164 ...
1165
1166 3.53. ka_domain (str)
1167
1168 The domain to be set in To header URI if the multi-domain is not
1169 enabled. If multi-domain is enabled, then the domain from the location
1170 record is used and this parameter is ignored.
1171
1172 Default value is “kamailio.org”.
1173
1174 Example 1.53. ka_domain parameter usage
1175 ...
1176 modparam("usrloc", "ka_domain", "mydomain.com")
1177 ...
1178
1179 3.54. ka_filter (int)
1180
1181 Set filters for keepalive processing.
1182
1183 Its value is a set of flags:
1184 * 0 - if the value is zero, no filter is enabled for keepalives
1185 * 1 (bit 1 set) - keepalives sent only to records matching the
1186 server_id global parameter.
1187
1188 Default value is “0” (no filter).
1189
1190 Example 1.54. ka_filter parameter usage
1191 ...
1192 modparam("usrloc", "ka_filter", 1)
1193 ...
1194
1195 3.55. ka_timeout (int)
1196
1197 The parameter sets the interval in seconds after which a contact is
1198 removed from location table if it does not reply to SIP keepalives
1199 (usually OPTIONS ping requests).
1200
1201 The features is available only for contacts that are stored in memory
1202 (not working for db only mode of the usrloc module).
1203
1204 Keepalives are sent stateless, not using TM module. The value of this
1205 parameter has to be few times higher than timer interval.
1206
1207 Default value is “0” (feature disabled).
1208
1209 Example 1.55. Set ka_timeout parameter
1210 ...
1211 modparam("usrloc", "ka_timeout", 120)
1212 ...
1213
1214 3.56. ka_interval (int)
1215
1216 The parameter sets the interval in seconds after which a new keepalive
1217 request should be sent for a location record.
1218
1219 Default value is “40”.
1220
1221 Example 1.56. Set ka_interval parameter
1222 ...
1223 modparam("usrloc", "ka_interval", 30)
1224 ...
1225
1226 3.57. ka_randomize (int)
1227
1228 The parameter sets the the upper limit to the range of random seconds
1229 to be added to ka_interval before checking if a new keepalive request
1230 has to be sent. It should help to distribute better the sending of
1231 keepalive requests. The keepalive for a location record is going to be
1232 sent in a random fashion between (ka_interval + 0) and (ka_interval +
1233 ka_randomize).
1234
1235 Default value is “20”.
1236
1237 Example 1.57. Set ka_randomize parameter
1238 ...
1239 modparam("usrloc", "ka_interval", 30)
1240 ...
1241
1242 3.58. ka_loglevel (int)
1243
1244 The level to print the log message when the keepalive response is
1245 received. It should be a value between -5 (L_ALERT) and 3 (L_DBG).
1246
1247 Default value is “255” (disabled).
1248
1249 Example 1.58. ka_loglevel parameter usage
1250 ...
1251 modparam("usrloc", "ka_loglevel", 1)
1252 ...
1253
1254 3.59. ka_logmsg (str)
1255
1256 The formatted log specification to be added to the message printed when
1257 the keepalive is received and roundtrip time is computed. The log
1258 message starts with "keepalive roundtrip: %u.%06u sec - ruid [%.*s]",
1259 then concatenates the value of this parameter and the end of line.
1260
1261 The value of this parameter can contain script variables that are
1262 evaluated with the SIP response.
1263
1264 Default value is “ to-uri: [$tu] remote-addr: [$sas]”.
1265
1266 Example 1.59. ka_logmsg parameter usage
1267 ...
1268 modparam("usrloc", "ka_logmsg", " to-uri: [$tu] remote-addr: [$sas]")
1269 ...
1270
1271 3.60. ka_reply_codes (str)
1272
1273 Comma separated list of reply code values or reply code classes to be
1274 considered valid for keepalive processing. If the reply code does not
1275 match any of them, then the reply is ignored, not considered a valid
1276 response to keepalive request. It could be useful to skip replies from
1277 intermediary proxies that could not forward the request.
1278
1279 Default value is “0” (checking of reply code is not done, are responses
1280 are considered valid).
1281
1282 Example 1.60. ka_reply_codes parameter usage
1283 ...
1284 modparam("usrloc", "ka_reply_codes", "2,405,486")
1285 ...
1286
1287 3.61. load_rank (int)
1288
1289 Allows to set the rank of the child SIP worker to load the location
1290 records.
1291
1292 Default value is “1” (PROC_SIPINIT).
1293
1294 Example 1.61. load_rank parameter usage
1295 ...
1296 modparam("usrloc", "load_rank", 1)
1297 ...
1298
1299 3.62. db_clean_tcp (int)
1300
1301 If set to 1, when Kamailio starts it removes the contacts with
1302 transport TCP, TLS or WSS, no longer loading them. Useful when end
1303 points do not listen for incoming connections on contact address, which
1304 is quite common (end point use only tcp client connections). On
1305 restart, connections are lost, therefore the corresponding contact
1306 records become useless.
1307
1308 Default value is “0” (do not clean tcp contacts).
1309
1310 Example 1.62. db_clean_tcp parameter usage
1311 ...
1312 modparam("usrloc", "db_clean_tcp", 1)
1313 ...
1314
1315 4. RPC Commands
1316
1317 4.1. ul.dump
1318 4.2. ul.lookup table AOR
1319 4.3. ul.rm table AOR
1320 4.4. ul.rm_contact table AOR contact
1321 4.5. ul.flush
1322 4.6. ul.add
1323 4.7. ul.db_users
1324 4.8. ul.db_contacts
1325 4.9. ul.db_expired_contacts
1326
1327 4.1. ul.dump
1328
1329 Dumps the content of the location table
1330
1331 Parameters:
1332 * None.
1333
1334 4.2. ul.lookup table AOR
1335
1336 Looks up the contents of an AOR entry in the location table
1337
1338 Parameters:
1339 * table name - table where the AOR resides (Ex: location).
1340 * AOR - user AOR in username[@domain] format (domain must be supplied
1341 only if use_domain option is on).
1342
1343 4.3. ul.rm table AOR
1344
1345 Deletes an entire AOR record (including its contacts).
1346
1347 Parameters:
1348 * table name - table where the AOR resides (Ex: location).
1349 * AOR - user AOR in username[@domain] format (domain must be supplied
1350 only if use_domain option is on).
1351
1352 4.4. ul.rm_contact table AOR contact
1353
1354 Deletes a contact from an AOR record.
1355
1356 Parameters:
1357 * table name - table where the AOR is removed from (Ex: location).
1358 * AOR - user AOR in username[@domain] format (domain must be supplied
1359 only if use_domain option is on).
1360 * contact - exact contact to be removed
1361
1362 4.5. ul.flush
1363
1364 Triggers the flush of USRLOC memory cache into DB from the RPC process.
1365 It succeeds only if the the db_mode is set to a value that enables
1366 connectivity to database.
1367
1368 4.6. ul.add
1369
1370 Adds a new contact for a user AOR.
1371
1372 Parameters:
1373 * table name - table where the contact will be added (Ex: location).
1374 * AOR - user AOR in username[@domain] format (domain must be supplied
1375 only if use_domain option is on).
1376 * contact - contact string to be added
1377 * expires - expires value of the contact
1378 * Q - Q value of the contact
1379 * path value with the Path vector (use '0' or '.' if it should not be
1380 set)
1381 * flags - internal USRLOC flags of the contact
1382 * cflags - per branch flags of the contact
1383 * methods - mask with supported requests of the contact
1384 * received (optional) value with the received-from address (source
1385 address) (use '0' or '.' if it should not be set). Format:
1386 sip:srcip:srcport;transport=abc
1387 * socket (optional) value with the local socket address (use '0' or
1388 '.' if it should not be set). Format: proto:localip:localport
1389
1390 Note: the position of parameters is relevant, in the case of optional
1391 parameters, use '0' or '.' for parameters that should not be set which
1392 are positioned before any parameter that has to be set.
1393
1394 4.7. ul.db_users
1395
1396 Tell number of different users (AoRs) in a location table that have
1397 unexpired contacts.
1398
1399 Parameters:
1400 * table name - location table where the users are looked for, for
1401 example, location.
1402
1403 4.8. ul.db_contacts
1404
1405 Tell number of unexpired contacts in a location table.
1406
1407 Parameters:
1408 * table name - location table where the contacts are looked for, for
1409 example, location.
1410
1411 4.9. ul.db_expired_contacts
1412
1413 Tell number of expired contacts in a location table.
1414
1415 Parameters:
1416 * table name - location table where the contacts are looked for, for
1417 example, location.
1418
1419 5. Statistics
1420
1421 5.1. users
1422 5.2. contacts
1423 5.3. expires
1424 5.4. registered_users
1425
1426 Exported statistics are listed in the next sections.
1427
1428 5.1. users
1429
1430 Number of AOR existing in the USRLOC memory cache for that domain - can
1431 not be reset; this statistic will be registered for each used domain
1432 (Ex: location).
1433
1434 5.2. contacts
1435
1436 Number of contacts existing in the USRLOC memory cache for that domain
1437 - can not be reset; this statistic will be registered for each used
1438 domain (Ex: location).
1439
1440 5.3. expires
1441
1442 Total number of expired contacts for that domain - can be reset; this
1443 statistic will be registered for each used domain (Ex: location).
1444
1445 5.4. registered_users
1446
1447 Total number of AOR existing in the USRLOC memory cache for all domains
1448 - can not be reset.
1449
1450 Chapter 2. Developer Guide
1451
1452 Table of Contents
1453
1454 1. Available Functions
1455
1456 1.1. ul_register_domain(name)
1457 1.2. ul_insert_urecord(domain, aor, rec)
1458 1.3. ul_delete_urecord(domain, aor)
1459 1.4. ul_delete_urecord_by_ruid(domain, ruid)
1460 1.5. ul_get_urecord(domain, aor)
1461 1.6. ul_lock_udomain(domain)
1462 1.7. ul_unlock_udomain(domain)
1463 1.8. ul_release_urecord(record)
1464 1.9. ul_insert_ucontact(record, contact, expires, q, callid, cseq,
1465 flags, cont, ua, sock)
1466
1467 1.10. ul_delete_ucontact (record, contact)
1468 1.11. ul_get_ucontact(record, contact)
1469 1.12. ul_get_all_ucontacts (buf, len, flags)
1470 1.13. ul_update_ucontact(contact, expires, q, callid, cseq, set,
1471 res, ua, sock)
1472
1473 1.14. ul_bind_ursloc(api)
1474 1.15. ul_register_ulcb(type, callback, param)
1475 1.16. ul_get_num_users()
1476
1477 1. Available Functions
1478
1479 1.1. ul_register_domain(name)
1480 1.2. ul_insert_urecord(domain, aor, rec)
1481 1.3. ul_delete_urecord(domain, aor)
1482 1.4. ul_delete_urecord_by_ruid(domain, ruid)
1483 1.5. ul_get_urecord(domain, aor)
1484 1.6. ul_lock_udomain(domain)
1485 1.7. ul_unlock_udomain(domain)
1486 1.8. ul_release_urecord(record)
1487 1.9. ul_insert_ucontact(record, contact, expires, q, callid, cseq,
1488 flags, cont, ua, sock)
1489
1490 1.10. ul_delete_ucontact (record, contact)
1491 1.11. ul_get_ucontact(record, contact)
1492 1.12. ul_get_all_ucontacts (buf, len, flags)
1493 1.13. ul_update_ucontact(contact, expires, q, callid, cseq, set, res,
1494 ua, sock)
1495
1496 1.14. ul_bind_ursloc(api)
1497 1.15. ul_register_ulcb(type, callback, param)
1498 1.16. ul_get_num_users()
1499
1500 1.1. ul_register_domain(name)
1501
1502 The function registers a new domain. Domain is just another name for
1503 table used in registrar. The function is called from fixups in
1504 registrar. It gets name of the domain as a parameter and returns
1505 pointer to a new domain structure. The fixup than 'fixes' the parameter
1506 in registrar so that it will pass the pointer instead of the name every
1507 time save() or lookup() is called. Some usrloc functions get the
1508 pointer as parameter when called. For more details see implementation
1509 of save function in registrar.
1510
1511 Meaning of the parameters is as follows:
1512 * const char* name - Name of the domain (also called table) to be
1513 registered.
1514
1515 1.2. ul_insert_urecord(domain, aor, rec)
1516
1517 The function creates a new record structure and inserts it in the
1518 specified domain. The record is structure that contains all the
1519 contacts for belonging to the specified username.
1520
1521 Meaning of the parameters is as follows:
1522 * udomain_t* domain - Pointer to domain returned by
1523 ul_register_udomain.
1524
1525 * str* aor - Address of Record (aka username) of the new record (at
1526 this time the record will contain no contacts yet).
1527
1528 * urecord_t** rec - The newly created record structure.
1529
1530 1.3. ul_delete_urecord(domain, aor)
1531
1532 The function deletes all the contacts bound with the given Address Of
1533 Record.
1534
1535 Meaning of the parameters is as follows:
1536 * udomain_t* domain - Pointer to domain returned by
1537 ul_register_udomain.
1538
1539 * str* aor - Address of record (aka username) of the record, that
1540 should be deleted.
1541
1542 1.4. ul_delete_urecord_by_ruid(domain, ruid)
1543
1544 The function deletes from given domain a contact with given ruid.
1545
1546 Meaning of the parameters is as follows:
1547 * udomain_t* domain - Pointer to domain returned by
1548 ul_register_udomain.
1549
1550 * str* ruid - ruid of contact that should be deleted.
1551
1552 1.5. ul_get_urecord(domain, aor)
1553
1554 The function returns pointer to record with given Address of Record.
1555
1556 Meaning of the parameters is as follows:
1557 * udomain_t* domain - Pointer to domain returned by
1558 ul_register_udomain.
1559
1560 * str* aor - Address of Record of request record.
1561
1562 1.6. ul_lock_udomain(domain)
1563
1564 The function lock the specified domain, it means, that no other
1565 processes will be able to access during the time. This prevents race
1566 conditions. Scope of the lock is the specified domain, that means, that
1567 multiple domain can be accessed simultaneously, they don't block each
1568 other.
1569
1570 Meaning of the parameters is as follows:
1571 * udomain_t* domain - Domain to be locked.
1572
1573 1.7. ul_unlock_udomain(domain)
1574
1575 Unlock the specified domain previously locked by ul_lock_udomain.
1576
1577 Meaning of the parameters is as follows:
1578 * udomain_t* domain - Domain to be unlocked.
1579
1580 1.8. ul_release_urecord(record)
1581
1582 Do some sanity checks - if all contacts have been removed, delete the
1583 entire record structure.
1584
1585 Meaning of the parameters is as follows:
1586 * urecord_t* record - Record to be released.
1587
1588 1.9. ul_insert_ucontact(record, contact, expires, q, callid, cseq, flags,
1589 cont, ua, sock)
1590
1591 The function inserts a new contact in the given record with specified
1592 parameters.
1593
1594 Meaning of the parameters is as follows:
1595 * urecord_t* record - Record in which the contact should be inserted.
1596 * str* contact - Contact URI.
1597 * time_t expires - Expires of the contact in absolute value.
1598 * float q - q value of the contact.
1599 * str* callid - Call-ID of the REGISTER message that contained the
1600 contact.
1601 * int cseq - CSeq of the REGISTER message that contained the contact.
1602 * unsigned int flags - Flags to be set.
1603 * ucontact_t* cont - Pointer to newly created structure.
1604 * str* ua - User-Agent of the REGISTER message that contained the
1605 contact.
1606 * struct socket_info *sock - socket on which the REGISTER message was
1607 received on.
1608
1609 1.10. ul_delete_ucontact (record, contact)
1610
1611 The function deletes given contact from record.
1612
1613 Meaning of the parameters is as follows:
1614 * urecord_t* record - Record from which the contact should be
1615 removed.
1616
1617 * ucontact_t* contact - Contact to be deleted.
1618
1619 1.11. ul_get_ucontact(record, contact)
1620
1621 The function tries to find contact with given Contact URI and returns
1622 pointer to structure representing the contact.
1623
1624 Meaning of the parameters is as follows:
1625 * urecord_t* record - Record to be searched for the contact.
1626
1627 * str_t* contact - URI of the request contact.
1628
1629 1.12. ul_get_all_ucontacts (buf, len, flags)
1630
1631 The function retrieves all contacts of all registered users and returns
1632 them in the caller-supplied buffer. If the buffer is too small, the
1633 function returns positive value indicating how much additional space
1634 would be necessary to accommodate all of them. Please note that the
1635 positive return value should be used only as a “hint”, as there is no
1636 guarantee that during the time between two subsequent calls number of
1637 registered contacts will remain the same.
1638
1639 If flag parameter is set to non-zero value then only contacts that have
1640 the specified flags set will be returned. It is, for example, possible
1641 to list only contacts that are behind NAT.
1642
1643 Meaning of the parameters is as follows:
1644 * void* buf - Buffer for returning contacts.
1645
1646 * int len - Length of the buffer.
1647
1648 * unsigned int flags - Flags that must be set.
1649
1650 1.13. ul_update_ucontact(contact, expires, q, callid, cseq, set, res, ua,
1651 sock)
1652
1653 The function updates contact with new values.
1654
1655 Meaning of the parameters is as follows:
1656 * ucontact_t* contact - Contact URI.
1657 * time_t expires - Expires of the contact in absolute value.
1658 * float q - q value of the contact.
1659 * str* callid - Call-ID of the REGISTER message that contained the
1660 contact.
1661 * int cseq - CSeq of the REGISTER message that contained the contact.
1662 * unsigned int set - OR value of flags to be set.
1663 * unsigned int res - OR value of flags to be reset.
1664 * str* ua - User-Agent of the REGISTER message that contained the
1665 contact.
1666 * struct socket_info *sock - socket on which the REGISTER message was
1667 received on.
1668
1669 1.14. ul_bind_ursloc(api)
1670
1671 The function imports all functions that are exported by the USRLOC
1672 module. Overs for other modules which want to user the internal USRLOC
1673 API an easy way to load and access the functions.
1674
1675 Meaning of the parameters is as follows:
1676 * usrloc_api_t* api - USRLOC API
1677
1678 1.15. ul_register_ulcb(type, callback, param)
1679
1680 The function register with USRLOC a callback function to be called when
1681 some event occurs inside USRLOC.
1682
1683 Meaning of the parameters is as follows:
1684 * int types - type of event for which the callback should be called
1685 (see usrloc/ul_callback.h).
1686 * ul_cb f - callback function; see usrloc/ul_callback.h for
1687 prototype.
1688 * void *param - some parameter to be passed to the callback each time
1689 when it is called.
1690
1691 1.16. ul_get_num_users()
1692
1693 The function loops through all domains summing up the number of users.