Tidied up whitespace; added comments; removed comments from the header
authorscottmk <scottmk@dcc99617-32d9-48b4-a31d-7c20da2025e4>
Mon, 15 Mar 2010 01:54:50 +0000 (01:54 +0000)
committerscottmk <scottmk@dcc99617-32d9-48b4-a31d-7c20da2025e4>
Mon, 15 Mar 2010 01:54:50 +0000 (01:54 +0000)
so that they won't override the new doxygen-style comments in the
implementation file.

M    Open-ILS/include/openils/oils_event.h
M    Open-ILS/src/c-apps/oils_event.c

git-svn-id: svn://svn.open-ils.org/ILS/trunk@15843 dcc99617-32d9-48b4-a31d-7c20da2025e4

Open-ILS/include/openils/oils_event.h
Open-ILS/src/c-apps/oils_event.c

index ccfe4ab..111b791 100644 (file)
@@ -9,51 +9,37 @@
 extern "C" {
 #endif
 
-/* OILS Event structure */
+/**
+       @brief Represents an event; typically some kind of error condition.
+*/
 struct _oilsEventStruct {
-       char* event;                    /* the event name */
-       char* perm;                             /* the permission error name */
-       int permloc;                    /* the permission location id */
-       jsonObject* payload;    /* the payload */
-       jsonObject* json;               /* the event as a jsonObject */
-       char* file;
-       int line;
+       char* event;            /**< Event name. */
+       char* perm;             /**< Permission error name. */
+       int permloc;            /**< Permission location id. */
+       jsonObject* payload;    /**< Payload. */
+       jsonObject* json;       /**< The event as a jsonObject. */
+       char* file;             /**< Name of source file where event was created. */
+       int line;               /**< Line number in source file where event was created. */
 };
 typedef struct _oilsEventStruct oilsEvent;
 
-
-/** Creates a new event.  User is responsible for freeing event with oilsEventFree */
 oilsEvent* oilsNewEvent( const char* file, int line, const char* event );
 
-/** Creates a new event with payload.  
- * User is responsible for freeing event with oilsEventFree */
 oilsEvent* oilsNewEvent2( const char* file, int line, const char* event,
                const jsonObject* payload );
 
-/** Creates a new event with permission and permission location.  
- * User is responsible for freeing event with oilsEventFree */
 oilsEvent* oilsNewEvent3( const char* file, int line, const char* event,
                const char* perm, int permloc );
 
-/** Creates a new event with permission, permission location, and payload.  
- * User is responsible for freeing event with oilsEventFree */
 oilsEvent* oilsNewEvent4( const char* file, int line, const char* event,
                const char* perm, int permloc, const jsonObject* payload );
 
-/** Sets the permission info for the event */
 void oilsEventSetPermission( oilsEvent* event, const char* perm, int permloc );
 
-/* Sets the payload for the event 
- * This clones the payload, so the user is responsible
- * for handling the payload object's memory
- * */
 void oilsEventSetPayload( oilsEvent* event, const jsonObject* payload );
 
-/** Creates the JSON associated with an event.  The JSON should NOT be
- * freed by the user.  It will be freed by oilsEventFree */
 jsonObject* oilsEventToJSON( oilsEvent* event );
 
-/* Frees an event object */
 void oilsEventFree( oilsEvent* event );
 
 #ifdef __cplusplus
index 7b229ad..1fe547b 100644 (file)
@@ -8,32 +8,94 @@ static void _oilsEventParseEvents();
 // The following two osrfHashes are created when we
 // create the first osrfEvent, and are never freed.
 
+/**
+       @brief Lookup store mapping event names to event numbers.
+
+       - Key: textcode from the events config file.
+       - Data: numeric code (as a string) from the events config file.
+*/
 static osrfHash* _oilsEventEvents = NULL;
+
+/**
+       @brief Lookup store mapping event numbers to descriptive text.
+
+       - Key: numeric code (as a string) of the event.
+       - Data: another layer of lookup, as follows:
+               - Key: numeric code (as a string) of the event.
+               - Data: text message describing the event.
+*/
 static osrfHash* _oilsEventDescriptions = NULL;
 
+/**
+       @brief Allocate and initialize a new oilsEvent.
+       @param file The name of the source file where oilsNewEvent is called.
+       @param line The line number in the source code where oilsNewEvent is called.
+       @param event A name or label for the event.
+       @return Pointer to the newly allocated oilsEvent.
+
+       The first two parameters are normally passed as the OSRF_LOG_MARK macro.
+
+       The calling code is responsible for freeing the oilsEvent by calling oilsEventFree().
+*/
 oilsEvent* oilsNewEvent( const char* file, int line, const char* event ) {
        if(!event) return NULL;
+
        osrfLogInfo(OSRF_LOG_MARK, "Creating new event: %s", event);
-       if(!_oilsEventEvents) _oilsEventParseEvents();
-       oilsEvent* evt = safe_malloc(sizeof(oilsEvent));
+
+       if(!_oilsEventEvents)
+               _oilsEventParseEvents();
+
+       oilsEvent* evt = safe_malloc( sizeof(oilsEvent) );
        evt->event = strdup(event);
        evt->perm = NULL;
        evt->permloc = -1;
        evt->payload = NULL;
        evt->json = NULL;
-       if(file) evt->file = strdup(file);
-       else evt->file = NULL;
+
+       if(file)
+               evt->file = strdup(file);
+       else
+               evt->file = NULL;
+
        evt->line = line;
        return evt;
 }
 
+/**
+       @brief Allocate and initialize a new oilsEvent with a payload.
+       @param file The name of the source file where oilsNewEvent is called.
+       @param line The line number in the source code where oilsNewEvent is called.
+       @param event A name or label for the event.
+       @param payload The payload, of which a copy will be incorporated into the oilsEvent.
+       @return Pointer to the newly allocated oilsEvent.
+
+       The first two parameters are normally passed as the OSRF_LOG_MARK macro.
+
+       The calling code is responsible for freeing the oilsEvent by calling oilsEventFree().
+*/
 oilsEvent* oilsNewEvent2( const char* file, int line, const char* event,
                const jsonObject* payload ) {
        oilsEvent* evt = oilsNewEvent(file, line, event);
-       if(payload) evt->payload = jsonObjectClone(payload);
+
+       if(payload)
+               evt->payload = jsonObjectClone(payload);
+
        return evt;
 }
 
+/**
+       @brief Create a new oilsEvent with a permission and a permission location.
+       @param file The name of the source file where oilsNewEvent is called.
+       @param line The line number in the source code where oilsNewEvent is called.
+       @param event A name or label for the event.
+       @param perm The permission name.
+       @param permloc The permission location.
+       @return Pointer to the newly allocated oilsEvent.
+
+       The first two parameters are normally passed as the OSRF_LOG_MARK macro.
+
+       The calling code is responsible for freeing the oilsEvent by calling oilsEventFree().
+*/
 oilsEvent* oilsNewEvent3( const char* file, int line, const char* event,
                const char* perm, int permloc ) {
        oilsEvent* evt = oilsNewEvent(file, line, event);
@@ -44,58 +106,117 @@ oilsEvent* oilsNewEvent3( const char* file, int line, const char* event,
        return evt;
 }
 
+/**
+       @brief Create a new oilsEvent with a permission and a permission location.
+       @param file The name of the source file where oilsNewEvent is called.
+       @param line The line number in the source code where oilsNewEvent is called.
+       @param event A name or label for the event.
+       @param perm The permission name.
+       @param permloc The permission location.
+       @param payload Pointer to the payload.
+       @return Pointer to the newly allocated oilsEvent.
+
+       The first two parameters are normally passed as the OSRF_LOG_MARK macro.
+
+       The calling code is responsible for freeing the oilsEvent by calling oilsEventFree().
+*/
 oilsEvent* oilsNewEvent4( const char* file, int line, const char* event,
                const char* perm, int permloc, const jsonObject* payload ) {
        oilsEvent* evt = oilsNewEvent3( file, line, event, perm, permloc );
-       if(payload) evt->payload = jsonObjectClone(payload);
+
+       if(payload)
+               evt->payload = jsonObjectClone(payload);
+
        return evt;
 }
 
+/**
+       @brief Set the permission and permission location of an oilsEvent.
+       @param event Pointer the oilsEvent whose permission and permission location are to be set.
+       @param perm The permission name.
+       @param permloc The permission location.
+*/
 void oilsEventSetPermission( oilsEvent* event, const char* perm, int permloc ) {
        if(!(event && perm)) return;
-       if(event->perm) free(event->perm);
+
+       if(event->perm)
+               free(event->perm);
+
        event->perm = strdup(perm);
        event->permloc = permloc;
 }
 
+/**
+       @brief Install a payload in an oilsEvent.
+       @param event The oilsEvent in which the payload is to be installed.
+       @param payload The payload, a copy of which will be installed in the oilsEvent.
+
+       If @a payload is NULL, install a JSON_NULL as the payload.
+*/
 void oilsEventSetPayload( oilsEvent* event, const jsonObject* payload ) {
        if(!(event && payload)) return;
-       if(event->payload) jsonObjectFree(event->payload);
+
+       if(event->payload)
+               jsonObjectFree(event->payload);
+
        event->payload = jsonObjectClone(payload);
 }
 
-
+/**
+       @brief Free an OilsEvent.
+       @param event Pointer to the oilsEvent to be freed.
+*/
 void oilsEventFree( oilsEvent* event ) {
        if(!event) return;
        free(event->event);
        free(event->perm);
        free(event->file);
-       if(event->json) jsonObjectFree(event->json);
-    /* event->json will contain a pointer to event->payload */
-    else jsonObjectFree(event->payload); 
+
+       // If present, the jsonObject to which event->json will include a pointer to
+       // event->payload.  Hence we must avoid trying to free the payload twice.
+       if(event->json)
+               jsonObjectFree(event->json);
+       else
+               jsonObjectFree(event->payload);
+
        free(event);
 }
 
+/**
+       @brief Package the contents of an oilsEvent into a jsonObject.
+       @param event Pointer to the oilsEvent whose contents are to be packaged.
+       @return Pointer to the newly created jsonObject if successful, or NULL if not.
+
+       The jsonObject will include a textual description of the event, as loaded from the
+       events file.  Although the events file may include text in multiple languages,
+       oilsEventToJSON() uses only those marked as "en-US".
 
+       A pointer to the resulting jsonObject will be stored in the oilsEvent.  Hence the calling
+       code should @em not free the returned jsonObject directly.  It will be freed by
+       oilsEventFree().
+*/
 jsonObject* oilsEventToJSON( oilsEvent* event ) {
        if(!event) return NULL;
-       char* code = osrfHashGet( _oilsEventEvents, event->event );
 
+       char* code = osrfHashGet( _oilsEventEvents, event->event );
        if(!code) {
-               osrfLogError(OSRF_LOG_MARK,  "No such event name: %s", event->event );
+               osrfLogError(OSRF_LOG_MARK, "No such event name: %s", event->event );
                return NULL;
        }
 
-
+       // Search for the right language
        char* lang = "en-US"; /* assume this for now */
        char* desc = NULL;
        osrfHash* h = osrfHashGet(_oilsEventDescriptions, lang);
        if(h) {
+               // Within that language, search for the right message
                osrfLogDebug(OSRF_LOG_MARK, "Loaded event lang hash for %s",lang);
                desc = osrfHashGet(h, code);
                osrfLogDebug(OSRF_LOG_MARK, "Found event description %s", desc);
        }
-       if(!desc) desc = "";
+
+       if(!desc)
+               desc = "";  // Not found?  Message defaults to empty string.
 
        jsonObject* json = jsonNewObject(NULL);
        jsonObjectSetKey( json, "ilsevent", jsonNewNumberObject(atoi(code)) );
@@ -108,18 +229,32 @@ jsonObject* oilsEventToJSON( oilsEvent* event ) {
        snprintf(buf, sizeof(buf), "%s:%d", event->file, event->line);
        jsonObjectSetKey( json, "stacktrace", jsonNewObject(buf) );
 
-       if(event->perm) jsonObjectSetKey( json, "ilsperm", jsonNewObject(event->perm) );
-       if(event->permloc != -1) jsonObjectSetKey( json, "ilspermloc", jsonNewNumberObject(event->permloc) );
-       if(event->payload) jsonObjectSetKey( json, "payload", event->payload );
-       
-       if(event->json) jsonObjectFree(event->json);
+       if(event->perm)
+               jsonObjectSetKey( json, "ilsperm", jsonNewObject(event->perm) );
+
+       if(event->permloc != -1)
+               jsonObjectSetKey( json, "ilspermloc", jsonNewNumberObject(event->permloc) );
+
+       if(event->payload)
+               jsonObjectSetKey( json, "payload", event->payload );
+
+       if(event->json)
+               jsonObjectFree(event->json);
+
        event->json = json;
        return json;
 }
 
-/* Parses the events file */
+/**
+       @brief Parse and load the events file.
+
+       Get the name of the events file from previously loaded settings.  Open it and load
+       it into an xmlDoc.  Based on the contents of the xmlDoc, build two osrfHashes: one to
+       map event names to event numbers, and another to map event numbers to descriptive
+       text messages (actually one such hash for each supported language).
+*/
 static void _oilsEventParseEvents() {
-       
+
        char* xml = osrf_settings_host_value("/ils_events");
 
        if(!xml) {
@@ -152,9 +287,10 @@ static void _oilsEventParseEvents() {
                                        xmlNodePtr desc = child->children;
                                        while(desc) {
                                                if( !strcmp((char*) desc->name, "desc") ) {
-                                                       xmlChar* lang = xmlGetProp( desc, BAD_CAST "lang");     
+                                                       xmlChar* lang = xmlGetProp( desc, BAD_CAST "lang");
                                                        if(lang) {
-                                                               osrfLogInternal(OSRF_LOG_MARK, "Loaded event lang: %s", (char*) lang);
+                                                               osrfLogInternal( OSRF_LOG_MARK,
+                                                                       "Loaded event lang: %s", (char*) lang );
                                                                osrfHash* langHash = osrfHashGet(
                                                                        _oilsEventDescriptions, (char*) lang);
                                                                if(!langHash) {
@@ -162,8 +298,10 @@ static void _oilsEventParseEvents() {
                                                                        osrfHashSet(_oilsEventDescriptions, langHash, (char*) lang);
                                                                }
                                                                char* content;
-                                                               if( desc->children && (content = (char*) desc->children->content) ) {
-                                                                       osrfLogInternal(OSRF_LOG_MARK, "Loaded event desc: %s", content);
+                                                               if( desc->children
+                                                                       && (content = (char*) desc->children->content) ) {
+                                                                       osrfLogInternal( OSRF_LOG_MARK,
+                                                                               "Loaded event desc: %s", content);
                                                                        osrfHashSet( langHash, content, (char*) code );
                                                                }
                                                        }
@@ -176,7 +314,6 @@ static void _oilsEventParseEvents() {
                }
        }
 
-       if(!success) osrfLogError(OSRF_LOG_MARK,  " ! Unable to parse events file: %s", xml );
+       if(!success)
+               osrfLogError(OSRF_LOG_MARK, " ! Unable to parse events file: %s", xml );
 }
-
-