From d2780ce1270c734989012371e165283274ed31f4 Mon Sep 17 00:00:00 2001
From: scottmk <scottmk@dcc99617-32d9-48b4-a31d-7c20da2025e4>
Date: Mon, 15 Mar 2010 01:54:50 +0000
Subject: [PATCH] Tidied up whitespace; added comments; removed comments from
the header 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 | 34 ++----
Open-ILS/src/c-apps/oils_event.c | 197 ++++++++++++++++++++++++++++------
2 files changed, 177 insertions(+), 54 deletions(-)
diff --git a/Open-ILS/include/openils/oils_event.h b/Open-ILS/include/openils/oils_event.h
index ccfe4aba9f..111b791b67 100644
--- a/Open-ILS/include/openils/oils_event.h
+++ b/Open-ILS/include/openils/oils_event.h
@@ -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
diff --git a/Open-ILS/src/c-apps/oils_event.c b/Open-ILS/src/c-apps/oils_event.c
index 7b229adf5c..1fe547b258 100644
--- a/Open-ILS/src/c-apps/oils_event.c
+++ b/Open-ILS/src/c-apps/oils_event.c
@@ -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 );
}
-
-
--
2.11.0