[Opensrf-commits] r1771 - in trunk: include/opensrf src/libopensrf (scottmk)

[svn at svn.open-ils.org]

Author: scottmk
Date: 2009-09-08 16:46:23 -0400 (Tue, 08 Sep 2009)
New Revision: 1771

Modified:
   trunk/include/opensrf/osrf_settings.h
   trunk/src/libopensrf/osrf_settings.c
Log:
1. Moved the declaration of the osrf_host_config struct out of the header.
Nothing outside of osrf_settings.c needs access to any members of this
struct.

2. Made the osrf_settings_new_host_config function static; removed its
prototype from the header.

3. Made the "config" pointer static.

4. Rearranged osrf_settings_free_host_config a bit to protect against
attempts to free the cached config twice.

5. Finished adding doxygen-style markup comments.


Modified: trunk/include/opensrf/osrf_settings.h
===================================================================
--- trunk/include/opensrf/osrf_settings.h	2009-09-08 14:29:45 UTC (rev 1770)
+++ trunk/include/opensrf/osrf_settings.h	2009-09-08 20:46:23 UTC (rev 1771)
@@ -14,17 +14,22 @@
 
 #include <opensrf/osrf_json.h>
 
+/**
+	@file osrf_settings.h
+	@brief Facility for retrieving server configuration settings.
+
+	Look up server configuration settings from a settings server, cache them in the form of
+	a jsonObject, and retrieve them on request.
+
+	Not generally intended for client processes, unless they are also servers in their own right.
+*/
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-typedef struct { 
-	char* hostname; 
-	jsonObject* config; 
-} osrf_host_config;
+struct osrf_host_config_;
+typedef struct osrf_host_config_ osrf_host_config;
 
-
-osrf_host_config* osrf_settings_new_host_config(const char* hostname);
 void osrf_settings_free_host_config(osrf_host_config*);
 char* osrf_settings_host_value(const char* path, ...);
 jsonObject* osrf_settings_host_value_object(const char* format, ...);

Modified: trunk/src/libopensrf/osrf_settings.c
===================================================================
--- trunk/src/libopensrf/osrf_settings.c	2009-09-08 14:29:45 UTC (rev 1770)
+++ trunk/src/libopensrf/osrf_settings.c	2009-09-08 20:46:23 UTC (rev 1771)
@@ -1,7 +1,26 @@
+/**
+	@file osrf_settings.c
+	@brief Facility for retrieving server configuration settings.
+*/
 #include <opensrf/osrf_settings.h> 
 
-osrf_host_config* config = NULL;
+/**
+	@brief Stores a copy of server configuration settings as a jsonObject.
 
+	It also stores the host name of the settings server which supplied the configuration
+	settings.  In practice nothing uses the stored copy of the host name.
+*/
+struct osrf_host_config_ {
+	/** @brief The host name of the settings server */
+	char* hostname;
+	/** @brief The configuration settings as a jsonObject */
+jsonObject* config;
+};
+
+static osrf_host_config* osrf_settings_new_host_config(const char* hostname);
+
+static osrf_host_config* config = NULL;
+
 /**
 	@brief Fetch a specified string from an already-loaded configuration.
 	@param format A printf-style format string.  Subsequent parameters, if any, will be formatted
@@ -66,6 +85,22 @@
 }
 
 
+/**
+	@brief Look up the configuration settings and cache them for future reference.
+	@param hostname The host name for the settings server.
+	@return Zero if successful, or -1 if not.
+
+	The configuration settings come from a settings server.  This arrangement is intended for
+	use by servers, so that all server settings can be stored in a single location.  Typically
+	a client process (that is not also a server in its own right) will read its own
+	configuration file locally.
+
+	The settings are cached as a jsonObject for future lookups by the functions
+	osrf_settings_host_value() and osrf_settings_host_value_object().
+
+	The calling code is responsible for freeing the cached settings by calling
+	osrf_settings_free_host_config().
+ */
 int osrf_settings_retrieve(const char* hostname) {
 
 	if(!config) {
@@ -106,7 +141,12 @@
 	return 0;
 }
 
-osrf_host_config* osrf_settings_new_host_config(const char* hostname) {
+/**
+	@brief Allocate and initialize an osrf_host_config for a given host name.
+	@param hostname Pointer to a host name.
+	@return Pointer to a newly created osrf_host_config.
+*/
+static osrf_host_config* osrf_settings_new_host_config(const char* hostname) {
 	if(!hostname) return NULL;
 	osrf_host_config* c = safe_malloc(sizeof(osrf_host_config));
 	c->hostname = strdup(hostname);
@@ -114,10 +154,18 @@
 	return c;
 }
 
+/**
+	@brief Deallocate an osrf_host_config and its contents.
+	@param c A pointer to the osrf_host_config to be deallocated.
+*/
 void osrf_settings_free_host_config(osrf_host_config* c) {
-	if(!c) c = config;
-	if(!c) return;
-	free(c->hostname);
-	jsonObjectFree(c->config);	
-	free(c);
+	if( !c ) {
+		c = config;
+		config = NULL;
+	}
+	if( c ) {
+		free(c->hostname);
+		jsonObjectFree(c->config);
+		free(c);
+	}
 }