cfgutils documentation

modules/cfgutils/README

@@ -18,14 +18,18 @@ Jiri Kuthan
 
    <[email protected]>
 
+Olle E. Johansson
+
+   <[email protected]>
+
 Edited by
 
 Daniel-Constantin Mierla
 
    <[email protected]>
 
-   Copyright © 2007, 2008, 2004 1und1 Internet AG, BASIS AudioNet GmbH,
-   Elena-Ramona Modroiu, FhG FOKUS
+   Copyright © 2013, 2007, 2008, 2004 Edvina AB, 1und1 Internet AG, BASIS
+   AudioNet GmbH, Elena-Ramona Modroiu, FhG FOKUS
      __________________________________________________________________
 
    Table of Contents
@@ -59,7 +63,9 @@ Daniel-Constantin Mierla
               4.14. is_gflag(flag)
               4.15. lock(key)
               4.16. unlock(key)
-              4.17. core_hash(string1, string2, size)
+              4.17. check_route_exists(route)
+              4.18. route_if_exists(route)
+              4.19. core_hash(string1, string2, size)
 
         5. MI Commands
 
@@ -99,17 +105,19 @@ Daniel-Constantin Mierla
    1.18. is_gflag() usage
    1.19. lock() usage
    1.20. unlock() usage
-   1.21. core_hash() usage
-   1.22. rand_set_prob usage
-   1.23. rand_reset_prob usage
-   1.24. rand_get_prob usage
-   1.25. check_config_hash usage
-   1.26. get_config_hash usage
-   1.27. set_gflag usage
-   1.28. reset_gflag usage
-   1.29. is_gflag usage
-   1.30. get_gflags usage
-   1.31. RANDOM pseudo-variable usage
+   1.21. check_route_exists() usage
+   1.22. route_if_exists() usage
+   1.23. core_hash() usage
+   1.24. rand_set_prob usage
+   1.25. rand_reset_prob usage
+   1.26. rand_get_prob usage
+   1.27. check_config_hash usage
+   1.28. get_config_hash usage
+   1.29. set_gflag usage
+   1.30. reset_gflag usage
+   1.31. is_gflag usage
+   1.32. get_gflags usage
+   1.33. RANDOM pseudo-variable usage
 
 Chapter 1. Admin Guide
 
@@ -142,7 +150,9 @@ Chapter 1. Admin Guide
         4.14. is_gflag(flag)
         4.15. lock(key)
         4.16. unlock(key)
-        4.17. core_hash(string1, string2, size)
+        4.17. check_route_exists(route)
+        4.18. route_if_exists(route)
+        4.19. core_hash(string1, string2, size)
 
    5. MI Commands
 
@@ -281,7 +291,9 @@ modparam("cfgutils", "lock_set_size", 4)
    4.14. is_gflag(flag)
    4.15. lock(key)
    4.16. unlock(key)
-   4.17. core_hash(string1, string2, size)
+   4.17. check_route_exists(route)
+   4.18. route_if_exists(route)
+   4.19. core_hash(string1, string2, size)
 
 4.1. rand_event()
 
@@ -326,7 +338,7 @@ rand_reset_prob();
 ...
 rand_get_prob();
 
-4.5. sleep(time)
+4.5.  sleep(time)
 
    Waits "time" seconds.
 
@@ -341,7 +353,7 @@ rand_get_prob();
 sleep("1");
 ...
 
-4.6. usleep(time)
+4.6.  usleep(time)
 
    Waits "time" milli-seconds.
 
@@ -356,7 +368,7 @@ sleep("1");
 usleep("500");
 ...
 
-4.7. abort()
+4.7.  abort()
 
    Debugging function that aborts the server. Depending on the
    configuration of the server a core dump will be created.
@@ -369,7 +381,7 @@ usleep("500");
 abort();
 ...
 
-4.8. pkg_status()
+4.8.  pkg_status()
 
    Debugging function that dumps the status for the private (PKG) memory.
    This information is logged to the default log facility, depending on
@@ -384,7 +396,7 @@ abort();
 pkg_status();
 ...
 
