From f4307af760844f0b8e45f30689df36243c85b883 Mon Sep 17 00:00:00 2001
From: scottmk <scottmk@9efc2488-bf62-4759-914b-345cdb29e865>
Date: Tue, 8 Sep 2009 20:46:23 +0000
Subject: [PATCH] 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.


git-svn-id: svn://svn.open-ils.org/OpenSRF/trunk@1771 9efc2488-bf62-4759-914b-345cdb29e865
---
 include/opensrf/osrf_settings.h | 17 +++++----
 src/libopensrf/osrf_settings.c  | 62 +++++++++++++++++++++++++++++----
 2 files changed, 66 insertions(+), 13 deletions(-)

diff --git a/include/opensrf/osrf_settings.h b/include/opensrf/osrf_settings.h
index 3d27870..fe4d399 100644
--- a/include/opensrf/osrf_settings.h
+++ b/include/opensrf/osrf_settings.h
@@ -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, ...);
diff --git a/src/libopensrf/osrf_settings.c b/src/libopensrf/osrf_settings.c
index 97c4fae..122f992 100644
--- a/src/libopensrf/osrf_settings.c
+++ b/src/libopensrf/osrf_settings.c
@@ -1,6 +1,25 @@
+/**
+	@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.
@@ -66,6 +85,22 @@ jsonObject* osrf_settings_host_value_object(const char* format, ...) {
 }
 
 
+/**
+	@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 @@ int osrf_settings_retrieve(const char* hostname) {
 	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 @@ osrf_host_config* osrf_settings_new_host_config(const char* hostname) {
 	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);
+	}
 }
-- 
2.43.2