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

diff --git a/include/opensrf/osrf_settings.h b/include/opensrf/osrf_settings.h
index 3d27870..fe4d399 100644 (file)
--- 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 (file)
--- 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);
+       }
 }