Browse code

cfgutils documentation

Olle E. Johansson authored on 02/03/2013 06:56:21
Showing 3 changed files
... ...
@@ -18,14 +18,18 @@ Jiri Kuthan
18 18
 
19 19
    <jiri@iptel.org>
20 20
 
21
+Olle E. Johansson
22
+
23
+   <oej@edvina.net>
24
+
21 25
 Edited by
22 26
 
23 27
 Daniel-Constantin Mierla
24 28
 
25 29
    <miconda@gmail.com>
26 30
 
27
-   Copyright � 2007, 2008, 2004 1und1 Internet AG, BASIS AudioNet GmbH,
28
-   Elena-Ramona Modroiu, FhG FOKUS
31
+   Copyright � 2013, 2007, 2008, 2004 Edvina AB, 1und1 Internet AG, BASIS
32
+   AudioNet GmbH, Elena-Ramona Modroiu, FhG FOKUS
29 33
      __________________________________________________________________
30 34
 
31 35
    Table of Contents
... ...
@@ -59,7 +63,9 @@ Daniel-Constantin Mierla
59 63
               4.14. is_gflag(flag)
60 64
               4.15. lock(key)
61 65
               4.16. unlock(key)
62
-              4.17. core_hash(string1, string2, size)
66
+              4.17. check_route_exists(route)
67
+              4.18. route_if_exists(route)
68
+              4.19. core_hash(string1, string2, size)
63 69
 
64 70
         5. MI Commands
65 71
 
... ...
@@ -99,17 +105,19 @@ Daniel-Constantin Mierla
99 105
    1.18. is_gflag() usage
100 106
    1.19. lock() usage
101 107
    1.20. unlock() usage
102
-   1.21. core_hash() usage
103
-   1.22. rand_set_prob usage
104
-   1.23. rand_reset_prob usage
105
-   1.24. rand_get_prob usage
106
-   1.25. check_config_hash usage
107
-   1.26. get_config_hash usage
108
-   1.27. set_gflag usage
109
-   1.28. reset_gflag usage
110
-   1.29. is_gflag usage
111
-   1.30. get_gflags usage
112
-   1.31. RANDOM pseudo-variable usage
108
+   1.21. check_route_exists() usage
109
+   1.22. route_if_exists() usage
110
+   1.23. core_hash() usage
111
+   1.24. rand_set_prob usage
112
+   1.25. rand_reset_prob usage
113
+   1.26. rand_get_prob usage
114
+   1.27. check_config_hash usage
115
+   1.28. get_config_hash usage
116
+   1.29. set_gflag usage
117
+   1.30. reset_gflag usage
118
+   1.31. is_gflag usage
119
+   1.32. get_gflags usage
120
+   1.33. RANDOM pseudo-variable usage
113 121
 
114 122
 Chapter 1. Admin Guide
115 123
 
... ...
@@ -142,7 +150,9 @@ Chapter 1. Admin Guide
142 150
         4.14. is_gflag(flag)
143 151
         4.15. lock(key)
144 152
         4.16. unlock(key)
145
-        4.17. core_hash(string1, string2, size)
153
+        4.17. check_route_exists(route)
154
+        4.18. route_if_exists(route)
155
+        4.19. core_hash(string1, string2, size)
146 156
 
147 157
    5. MI Commands
148 158
 
... ...
@@ -281,7 +291,9 @@ modparam("cfgutils", "lock_set_size", 4)
281 291
    4.14. is_gflag(flag)
282 292
    4.15. lock(key)
283 293
    4.16. unlock(key)
284
-   4.17. core_hash(string1, string2, size)
294
+   4.17. check_route_exists(route)
295
+   4.18. route_if_exists(route)
296
+   4.19. core_hash(string1, string2, size)
285 297
 
286 298
 4.1. rand_event()
287 299
 
... ...
@@ -326,7 +338,7 @@ rand_reset_prob();
326 338
 ...
327 339
 rand_get_prob();
328 340
 
329
-4.5. sleep(time)
341
+4.5.  sleep(time)
330 342
 
331 343
    Waits "time" seconds.
332 344
 
... ...
@@ -341,7 +353,7 @@ rand_get_prob();
341 353
 sleep("1");
342 354
 ...
343 355
 
344
-4.6. usleep(time)
356
+4.6.  usleep(time)
345 357
 
346 358
    Waits "time" milli-seconds.
347 359
 
... ...
@@ -356,7 +368,7 @@ sleep("1");
356 368
 usleep("500");
357 369
 ...
358 370
 
359
-4.7. abort()
371
+4.7.  abort()
360 372
 
361 373
    Debugging function that aborts the server. Depending on the
362 374
    configuration of the server a core dump will be created.
... ...
@@ -369,7 +381,7 @@ usleep("500");
369 381
 abort();
370 382
 ...
371 383
 
372
-4.8. pkg_status()
384
+4.8.  pkg_status()
373 385
 
374 386
    Debugging function that dumps the status for the private (PKG) memory.
375 387
    This information is logged to the default log facility, depending on