-4.9. pkg_summary()
+4.9.  pkg_summary()
 
    Debugging function that dumps the summary for the private (PKG) memory
    usage. This information is logged to the default log facility,
@@ -399,7 +411,7 @@ pkg_status();
 pkg_summary();
 ...
 
-4.10. shm_status()
+4.10.  shm_status()
 
    Debugging function that dumps the status for the shared (SHM) memory.
    This information is logged to the default log facility, depending on
@@ -414,7 +426,7 @@ pkg_summary();
 shm_status();
 ...
 
-4.11. shm_summary()
+4.11.  shm_summary()
 
    Debugging function that dumps the summary for the shared (SHM) memory
    usage. This information is logged to the default log facility,
@@ -508,7 +520,42 @@ lock("$rU");
 unlock("$rU");
 ...
 
-4.17. core_hash(string1, string2, size)
+4.17. check_route_exists(route)
+
+   Check if a route block exists
+
+   Parameters:
+
+   "name" of a route block in the config file, like "route[FROGJUMP]"
+
+   This function can be used from any route. You can only check for
+   route[] blocks, not reply, event or other routes.
+
+   Example 1.21. check_route_exists() usage
+...
+if(check_route_exists("FROGJUMP") {
+        $var(jumping_frogs) = 1;
+};
+...
+
+4.18. route_if_exists(route)
+
+   Execute a routing block only if it is defined. If it's not defined,
+   silently move to the next action in the configuration script.
+
+   Parameters:
+
+   "name" of a route block in the config file, like "route[FROGJUMP]"
+
+   This function can be used from any route. You can only execute it for
+   route[] blocks, not reply, event or other routes.
+
+   Example 1.22. route_if_exists() usage
+...
+route_if_exists("PRESENCE_SANTA_CLAUS");
+...
+
+4.19. core_hash(string1, string2, size)
 
    Exported function that enables the core_hash() function to be used from
    the configuration file.
@@ -525,7 +572,7 @@ unlock("$rU");
 
    This function can be used from ANY_ROUTE.
 
-   Example 1.21. core_hash() usage
+   Example 1.23. core_hash() usage
 ...
 core_hash("$ci", "", 4);
 ...
@@ -554,7 +601,7 @@ core_hash("$ci", "", 4);
 
    The parameter value must be a number from 0 to 100.
 
-   Example 1.22. rand_set_prob usage
+   Example 1.24. rand_set_prob usage
 ...
 $ kamctl fifo rand_set_prob 10
 ...
@@ -565,7 +612,7 @@ $ kamctl fifo rand_set_prob 10
 
    This command don't need a parameter.
 
-   Example 1.23. rand_reset_prob usage
+   Example 1.25.  rand_reset_prob usage
 ...
 $ kamctl fifo rand_reset_prob
 ...
@@ -576,7 +623,7 @@ $ kamctl fifo rand_reset_prob
 
    The function return the actual probability value.
 
-   Example 1.24. rand_get_prob usage
+   Example 1.26. rand_get_prob usage
 ...
 $ kamctl fifo get_prob
 The actual probability is 50 percent.
@@ -590,7 +637,7 @@ The actual probability is 50 percent.
    there are not identical, 404 if no file for hashing has been configured
    and 500 on errors. Additional a short text message is printed.
 
-   Example 1.25. check_config_hash usage
+   Example 1.27. check_config_hash usage
 ...
 $ kamctl fifo check_config_hash
 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.
    The function returns 200 OK and the hash value on success or 404 if no
    file for hashing has been configured.
 
-   Example 1.26. get_config_hash usage
+   Example 1.28. get_config_hash usage
 ...
 $ kamctl fifo get_config_hash
 1580a37104eb4de69ab9f31ce8d6e3e0
@@ -616,7 +663,7 @@ $ kamctl fifo get_config_hash
    The parameter value must be a bitmask in decimal or hexadecimal format.
    The bitmask has a 32 bit size.
 
-   Example 1.27. set_gflag usage
+   Example 1.29. set_gflag usage
 ...
 $ kamctl fifo set_gflag 1
 $ kamctl fifo set_gflag 0x3
@@ -629,7 +676,7 @@ $ kamctl fifo set_gflag 0x3
    The parameter value must be a bitmask in decimal or hexadecimal format.
    The bitmask has a 32 bit size.
 
-   Example 1.28. reset_gflag usage
+   Example 1.30.  reset_gflag usage
 ...
 $ kamctl fifo reset_gflag 1
 $ kamctl fifo reset_gflag 0x3
@@ -645,7 +692,7 @@ $ kamctl fifo reset_gflag 0x3
    The function returns TRUE if all the flags from the set are set and
    FALSE if at least one is not set.
 
-   Example 1.29. is_gflag usage
+   Example 1.31. is_gflag usage
 ...
 $ kamctl fifo set_gflag 1024
 $ kamctl fifo is_gflag 1024
@@ -668,7 +715,7 @@ TRUE
    Return the bitmap with all flags. The function gets no parameters and
    returns the bitmap in hexadecimal and decimal format.
 
-   Example 1.30. get_gflags usage
+   Example 1.32.  get_gflags usage
 ...
 $ kamctl fifo get_gflags
 0x3039
@@ -683,7 +730,7 @@ $ kamctl fifo get_gflags
 
    Returns a random value from the [0 - 2^31) range.
 
-   Example 1.31. RANDOM pseudo-variable usage
+   Example 1.33. RANDOM pseudo-variable usage
 ...
 if (rand_event()) {
   $avp(i:10) = ($RANDOM / 16777216); # 2^24

modules/cfgutils/doc/cfgutils.xml

@@ -37,6 +37,11 @@
 		<surname>Kuthan</surname>
 		<email>[email protected]</email>
 		</author>
+		<author>
+		<firstname>Olle E.</firstname>
+		<surname>Johansson</surname>
+		<email>[email protected]</email>
+		</author>
 		<editor>
 		<firstname>Daniel-Constantin</firstname>
 		<surname>Mierla</surname>
@@ -44,9 +49,11 @@
 		</editor>
 	</authorgroup>
 	<copyright>
+		<year>2013</year>
 		<year>2007</year>
 		<year>2008</year>
 		<year>2004</year>
+		<holder>Edvina AB</holder>
 		<holder>1und1 Internet AG</holder>
 		<holder>BASIS AudioNet GmbH</holder>
 		<holder>Elena-Ramona Modroiu</holder>

modules/cfgutils/doc/cfgutils_admin.xml

@@ -521,6 +521,53 @@ lock("$rU");
 ...
 unlock("$rU");
 ...
+</programlisting>
+		</example>
+	</section>
+	<section>
+		<title><function moreinfo="none">check_route_exists(route)</function></title>
+		<para>
+		Check if a route block exists
+		</para>
+		<para>Parameters:</para>
+		<para>
+		<quote>name</quote> of a route block in the config file, like <quote>route[FROGJUMP]</quote>
+		</para>
+		<para>
+		This function can be used from any route. You can only check for
+		route[] blocks, not reply, event or other routes.
+		</para>
+		<example>
+		<title><function moreinfo="none">check_route_exists()</function> usage</title>
+		<programlisting format="linespecific">
+...
+if(check_route_exists("FROGJUMP") {
+	$var(jumping_frogs) = 1;
+};
+...
+</programlisting>
+		</example>
+	</section>
+	<section>
+		<title><function moreinfo="none">route_if_exists(route)</function></title>
+		<para>
+		Execute a routing block only if it is defined. If it's not defined, silently
+		move to the next action in the configuration script.
+		</para>
+		<para>Parameters:</para>
+		<para>
+		<quote>name</quote> of a route block in the config file, like <quote>route[FROGJUMP]</quote>
+		</para>
+		<para>
+		This function can be used from any route. You can only execute it for
+		route[] blocks, not reply, event or other routes.
+		</para>
+		<example>
+		<title><function moreinfo="none">route_if_exists()</function> usage</title>
+		<programlisting format="linespecific">
+...
+route_if_exists("PRESENCE_SANTA_CLAUS");
+...
 </programlisting>
 		</example>
 	</section>