[sr-dev] git:master: cfg framework: documentation for cfg_read_var*

[Miklos Tirpak]

Module: sip-router
Branch: master
Commit: 249df0253d2ef8fa3948ce50a4a76ba8f256fd1e
URL:    http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=249df0253d2ef8fa3948ce50a4a76ba8f256fd1e

Author: Miklos Tirpak <miklos at iptel.org>
Committer: Miklos Tirpak <miklos at iptel.org>
Date:   Wed Jul  1 14:23:09 2009 +0200

cfg framework: documentation for cfg_read_var*

- How to read the variables of another module, core, or
the script is documented.
- cfg_read_var() fixed -- it did not allow reading the variables
that had a fixup function.

---

 cfg/cfg_select.c |    7 -------
 doc/cfg.txt      |   39 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 39 insertions(+), 7 deletions(-)

diff --git a/cfg/cfg_select.c b/cfg/cfg_select.c
index 45aeb94..4374aa6 100644
--- a/cfg/cfg_select.c
+++ b/cfg/cfg_select.c
@@ -274,13 +274,6 @@ int read_cfg_var_fixup(char *gname, char *vname, struct cfg_read_handle *read_ha
 		return 0;
 	}
 
-	if (var->def->on_change_cb) {
-		/* fixup function is defined -- safer to return an error
-		than an incorrect value */
-		LOG(L_ERR, "ERROR: read_cfg_var_fixup(): variable cannot be retrieved\n");
-		return -1;
-	}
-
 	read_handle->group = (void *)group;
 	read_handle->var = (void *)var;
 	return 1;
diff --git a/doc/cfg.txt b/doc/cfg.txt
index 19b0e53..93d2c77 100644
--- a/doc/cfg.txt
+++ b/doc/cfg.txt
@@ -166,6 +166,45 @@ cfg_get(foo, cfg_handle, s)
 cfg_get(foo, cfg_handle, p)
 
 
+It is also possible to access the variables of other modules or the core in two
+different ways:
+
+1) Include the header file of the other module/core that declares the cfg_group_*
+structure and the handle for it. Than use the handle of that module/core to access
+the variable:
+
+cfg_get(bar, cfg_handle_of_bar, j);
+
+2) Access the variables by their group and variable name:
+
+#include "../../cfg/cfg_select.h"
+
+struct cfg_read_handle var_bar_j;
+
+in the module init function:
+static int mod_init(void)
+{
+	if ((read_cfg_var_fixup("bar", "j", &var_bar_j)) < 0)
+		return -1;
+	/* Note that the variable may or may not exist at this point
+	 * depending on the module loading order. The fixup will still
+	 * be successful but the variable cannot be read if it has not been
+	 * declared yet. If the variable will not be declared at all
+	 * SER will fail to start
+	 */
+}
+
+int	j;
+if ((cfg_read_var_int(&var_bar_j, &j)) < 0) { error... }
+
+or similarly,
+str	s;
+if ((cfg_read_var_str(&var_bar_j, &s)) < 0) { error... }
+
+2) is a bit slower than 1) because the first solution returns the pointer directly
+to the variable, but 2) supports also the variables declared in the script that are
+not known at compile time.
+
 3. Using the framework in the core
 ===============================================================================