... ...
@@ -384,7 +396,7 @@ abort();
384 396
 pkg_status();
385 397
 ...
386 398
 
387
-4.9. pkg_summary()
399
+4.9.  pkg_summary()
388 400
 
389 401
    Debugging function that dumps the summary for the private (PKG) memory
390 402
    usage. This information is logged to the default log facility,
... ...
@@ -399,7 +411,7 @@ pkg_status();
399 411
 pkg_summary();
400 412
 ...
401 413
 
402
-4.10. shm_status()
414
+4.10.  shm_status()
403 415
 
404 416
    Debugging function that dumps the status for the shared (SHM) memory.
405 417
    This information is logged to the default log facility, depending on
... ...
@@ -414,7 +426,7 @@ pkg_summary();
414 426
 shm_status();
415 427
 ...
416 428
 
417
-4.11. shm_summary()
429
+4.11.  shm_summary()
418 430
 
419 431
    Debugging function that dumps the summary for the shared (SHM) memory
420 432
    usage. This information is logged to the default log facility,
... ...
@@ -508,7 +520,42 @@ lock("$rU");
508 520
 unlock("$rU");
509 521
 ...
510 522
 
511
-4.17. core_hash(string1, string2, size)
523
+4.17. check_route_exists(route)
524
+
525
+   Check if a route block exists
526
+
527
+   Parameters:
528
+
529
+   "name" of a route block in the config file, like "route[FROGJUMP]"
530
+
531
+   This function can be used from any route. You can only check for
532
+   route[] blocks, not reply, event or other routes.
533
+
534
+   Example 1.21. check_route_exists() usage
535
+...
536
+if(check_route_exists("FROGJUMP") {
537
+        $var(jumping_frogs) = 1;
538
+};
539
+...
540
+
541
+4.18. route_if_exists(route)
542
+
543
+   Execute a routing block only if it is defined. If it's not defined,
544
+   silently move to the next action in the configuration script.
545
+
546
+   Parameters:
547
+
548
+   "name" of a route block in the config file, like "route[FROGJUMP]"
549
+
550
+   This function can be used from any route. You can only execute it for
551
+   route[] blocks, not reply, event or other routes.
552
+
553
+   Example 1.22. route_if_exists() usage
554
+...
555
+route_if_exists("PRESENCE_SANTA_CLAUS");
556
+...
557
+
558
+4.19. core_hash(string1, string2, size)
512 559
 
513 560
    Exported function that enables the core_hash() function to be used from
514 561
    the configuration file.
... ...
@@ -525,7 +572,7 @@ unlock("$rU");
525 572
 
526 573
    This function can be used from ANY_ROUTE.
527 574
 
528
-   Example 1.21. core_hash() usage
575
+   Example 1.23. core_hash() usage
529 576
 ...
530 577
 core_hash("$ci", "", 4);
531 578
 ...
... ...
@@ -554,7 +601,7 @@ core_hash("$ci", "", 4);
554 601
 
555 602
    The parameter value must be a number from 0 to 100.
556 603
 
557
-   Example 1.22. rand_set_prob usage
604
+   Example 1.24. rand_set_prob usage
558 605
 ...
559 606
 $ kamctl fifo rand_set_prob 10
560 607
 ...
... ...
@@ -565,7 +612,7 @@ $ kamctl fifo rand_set_prob 10
565 612
 
566 613
    This command don't need a parameter.
567 614
 
568
-   Example 1.23. rand_reset_prob usage
615
+   Example 1.25.  rand_reset_prob usage
569 616
 ...
570 617
 $ kamctl fifo rand_reset_prob
571 618
 ...
... ...
@@ -576,7 +623,7 @@ $ kamctl fifo rand_reset_prob
576 623
 
577 624
    The function return the actual probability value.
578 625
 
579
-   Example 1.24. rand_get_prob usage
626
+   Example 1.26. rand_get_prob usage
580 627
 ...
581 628
 $ kamctl fifo get_prob
582 629
 The actual probability is 50 percent.
... ...
@@ -590,7 +637,7 @@ The actual probability is 50 percent.
590 637
    there are not identical, 404 if no file for hashing has been configured
591 638
    and 500 on errors. Additional a short text message is printed.
592 639
 
593
-   Example 1.25. check_config_hash usage
640
+   Example 1.27. check_config_hash usage
594 641
 ...
595 642
 $ kamctl fifo check_config_hash
596 643
 The actual config file hash is identical to the stored one.
... ...
@@ -603,7 +650,7 @@ The actual config file hash is identical to the stored one.
603 650
    The function returns 200 OK and the hash value on success or 404 if no
604 651
    file for hashing has been configured.
605 652
 
606
-   Example 1.26. get_config_hash usage
653
+   Example 1.28. get_config_hash usage
607 654
 ...
608 655
 $ kamctl fifo get_config_hash
609 656
 1580a37104eb4de69ab9f31ce8d6e3e0
... ...
@@ -616,7 +663,7 @@ $ kamctl fifo get_config_hash
616 663
    The parameter value must be a bitmask in decimal or hexadecimal format.
617 664
    The bitmask has a 32 bit size.
618 665
 
619
-   Example 1.27. set_gflag usage
666
+   Example 1.29. set_gflag usage
620 667
 ...
621 668
 $ kamctl fifo set_gflag 1
622 669
 $ kamctl fifo set_gflag 0x3
... ...
@@ -629,7 +676,7 @@ $ kamctl fifo set_gflag 0x3
629 676
    The parameter value must be a bitmask in decimal or hexadecimal format.
630 677
    The bitmask has a 32 bit size.
631 678
 
632
-   Example 1.28. reset_gflag usage
679
+   Example 1.30.  reset_gflag usage
633 680
 ...
634 681
 $ kamctl fifo reset_gflag 1
635 682
 $ kamctl fifo reset_gflag 0x3
... ...
@@ -645,7 +692,7 @@ $ kamctl fifo reset_gflag 0x3
645 692
    The function returns TRUE if all the flags from the set are set and
646 693
    FALSE if at least one is not set.
647 694
 
648
-   Example 1.29. is_gflag usage
695
+   Example 1.31. is_gflag usage
649 696
 ...
650 697
 $ kamctl fifo set_gflag 1024
651 698
 $ kamctl fifo is_gflag 1024
... ...
@@ -668,7 +715,7 @@ TRUE
668 715
    Return the bitmap with all flags. The function gets no parameters and
669 716
    returns the bitmap in hexadecimal and decimal format.
670 717
 
671
-   Example 1.30. get_gflags usage
718
+   Example 1.32.  get_gflags usage
672 719
 ...
673 720
 $ kamctl fifo get_gflags
674 721
 0x3039
... ...
@@ -683,7 +730,7 @@ $ kamctl fifo get_gflags
683 730
 
684 731
    Returns a random value from the [0 - 2^31) range.
685 732
 
686
-   Example 1.31. RANDOM pseudo-variable usage
733
+   Example 1.33. RANDOM pseudo-variable usage
687 734
 ...
688 735
 if (rand_event()) {
689 736
   $avp(i:10) = ($RANDOM / 16777216); # 2^24
... ...
@@ -37,6 +37,11 @@
37 37
 		<surname>Kuthan</surname>
38 38
 		<email>jiri@iptel.org</email>
39 39
 		</author>
40
+		<author>
41
+		<firstname>Olle E.</firstname>
42
+		<surname>Johansson</surname>
43
+		<email>oej@edvina.net</email>
44
+		</author>
40 45
 		<editor>
41 46
 		<firstname>Daniel-Constantin</firstname>
42 47
 		<surname>Mierla</surname>
... ...
@@ -44,9 +49,11 @@
44 49
 		</editor>
45 50
 	</authorgroup>
46 51
 	<copyright>
52
+		<year>2013</year>
47 53
 		<year>2007</year>
48 54
 		<year>2008</year>
49 55
 		<year>2004</year>
56
+		<holder>Edvina AB</holder>
50 57
 		<holder>1und1 Internet AG</holder>
51 58
 		<holder>BASIS AudioNet GmbH</holder>
52 59
 		<holder>Elena-Ramona Modroiu</holder>
... ...
@@ -521,6 +521,53 @@ lock("$rU");
521 521
 ...
522 522
 unlock("$rU");
523 523
 ...
524
+</programlisting>
525
+		</example>
526
+	</section>
527
+	<section>
528
+		<title><function moreinfo="none">check_route_exists(route)</function></title>
529
+		<para>
530
+		Check if a route block exists
531
+		</para>
532
+		<para>Parameters:</para>
533
+		<para>
534
+		<quote>name</quote> of a route block in the config file, like <quote>route[FROGJUMP]</quote>
535
+		</para>
536
+		<para>
537
+		This function can be used from any route. You can only check for
538
+		route[] blocks, not reply, event or other routes.
539
+		</para>
540
+		<example>
541
+		<title><function moreinfo="none">check_route_exists()</function> usage</title>
542
+		<programlisting format="linespecific">
543
+...
544
+if(check_route_exists("FROGJUMP") {
545
+	$var(jumping_frogs) = 1;
546
+};
547
+...
548
+</programlisting>
549
+		</example>
550
+	</section>
551
+	<section>
552
+		<title><function moreinfo="none">route_if_exists(route)</function></title>
553
+		<para>
554
+		Execute a routing block only if it is defined. If it's not defined, silently
555
+		move to the next action in the configuration script.
556
+		</para>
557
+		<para>Parameters:</para>
558
+		<para>
559
+		<quote>name</quote> of a route block in the config file, like <quote>route[FROGJUMP]</quote>
560
+		</para>
561
+		<para>
562
+		This function can be used from any route. You can only execute it for
563
+		route[] blocks, not reply, event or other routes.
564
+		</para>
565
+		<example>
566
+		<title><function moreinfo="none">route_if_exists()</function> usage</title>
567
+		<programlisting format="linespecific">
568
+...
569
+route_if_exists("PRESENCE_SANTA_CLAUS");
570
+...
524 571
 </programlisting>
525 572
 		</example>
526 573
 	</section>