diff options
Diffstat (limited to 'common/elapi/elapi_event.h')
| -rw-r--r-- | common/elapi/elapi_event.h | 168 |
1 files changed, 168 insertions, 0 deletions
diff --git a/common/elapi/elapi_event.h b/common/elapi/elapi_event.h new file mode 100644 index 000000000..d1e0dd128 --- /dev/null +++ b/common/elapi/elapi_event.h @@ -0,0 +1,168 @@ +/* + ELAPI + + Header file for the ELAPI event interface. + + Copyright (C) Dmitri Pal <dpal@redhat.com> 2009 + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + You should have received a copy of the GNU General Public License + along with this program. If not, see <http://www.gnu.org/licenses/>. +*/ + +#ifndef ELAPI_EVENT_H +#define ELAPI_EVENT_H + +#include "collection.h" + +/* Possible predefined elements of the event */ +#define E_TIMESTAMP "stamp" /* string - the value is the format for strftime() + * default is standard format for current locale. */ +#define E_UTCTIME "time" /* int - UTC time as unix time in seconds since 1970 */ +#define E_PID "pid" /* int - Process ID of the current process */ +#define E_APPNAME "appnm" /* string - Name of the current application */ +#define E_HOSTNAME "host" /* string - Name of the current host */ +#define E_HOSTIP "ip" /* string - IP address */ +#define E_SEVERITY "sev" /* int - Same as "priority" in syslog() */ +#define E_HOSTALIAS "halias" /* string - List of alternative host names */ +#define E_HOSTIPS "iplist" /* string - List of alternative IP addresses */ + +/* There is a special optional attribute of the event named "message". + * It is a string that contains text specific to each event. + * This string can contain placeholders that will be automatically + * replaced by the values that correspond to other attributes in + * the message. For example message can be: + * "Connected to remote %(server)". + * The token %(server) will be replaced by value + * in the attribute "server" in the event. + */ +#define E_MESSAGE "message" + +/* Base argument in the template creation function is a bit mask. + * Each supported predefined element corresponds to its bit in + * the mask. + */ +#define E_HAVE_TIMESTAMP 0x00000001 +#define E_HAVE_UTCTIME 0x00000002 +#define E_HAVE_PID 0x00000004 +#define E_HAVE_APPNAME 0x00000010 +#define E_HAVE_HOSTNAME 0x00000020 +#define E_HAVE_HOSTIP 0x00000040 +#define E_HAVE_SEVERITY 0x00000100 +#define E_HAVE_HOSTALIAS 0x00000200 +#define E_HAVE_HOSTIPS 0x00000400 + +/* Convenient bitmasks */ +#define E_BASE_TIME ( E_HAVE_TIMESTAMP | E_HAVE_UTCTIME ) +#define E_BASE_HOST ( E_HAVE_HOSTIP | E_HAVE_HOSTNAME ) +#define E_BASE_APP ( E_HAVE_APPNAME | E_HAVE_PID ) +#define E_BASE_HOSTEXT ( E_HAVE_HOSTALIAS | E_HAVE_HOSTIPS ) +#define E_BASE_DEFV1 ( E_BASE_TIME | E_BASE_HOST | E_BASE_APP | E_HAVE_SEVERITY ) + +/* The default time stamp format */ +#define E_TIMESTAMP_FORMAT "%c" + +#define TIME_ARRAY_SIZE 100 + + +/* End of arg list special value */ +#define E_EOARG "<EOARG>" + + + +/***************************************************************************/ +/* TREAD SAFE ELAPI EVENT API */ +/***************************************************************************/ + +/* In the thread safe API the caller is responsible for + * carrying context information. It is usually allocated + * when a "create" function is called + * and should be deleted using "destroy" function. + */ + +/* Create an event template. + * One can create an event template + * and specify what fields should be + * populated in the event at its creation. + * Possible supported fields are listed above. + * Base parameter specifies the base collection of + * attributes. See above. The value of 0 will default + * to the current version of default combination + * which might change as the API evolves. + * The variable list can be used to initialize template. + * It can be initialized by providing key value pairs. + * ...base, key, value, key, value); + * If the key does not contain format specifier + * the value should be a NULL terminated string. + * See examples for the specific syntax. + * If key starts with "-" like "-foo" + * it means that attribute should be removed. + * In this case the value should not be provided + * and next argument should be next key. + * The attributes selected by base argument will + * be internally and automatically initialized + * if there is no key - value pair provided. + * The timestamps will we overwritten each time + * the event is created so initializing them + * does not make sense unless you use the base + * that does not include them. + * The list of key value pairs should be terminated by special + * argument E_EOARG. + */ +int elapi_create_event_template(struct collection_item **template, + unsigned base, ...); + +/* Function to destroy event template */ +void elapi_destroy_event_template(struct collection_item *template); + +/***************************************************************************/ +/* Creates a new event using template (must be provided) + * and adds additional fields using collection + * if provided and/or key value pairs if provided. + * Mode specifies how the collection should be + * copied into event. + * See example for details about format specification. + */ +int elapi_create_event(struct collection_item **event, + struct collection_item *template, + struct collection_item *collection, + int mode, ...); + +/* Add/Updates/Removes the event attributes based on the and provided key value pairs */ +int elapi_modify_event(struct collection_item *event, + struct collection_item *collection, + int mode, ...); + +/* Create a copy of the event */ +int elapi_copy_event(struct collection_item **new_event, + struct collection_item *source_event); + +/* Function to destroy event. */ +/* Keep in mind that as soon as event is logged + * it is automatically destroyed so the + * function should be used only in cases + * when you have an event + * that you use as a template for other events. + */ +void elapi_destroy_event(struct collection_item *event); + +/***************************************************************************/ +/* TREAD UNSAFE ELAPI EVENT API - for simple use cases */ +/***************************************************************************/ +/* Initializes default internal template */ +int elapi_set_default_template(unsigned base, ...); + +/* This function will use internal default template. + * Hides all complexity from the caller. + */ +int elapi_create_simple_event(struct collection_item **event, ...); + + +#endif |