Debian Codegraph @

src/modules/ims_registrar_scscf/doc/ims_registrar_scscf_admin.xml

raw
1 <?xml version="1.0" encoding="ISO-8859-1"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4 <!-- Include general documentation entities -->
5 <!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
6 %docentities;
7 ]>
8 <!-- Module User's Guide -->
9 <chapter>
10 <title>&adminguide;</title>
11
12 <section>
13 <title>Overview</title>
14
15 <para>This module contains REGISTER processing logic for the S-CSCF. The
16 'storage engine' of this module is provided by the ims_usrloc_scscf
17 module:</para>
18 </section>
19
20 <section>
21 <title>Dependencies</title>
22
23 <section>
24 <title>&kamailio; Modules</title>
25
26 <para>The following modules must be loaded before this module:
27 <itemizedlist>
28 <listitem>
29 <para><emphasis>CDP</emphasis></para>
30 </listitem>
31
32 <listitem>
33 <para><emphasis>CDP_AVP</emphasis></para>
34 </listitem>
35
36 <listitem>
37 <para><emphasis>TM</emphasis></para>
38 </listitem>
39
40 <listitem>
41 <para><emphasis>ims_usrloc_scscf</emphasis></para>
42 </listitem>
43 </itemizedlist></para>
44 </section>
45
46 <section>
47 <title>External Libraries or Applications</title>
48
49 <para>The following libraries or applications must be installed before
50 running &kamailio; with this module loaded: <itemizedlist>
51 <listitem>
52 <para><emphasis>LibXML2 - used for parsing the XML Subscription
53 information obtained from the HSS (Home Subscriber
54 Server)</emphasis></para>
55 </listitem>
56 </itemizedlist></para>
57 </section>
58 </section>
59
60 <section>
61 <title>Parameters</title>
62
63 <section>
64 <title>default_expires (int)</title>
65
66 <para>If the processed message contains neither Expires HFs nor expires
67 contact parameters, this value will be used for newly created S-CSCF
68 usrloc records. The parameter contains number of second to expire (for
69 example use 3600 for one hour). If it is set to a lower value than the
70 min_expires parameter then it will be ignored. This parameter can be
71 modified via ser config framework. A random value in a specific interval
72 can be selected by using the default_expires_range parameter</para>
73
74 <para><emphasis> Default value is 3600. </emphasis></para>
75
76 <example>
77 <title>Set <varname>default_expires</varname> parameter</title>
78
79 <programlisting format="linespecific">...
80 modparam("ims_registrar_scscf", "default_expires", 3600)
81 ...</programlisting>
82 </example>
83 </section>
84
85 <section>
86 <title>default_expires_range (int)</title>
87
88 <para>This parameter specifies that the expiry used for newly created
89 S-CSCF usrloc records are not fixed(when default_expires applies), but a
90 random value in the intervalrdq [default_expires-default_expires_range%,
91 default_expires+default_expires_range%]. The value is between 0 and 100
92 and represent the maximum percentage from default_expires that will be
93 subtracted or added when computing the value. Default in 0, meaning
94 default_expires is left unmodified. This parameter can be modified via
95 ser config framework.</para>
96
97 <para><emphasis> Default value is 0. </emphasis></para>
98
99 <example>
100 <title>Set <varname>default_expires_range </varname>parameter</title>
101
102 <programlisting format="linespecific">...
103 modparam("ims_registrar_scscf", "default_expires_range", 30) # +- 30% from default_expires
104 ...</programlisting>
105 </example>
106 </section>
107
108 <section>
109 <title>min_expires (int)</title>
110
111 <para>The minimum expires value of a Contact, values lower than this
112 minimum will be automatically set to the minimum. Value 0 disables the
113 checking. This parameter can be modified via ser config
114 framework.</para>
115
116 <para><emphasis> Default value is 60. </emphasis></para>
117
118 <example>
119 <title>Set <varname>min_expires</varname>parameter</title>
120
121 <programlisting format="linespecific">...
122 modparam("ims_registrar_scscf", "min_expires", 1800)
123 ...</programlisting>
124 </example>
125 </section>
126
127 <section>
128 <title>max_expires (int)</title>
129
130 <para>The maximum expires value of a Contact, values higher than this
131 maximum will be automatically set to the maximum. Value 0 disables the
132 checking. This parameter can be modified via ser config
133 framework.</para>
134
135 <para><emphasis> Default value is 0. </emphasis></para>
136
137 <example>
138 <title>Set <varname>max_expires</varname>parameter</title>
139
140 <programlisting format="linespecific">...
141 modparam("ims_registrar_scscf", "max_expires", 3600)
142 ...</programlisting>
143 </example>
144 </section>
145
146 <section>
147 <title>subscription_default_expires (int)</title>
148
149 <para>If the processed message contains neither Expires HFs nor expires
150 contact parameters, this value will be used for newly created
151 subscriptions. The parameter contains number of second to expire (for
152 example use 3600 for one hour). If it is set to a lower value than the
153 subscription_min_expires parameter then it will be ignored. A random
154 value in a specific interval can be selected by using the
155 subscription_expires_range parameter</para>
156
157 <para><emphasis> Default value is 3600. </emphasis></para>
158
159 <example>
160 <title>Set <varname>subscription_default_expires</varname>
161 parameter</title>
162
163 <programlisting format="linespecific">...
164 modparam("ims_registrar_scscf", "subscription_default_expires", 3600)
165 ...</programlisting>
166 </example>
167 </section>
168
169 <section>
170 <title>subscription_expires_range (int)</title>
171
172 <para>This parameter specifies that the expiry used for newly created
173 subscriptions are not fixed(when subscription_default_expires applies),
174 but a random value in the interval
175 [subscription_default_expires-subscription_expires_range%,
176 subscription_default_expires+subscription_expires_range%]. The value is
177 between 0 and 100 and represent the maximum percentage from
178 subscription_default_expires that will be subtracted or added when
179 computing the value. Default in 0, meaning subscription_default_expires
180 is left unmodified.</para>
181
182 <para><emphasis> Default value is 0. </emphasis></para>
183
184 <example>
185 <title>Set <varname>subscription_expires_range
186 </varname>parameter</title>
187
188 <programlisting format="linespecific">...
189 modparam("ims_registrar_scscf", "subscription_expires_range", 30) # +- 30% from subscription_expires_range
190 ...</programlisting>
191 </example>
192 </section>
193
194 <section>
195 <title>subscription_min_expires (int)</title>
196
197 <para>The minimum expires value of a subscription, values lower than
198 this minimum will be automatically set to the minimum. Value 0 disables
199 the checking.</para>
200
201 <para><emphasis> Default value is 10. </emphasis></para>
202
203 <example>
204 <title>Set
205 <varname>subscription_min_expires</varname>parameter</title>
206
207 <programlisting format="linespecific">...
208 modparam("subscription_min_expires", "min_expires", 1800)
209 ...</programlisting>
210 </example>
211 </section>
212
213 <section>
214 <title>subscription_max_expires (int)</title>
215
216 <para>The maximum expires value of a subscription, values higher than
217 this maximum will be automatically set to the maximum. Value 0 disables
218 the checking.</para>
219
220 <para><emphasis> Default value is 1000000. </emphasis></para>
221
222 <example>
223 <title>Set
224 <varname>subscription_max_expires</varname>parameter</title>
225
226 <programlisting format="linespecific">...
227 modparam("ims_registrar_scscf", "subscription_max_expires", 3600)
228 ...</programlisting>
229 </example>
230 </section>
231
232 <section>
233 <title>ue_unsubscribe_on_dereg (int)</title>
234
235 <para>Many UEs do not unsubscribe on de-register, therefor if the
236 parameter is set to 0, the default, any subscription of that subscriber
237 will be removed and NOTIFY will be not sent. To disable this behaviour set this
238 parameter to 1.</para>
239
240 <para><emphasis> Default value is 0 (disabled)</emphasis></para>
241
242 <example>
243 <title>Set <varname>user_data_dtd</varname>parameter</title>
244
245 <programlisting format="linespecific">...
246 modparam("ims_registrar_scscf", "ue_unsubscribe_on_dereg", 1)
247 ...</programlisting>
248 </example>
249 </section>
250
251 <section>
252 <title>user_data_dtd (string)</title>
253
254 <para>DTD to check the user data received in SAA (Server Assignment
255 Answer).</para>
256
257 <para><emphasis> Default value is NULL (none). </emphasis></para>
258
259 <example>
260 <title>Set <varname>user_data_dtd</varname>parameter</title>
261
262 <programlisting format="linespecific">...
263 modparam("ims_registrar_scscf", "user_data_dtd", "/usr/local/etc/kamailio/CxDataType_Rel7.dtd")
264 ...</programlisting>
265 </example>
266 </section>
267
268 <section>
269 <title>user_data_xsd (string)</title>
270
271 <para>XSD to check the user data received in SAA (Server Assignment
272 Answer).</para>
273
274 <para><emphasis> Default value is NULL (none). </emphasis></para>
275
276 <example>
277 <title>Set <varname>user_data_xsd</varname>parameter</title>
278
279 <programlisting format="linespecific">...
280 modparam("ims_registrar_scscf", "user_data_xsd", "/usr/local/etc/kamailio/CxDataType_Rel7.xsd")
281 ...</programlisting>
282 </example>
283 </section>
284
285 <section>
286 <title>support_wildcardPSI (int)</title>
287
288 <para>indicate support for wildcard PSI is subscription profile
289 (SAA)</para>
290
291 <para><emphasis> Default value is 0. </emphasis></para>
292
293 <example>
294 <title>Set <varname>support_wildcardPSI</varname>parameter</title>
295
296 <programlisting format="linespecific">...
297 modparam("ims_registrar_scscf", "support_wildcardPSI", 1)
298 ...</programlisting>
299 </example>
300 </section>
301
302 <section>
303 <title>scscf_name (string)</title>
304
305 <para>The name of the S-CSCF</para>
306
307 <para><emphasis> Default value is sip:scscf.ims.smilecoms.com:6060.
308 </emphasis></para>
309
310 <example>
311 <title>Set <varname>scscf_name</varname>parameter</title>
312
313 <programlisting format="linespecific">...
314 modparam("ims_registrar_scscf", "scscf_name", "sip:scscf2.ims.smilecoms.com:6060")
315 ...</programlisting>
316 </example>
317 </section>
318
319 <section>
320 <title>store_profile_dereg (int)</title>
321
322 <para>Should the subscription profile be stored on
323 de-registration</para>
324
325 <para><emphasis> Default value 0.</emphasis></para>
326
327 <example>
328 <title>Set <varname>store_profile_dereg</varname>parameter</title>
329
330 <programlisting format="linespecific">...
331 modparam("ims_registrar_scscf", "store_profile_dereg", 1)
332 ...</programlisting>
333 </example>
334 </section>
335
336 <section>
337 <title>cxdx_dest_realm (string)</title>
338
339 <para>Destination realm to be used in Diameter messages</para>
340
341 <para><emphasis> Default value "ims.smilecoms.com"</emphasis></para>
342
343 <example>
344 <title>Set <varname>cxdx_dest_realm</varname>parameter</title>
345
346 <programlisting format="linespecific">...
347 modparam("ims_registrar_scscf", "cxdx_dest_realm", "my.domain,org")
348 ...</programlisting>
349 </example>
350 </section>
351
352 <section>
353 <title>cxdx_forced_peer (string)</title>
354
355 <para>FQDN of Diameter Peer (HSS) to use for communication (SAR). If you
356 use this, the routing defined in your diameter xml configuration file
357 (CDP) will be ignored and as a result you will lose the benefits of load
358 balancing and failover.</para>
359
360 <para><emphasis> Default value NULL (none)</emphasis></para>
361
362 <example>
363 <title>Set <varname>cxdx_forced_peer</varname>parameter</title>
364
365 <programlisting format="linespecific">...
366 modparam("ims_registrar_scscf", "cxdx_forced_peer", "hss.ims.smilecoms.com")
367 ...</programlisting>
368 </example>
369 </section>
370
371 <section>
372 <title>append_branches (integer)</title>
373
374 <para>The parameter controls how lookup function processes multiple
375 contacts. If there are multiple contacts for the given username in
376 usrloc and this parameter is set to 1, Request-URI will be overwritten
377 with the highest-q rated contact and the rest will be appended to
378 sip_msg structure and can be later used by tm for forking. If the
379 parameter is set to 0, only Request-URI will be overwritten with the
380 highest-q rated contact and the rest will be left unprocessed. This
381 parameter can be modified via Kamailio config framework.</para>
382
383 <para><emphasis> Default value is 0 (disabled)</emphasis></para>
384
385 <example>
386 <title>Set <varname>cxdx_forced_peer</varname>parameter</title>
387
388 <programlisting format="linespecific">...
389 modparam("ims_registrar_scscf", "append_branches", 1)
390 ...</programlisting>
391 </example>
392 </section>
393
394 <section>
395 <title>method_filtering (integer)</title>
396
397 <para>Tells if the contact filtering based on supported methods should
398 be performed during lookup. It's enabled only if it has a non zero
399 value.</para>
400
401 <para><emphasis> Default value is 0 (disabled)</emphasis></para>
402
403 <example>
404 <title>Set <varname>cxdx_forced_peer</varname>parameter</title>
405
406 <programlisting format="linespecific">...
407 modparam("ims_registrar_scscf", "method_filtering", 1)
408 ...</programlisting>
409 </example>
410 </section>
411
412 <section>
413 <title>user_data_always (integer)</title>
414
415 <para>If specified this will make the S-CSCF always request user data
416 from HSS.</para>
417
418 <para><emphasis> Default value is 0 (disabled)</emphasis></para>
419
420 <example>
421 <title>Set <varname>user_data_always</varname>parameter</title>
422
423 <programlisting format="linespecific">...
424 modparam("ims_registrar_scscf", "user_data_always", 1)
425 ...
426 </programlisting>
427 </example>
428 </section>
429
430 <section>
431 <title>error_reply_code (int)</title>
432
433 <para>In certain error conditions, the S-CSCF may not be able to process
434 the request (e.g. in case of database failures). Per default and
435 according to the Specs, the S-CSCF would return a 500 error in this
436 case. However, according to the SIP-Specs for DNS-SRV, this won't
437 trigger a failover, which may be desired.</para>
438
439 <para>This parameter let's you override the default 500 with another
440 return-code (e.g. 503) in order to get the desired behaviour.</para>
441
442 <para><emphasis> Default value is 500. </emphasis></para>
443
444 <example>
445 <title>Set <varname>error_reply_code</varname> parameter</title>
446
447 <programlisting format="linespecific">...
448 modparam("ims_registrar_scscf", "error_reply_code", 503)
449 ...</programlisting>
450 </example>
451 </section>
452
453 <section>
454 <title>skip_multiple_bindings_on_reg_resp (int)</title>
455
456 <para>If set to 1 - on Re-Registration registrar sends in 200 OK reply only
457 current contact in case of multiple bindings.
458 If set to 0 - on Re-Registration registrar sends in 200 OK reply all
459 contacts in case of multiple bindings according to RFC3261.
460 </para>
461
462 <para><emphasis> Default value is 0. </emphasis></para>
463
464 <example>
465 <title>Set <varname>skip_multiple_bindings_on_reg_resp</varname> parameter</title>
466
467 <programlisting format="linespecific">...
468 modparam("ims_registrar_scscf", "skip_multiple_bindings_on_reg_resp", 1)
469 ...</programlisting>
470 </example>
471 </section>
472
473 </section>
474
475 <section>
476 <title>Functions</title>
477
478 <section>
479 <title><function moreinfo="none">save(async_reply_route,
480 domain, mode, flags)</function></title>
481
482 <para>The function processes a REGISTER message. It can add, remove or
483 modify usrloc records depending on Contact and Expires HFs in the
484 REGISTER message. On success and when called from the REQUEST_ROUTE, 200
485 OK will be returned listing all contacts that are currently in usrloc.
486 On an error, error message will be sent with a short description in
487 reason phrase. In case of internal errors the function will return
488 FALSE, otherwise a force to exit the cfg is file is actioned by
489 returning 0 (asynchronous processing)</para>
490
491 <para>Meaning of the parameters is as follows:</para>
492
493 <itemizedlist>
494 <listitem>
495 <para><emphasis>async_reply_route</emphasis>- the route to execute
496 after the save has completed. This is required because the save
497 function is executed asynchronously (Diameter).</para>
498 </listitem>
499
500 <listitem>
501 <para><emphasis>domain</emphasis>- Logical domain within
502 registrar.</para>
503 </listitem>
504
505 <listitem>
506 <para><emphasis>mode</emphasis>- Optional and unused legacy parameter.</para>
507 </listitem>
508
509 <listitem>
510 <para><emphasis>flags</emphasis>- Optional parameter. Valid values:
511 0x01 - Realm is not used when extracting Private Identity from the
512 Authorization header.</para>
513 </listitem>
514 </itemizedlist>
515
516 <para>This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE</para>
517
518 <example>
519 <title><function>save</function> usage</title>
520
521 <programlisting format="linespecific">...
522 if (!impu_registered("location")) {
523 save("PRE_REG_SAR_REPLY","location");
524 }
525 ...
526 </programlisting>
527 </example>
528 </section>
529
530 <section>
531 <title><function moreinfo="none">lookup(domain)</function></title>
532
533 <para>This function extract the IMPU from the Request-URI and tries to
534 find all registered contacts in usrloc. If there are no such contacts,
535 -1 is returned. If there are, Request-URI will be rewritten with the
536 contact that has the highest q value. The rest of the contacts will be
537 appended to the sip msg structure (if append_branches is set) and can be
538 later used by TM module for forking for example...</para>
539
540 <para>If the method filtering option is enabled, the lookup function
541 will only return contacts that support the method of the request being
542 processed (see allows header)</para>
543
544 <para>Meaning of the parameters is as follows:</para>
545
546 <para><itemizedlist>
547 <listitem>
548 <para><emphasis>domain</emphasis> - Logical domain within
549 registrar.</para>
550 </listitem>
551 </itemizedlist></para>
552
553 <para>Return codes:</para>
554
555 <para><itemizedlist>
556 <listitem>
557 <para><emphasis>-1</emphasis> - Not found</para>
558 </listitem>
559
560 <listitem>
561 <para>-2 - Found, but method not allowed (check Allows header for
562 INVITE, MESSAGE, etc).</para>
563 </listitem>
564
565 <listitem>
566 <para>-3 - Error occurred internally during processing</para>
567 </listitem>
568 </itemizedlist></para>
569
570 <para>This function can be used from REQUEST_ROUTE, FAILURE_ROUTE</para>
571
572 <example>
573 <title><function>lookup</function> usage</title>
574
575 <programlisting format="linespecific">...
576 lookup("location");
577 switch ($retcode) {
578 case -1:
579 case -3:
580 sl_send_reply("404", "Not Found");
581 exit;
582 case -2:
583 sl_send_reply("405", "Not Found");
584 exit;
585 };
586 ...
587 </programlisting>
588 </example>
589 </section>
590
591 <section>
592 <title><function
593 moreinfo="none">lookup_path_to_contact(uri)</function></title>
594
595 <para>This function take a URI and tries to find the contact in usrloc.
596 If the contact is found and has a path set, then a path header is added
597 to the SIP message so it can be loose routed.</para>
598
599 <para>Meaning of the parameters is as follows:</para>
600
601 <para><itemizedlist>
602 <listitem>
603 <para>uri - URI of contact to lookup</para>
604 </listitem>
605 </itemizedlist></para>
606
607 <para>Return codes:</para>
608
609 <para><itemizedlist>
610 <listitem>
611 <para><emphasis>1</emphasis> - Success</para>
612 </listitem>
613
614 <listitem>
615 <para>-1 - Failure</para>
616 </listitem>
617 </itemizedlist></para>
618
619 <para>This function can be used from REQUEST_ROUTE, FAILURE_ROUTE</para>
620
621 <example>
622 <title><function>lookup</function> usage</title>
623
624 <programlisting format="linespecific">...
625 lookup_path_to_contact($ruri);
626 ...
627 </programlisting>
628 </example>
629 </section>
630
631 <section>
632 <title><function moreinfo="none">unregister(domain)</function></title>
633
634 <para>This function will remove all bindings for the IMPU found in the
635 Request-URI.</para>
636
637 <para>Meaning of the parameters is as follows:</para>
638
639 <itemizedlist>
640 <listitem>
641 <para><emphasis>Domain</emphasis>- Logical domain within
642 registrar.</para>
643 </listitem>
644 </itemizedlist>
645
646 <para>This function can be used in REQUEST_ROUTE, FAILURE_ROUTE</para>
647
648 <example>
649 <title><function>unregister</function> usage</title>
650
651 <programlisting format="linespecific">...
652 unregister("location");
653 ...
654 </programlisting>
655 </example>
656 </section>
657
658 <section>
659 <title><function moreinfo="none">assign_server_unreg(aysnc_reply_route,
660 domain, direction)</function></title>
661
662 <para>TBD</para>
663
664 <para>used in REQUEST_ROUTE</para>
665 </section>
666
667 <section>
668 <title><function
669 moreinfo="none">impu_registered(domain)</function></title>
670
671 <para>This function checks if the IMPU in the To header is registered in
672 usrloc.</para>
673
674 <para>Meaning of the parameters is as follows:</para>
675
676 <itemizedlist>
677 <listitem>
678 <para><emphasis>domain</emphasis>- Logical domain within
679 registrar.</para>
680 </listitem>
681 </itemizedlist>
682
683 <para>Return codes:</para>
684
685 <itemizedlist>
686 <listitem>
687 <para>1 - True, IMPU exists in registered state in usrloc</para>
688 </listitem>
689
690 <listitem>
691 <para><emphasis>-1 - False, IMPU not registered</emphasis></para>
692 </listitem>
693 </itemizedlist>
694
695 <para>This function can be used in REQUEST_ROUTE, FAILURE_ROUTE</para>
696
697 <example>
698 <title><function>impu_registered</function> usage</title>
699
700 <programlisting format="linespecific">...
701 impu_registered("location");
702 switch ($retcode) {
703 case -1:
704 sl_send_reply("404", "Not Found");
705 exit;
706 case 1:
707 #true, continue with normal processing
708 };
709 ...
710 </programlisting>
711 </example>
712 </section>
713
714 <section>
715 <title><function
716 moreinfo="none">term_impu_registered(domain)</function></title>
717
718 <para>This function checks if the IMPU in the Request-URI is registered
719 in usrloc.</para>
720
721 <para>Meaning of the parameters is as follows:</para>
722
723 <itemizedlist>
724 <listitem>
725 <para><emphasis>domain</emphasis>- Logical domain within
726 registrar.</para>
727 </listitem>
728 </itemizedlist>
729
730 <para>Return codes:</para>
731
732 <itemizedlist>
733 <listitem>
734 <para>1 - True, IMPU exists in registered state in usrloc</para>
735 </listitem>
736
737 <listitem>
738 <para><emphasis>-1 - False, IMPU not registered</emphasis></para>
739 </listitem>
740 </itemizedlist>
741
742 <para>This function can be used in REQUEST_ROUTE, FAILURE_ROUTE</para>
743
744 <example>
745 <title><function>term_impu_registered</function> usage</title>
746
747 <programlisting format="linespecific">...
748 term_impu_registered("location");
749 switch ($retcode) {
750 case -1:
751 sl_send_reply("404", "Not Found");
752 exit;
753 case 1:
754 #true, continue with normal processing
755 };
756 ...
757 </programlisting>
758 </example>
759 </section>
760
761 <section>
762 <title><function moreinfo="none">reg_fetch_contacts(domain, uri,
763 profile)</function></title>
764
765 <para>The function fetches the contacts for 'uri' from table 'domain' to
766 pseudo-variable $ulc(profile) [ulc = ims scscf ulc].</para>
767
768 <para>Meaning of the parameters is as follows:</para>
769
770 <itemizedlist>
771 <listitem>
772 <para><emphasis>domain </emphasis>- Name of table that should be
773 used for the lookup of contact addresses.</para>
774 </listitem>
775
776 <listitem>
777 <para><emphasis>uri</emphasis> - The SIP URI address of the user
778 which to fetch the contact addresses for. It can contain
779 pseudo-variables that are evaluated at runtime.</para>
780 </listitem>
781
782 <listitem>
783 <para><emphasis>profile</emphasis> - Name of $ulc
784 pseudo-variable profile that will store the fetched contacts. It is
785 a static string.</para>
786 </listitem>
787 </itemizedlist>
788
789 <para>This function can be used in REQUEST_ROUTE, FAILURE_ROUTE</para>
790
791 <example>
792 <title><function>reg_fetch_contacts</function> usage</title>
793
794 <programlisting format="linespecific">...
795 reg_fetch_contacts("location", "$ru", "callee");
796 reg_fetch_contacts("location", "sip:[email protected]", "caller");
797 ...
798 </programlisting>
799 </example>
800 </section>
801
802 <section>
803 <title><function
804 moreinfo="none">reg_free_contacts(profile)</function></title>
805
806 <para>The function frees the contacts from pseudo-variable
807 $ulc(profile). Should be called to release the content of a profile.
808 Anyhow, fetching a new contact addresses set over a profile will release
809 any existing data in that profile.</para>
810
811 <para>Meaning of the parameters is as follows:</para>
812
813 <itemizedlist>
814 <listitem>
815 <para><emphasis>profile</emphasis> - Name of $ulc
816 pseudo-variable profile that stores the contacts. It is a static
817 string.</para>
818 </listitem>
819 </itemizedlist>
820
821 <para>This function can be used in REQUEST_ROUTE, FAILURE_ROUTE</para>
822
823 <example>
824 <title><function>reg_free_contacts</function> usage</title>
825
826 <programlisting format="linespecific">...
827 reg_free_contacts("callee");
828 ...
829 </programlisting>
830 </example>
831 </section>
832
833 <section>
834 <title><function
835 moreinfo="none">can_subscribe_to_reg(domain)</function></title>
836
837 <para>This function checks to see that a SUBSCRIBE request is authorised
838 to subscribe to the particular identity. Only 3 entities can
839 subscribe:</para>
840
841 <itemizedlist>
842 <listitem>
843 <para><emphasis>The user agent to its own state</emphasis></para>
844 </listitem>
845
846 <listitem>
847 <para>The P-CSCF specified in the path header for that user</para>
848 </listitem>
849
850 <listitem>
851 <para>Application Server (AS) not yet implemented</para>
852 </listitem>
853 </itemizedlist>
854
855 <para>Meaning of the parameters is as follows:</para>
856
857 <itemizedlist>
858 <listitem>
859 <para><emphasis>domain - Logical domain within
860 registrar.</emphasis></para>
861 </listitem>
862 </itemizedlist>
863
864 <para>This function can be used in REQUEST_ROUTE</para>
865
866 <example>
867 <title><function>can_subscribe_to_reg</function> usage</title>
868
869 <programlisting format="linespecific">...
870 if (can_subscribe_to_reg("location")){
871 $var(ret)= subscribe_to_reg("location");
872 }
873 ...
874 </programlisting>
875 </example>
876 </section>
877
878 <section>
879 <title><function
880 moreinfo="none">subscribe_to_reg(domain)</function></title>
881
882 <para>Save the subscription to the REG event for the UAC or the
883 appropriate P-CSCF (in the path to the UAC).</para>
884
885 <para>Meaning of the parameters is as follows:</para>
886
887 <itemizedlist>
888 <listitem>
889 <para><emphasis>domain - Logical domain within
890 registrar.</emphasis></para>
891 </listitem>
892 </itemizedlist>
893
894 <para>This function can be used in REQUEST_ROUTE</para>
895
896 <example>
897 <title><function>subscribe_to_reg</function> usage</title>
898
899 <programlisting format="linespecific">...
900 if (can_subscribe_to_reg("location")){
901 $var(ret)= subscribe_to_reg("location");
902 }
903 ...
904 </programlisting>
905 </example>
906 </section>
907
908 <section>
909 <title><function
910 moreinfo="none">can_publish_reg(domain)</function></title>
911
912 <para>This function checks to see that a PUBLISH request is authorised
913 to publish for a particular identity. Only 3 entities can
914 publish:</para>
915
916 <itemizedlist>
917 <listitem>
918 <para><emphasis>The user agent to its own state</emphasis></para>
919 </listitem>
920
921 <listitem>
922 <para>The P-CSCF specified in the path header for that user</para>
923 </listitem>
924
925 <listitem>
926 <para>Application Server (AS) not yet implemented</para>
927 </listitem>
928 </itemizedlist>
929
930 <para>Meaning of the parameters is as follows:</para>
931
932 <itemizedlist>
933 <listitem>
934 <para><emphasis>domain - Logical domain within
935 registrar.</emphasis></para>
936 </listitem>
937 </itemizedlist>
938
939 <para>This function can be used in REQUEST_ROUTE</para>
940
941 <example>
942 <title><function>can_publish_reg</function> usage</title>
943
944 <programlisting format="linespecific">...
945 if (can_publish_reg("location")){
946 $var(ret)= publish_reg("location");
947 }
948 ...
949 </programlisting>
950 </example>
951 </section>
952
953 <section>
954 <title><function moreinfo="none">publish_reg(domain)</function></title>
955
956 <para>Save the publish to the REG event for the UAC or the appropriate
957 P-CSCF (in the path to the UAC).</para>
958
959 <para>Meaning of the parameters is as follows:</para>
960
961 <itemizedlist>
962 <listitem>
963 <para><emphasis>domain - Logical domain within
964 registrar.</emphasis></para>
965 </listitem>
966 </itemizedlist>
967
968 <para>This function can be used in REQUEST_ROUTE</para>
969
970 <example>
971 <title><function>publish_reg</function> usage</title>
972
973 <programlisting format="linespecific">...
974 if (can_publish_reg("location")){
975 $var(ret)= publish_reg("location");
976 }
977 ...
978 </programlisting>
979 </example>
980 </section>
981 </section>
982
983 <section>
984 <title>RPC Commands</title>
985
986 <para>exported RPC commands.</para>
987
988 <section>
989 <title>regscscf.dereg_impu</title>
990 <para>Initiate network de-register of IMPU</para>
991 </section>
992 </section>
993
994 <section>
995 <title>Statistics</title>
996
997 <para>Exported statistics are listed in the next sections.</para>
998
999 <section>
1000 <title>registered contacts</title>
1001
1002 <para>Number of AOR contacts in registered state - cannot be
1003 reset.</para>
1004 </section>
1005
1006 <section>
1007 <title>impus</title>
1008
1009 <para>Number of IMPUs - cannot be reset.</para>
1010 </section>
1011
1012 <section>
1013 <title>expired contacts</title>
1014
1015 <para>Number of expired contacts - can be reset.</para>
1016 </section>
1017 </section>
1018 </chapter>