lwes_event.h File Reference

Detailed Description

Functions for dealing with LWES events.

Go to the source code of this file.

Data Structures

struct  lwes_event_deserialize_tmp
 Storage for use when deserializing strings from events. More...
struct  lwes_event
 Structure representing an event. More...
struct  lwes_event_attribute
 Structure representing an attribute. More...
struct  lwes_event_enumeration
 Structure for enumerating over the values in the event. More...

Functions

lwes_event * lwes_event_create_no_name (struct lwes_event_type_db *db)
 Create the memory for an event with no name.
lwes_event * lwes_event_create (struct lwes_event_type_db *db, LWES_CONST_SHORT_STRING name)
 Create the memory for an event.
lwes_event * lwes_event_create_with_encoding (struct lwes_event_type_db *db, LWES_CONST_SHORT_STRING name, LWES_INT_16 encoding)
 Create the memory for an event with encoding.
int lwes_event_destroy (struct lwes_event *event)
 Cleanup the memory for an event.
int lwes_event_set_name (struct lwes_event *event, LWES_CONST_SHORT_STRING name)
 Set the name of the event.
int lwes_event_set_encoding (struct lwes_event *event, LWES_INT_16 encoding)
 Set the encoding of the event.
int lwes_event_set_U_INT_16 (struct lwes_event *event, LWES_CONST_SHORT_STRING name, LWES_U_INT_16 value)
 Add a LWES_U_INT_16 attribute to the event.
int lwes_event_set_INT_16 (struct lwes_event *event, LWES_CONST_SHORT_STRING name, LWES_INT_16 value)
 Add a LWES_INT_16 attribute to the event.
int lwes_event_set_U_INT_32 (struct lwes_event *event, LWES_CONST_SHORT_STRING name, LWES_U_INT_32 value)
 Add a LWES_U_INT_32 attribute to the event.
int lwes_event_set_INT_32 (struct lwes_event *event, LWES_CONST_SHORT_STRING name, LWES_INT_32 value)
 Add a LWES_INT_32 attribute to the event.
int lwes_event_set_U_INT_64 (struct lwes_event *event, LWES_CONST_SHORT_STRING name, LWES_U_INT_64 value)
 Add a LWES_U_INT_64 attribute to the event.
int lwes_event_set_U_INT_64_w_string (struct lwes_event *event, LWES_CONST_SHORT_STRING name, LWES_CONST_SHORT_STRING value)
 Add a LWES_U_INT_64 attribute to the event with a string value.
int lwes_event_set_INT_64 (struct lwes_event *event, LWES_CONST_SHORT_STRING name, LWES_INT_64 value)
 Add a LWES_INT_64 attribute to the event.
int lwes_event_set_INT_64_w_string (struct lwes_event *event, LWES_CONST_SHORT_STRING name, LWES_CONST_SHORT_STRING value)
 Add a LWES_INT_64 attribute to the event with a string value.
int lwes_event_set_STRING (struct lwes_event *event, LWES_CONST_SHORT_STRING name, LWES_CONST_LONG_STRING value)
 Add an LWES_LONG_STRING attribute to the event.
int lwes_event_set_IP_ADDR (struct lwes_event *event, LWES_CONST_SHORT_STRING name, LWES_IP_ADDR value)
 Add an LWES_IP_ADDR attribute to the event.
int lwes_event_set_IP_ADDR_w_string (struct lwes_event *event, LWES_CONST_SHORT_STRING name, LWES_CONST_SHORT_STRING value)
 Add a LWES_IP_ADDR attribute to the event with a string value.
int lwes_event_set_BOOLEAN (struct lwes_event *event, LWES_CONST_SHORT_STRING name, LWES_BOOLEAN value)
 Add an LWES_BOOLEAN attribute to the event.
int lwes_event_get_name (struct lwes_event *event, LWES_SHORT_STRING *name)
 Get the name of the event.
int lwes_event_get_number_of_attributes (struct lwes_event *event, LWES_U_INT_16 *number)
 Get the number of attributes in the event.
int lwes_event_get_encoding (struct lwes_event *event, LWES_INT_16 *encoding)
 Get the encoding of the event.
int lwes_event_get_U_INT_16 (struct lwes_event *event, LWES_CONST_SHORT_STRING name, LWES_U_INT_16 *value)
 Get an LWES_U_INT_16 attribute from the event.
int lwes_event_get_INT_16 (struct lwes_event *event, LWES_CONST_SHORT_STRING name, LWES_INT_16 *value)
 Get an LWES_INT_16 attribute from the event.
int lwes_event_get_U_INT_32 (struct lwes_event *event, LWES_CONST_SHORT_STRING name, LWES_U_INT_32 *value)
 Get an LWES_U_INT_32 attribute from the event.
int lwes_event_get_INT_32 (struct lwes_event *event, LWES_CONST_SHORT_STRING name, LWES_INT_32 *value)
 Get an LWES_INT_32 attribute from the event.
int lwes_event_get_U_INT_64 (struct lwes_event *event, LWES_CONST_SHORT_STRING name, LWES_U_INT_64 *value)
 Get an LWES_U_INT_64 attribute from the event.
int lwes_event_get_INT_64 (struct lwes_event *event, LWES_CONST_SHORT_STRING name, LWES_INT_64 *value)
 Get an LWES_INT_64 attribute from the event.
int lwes_event_get_STRING (struct lwes_event *event, LWES_CONST_SHORT_STRING name, LWES_LONG_STRING *value)
 Get an LWES_LONG_STRING attribute to the event.
int lwes_event_get_IP_ADDR (struct lwes_event *event, LWES_CONST_SHORT_STRING name, LWES_IP_ADDR *value)
 Get an LWES_IP_ADDR attribute from the event.
int lwes_event_get_BOOLEAN (struct lwes_event *event, LWES_CONST_SHORT_STRING name, LWES_BOOLEAN *value)
 Get an LWES_BOOLEAN attribute from the event.
int lwes_event_to_bytes (struct lwes_event *event, LWES_BYTE_P bytes, size_t num_bytes, size_t offset)
 Serialize an event.
int lwes_event_from_bytes (struct lwes_event *event, LWES_BYTE_P bytes, size_t num_bytes, size_t offset, struct lwes_event_deserialize_tmp *dtmp)
 Deserialize an event.
int lwes_event_keys (struct lwes_event *event, struct lwes_event_enumeration *enumeration)
 Start an enumeration over the keys of the event.
int lwes_event_enumeration_next_element (struct lwes_event_enumeration *enumeration, LWES_CONST_SHORT_STRING *key, LWES_TYPE *type)
 Get the next element from the event.

Function Documentation

struct lwes_event* lwes_event_create_no_name (  struct lwes_event_type_db *  db  ) 
 

Create the memory for an event with no name.

This is used when deserializing an event from a byte array

Parameters:
[in] db the event type db to use for this object, if NULL, disable type checking.
Returns:
the newly allocated event or NULL if an error occurred

struct lwes_event* lwes_event_create (  struct lwes_event_type_db *  db,
LWES_CONST_SHORT_STRING  name
) 
 

Create the memory for an event.

This allocate's space for name, so you don't have to dynamically allocate the memory for it.

Parameters:
[in] name the name of the event
[in] db the event type db to use for this object, if NULL, disable type checking.
Returns:
the newly allocated event or NULL if an error occurred

struct lwes_event* lwes_event_create_with_encoding (  struct lwes_event_type_db *  db,
LWES_CONST_SHORT_STRING  name,
LWES_INT_16  encoding
) 
 

Create the memory for an event with encoding.

This allocate's space for name, so you don't have to dynamically allocate the memory for it

Parameters:
[in] name the name of the event
[in] db the event type db to use for this object, if NULL, disable type checking.
[in] encoding the character encoding used for strings in this object
Returns:
the newly allocated event or NULL if an error occurred

int lwes_event_destroy (  struct lwes_event *  event  ) 
 

Cleanup the memory for an event.

Parameters:
[in] event the event to free
Returns:
0 on success, a negative number on failure

int lwes_event_set_name (  struct lwes_event *  event,
LWES_CONST_SHORT_STRING  name
) 
 

Set the name of the event.

Usually only used when lwes_event_create_no_name is used. This sets the name of the event, clears the memory of previous settings, allocates new memory as necessary.

Parameters:
[in] event the event to set the name of
[in] name the new name of the event
Returns:
0 on success, a negative number on failure

int lwes_event_set_encoding (  struct lwes_event *  event,
LWES_INT_16  encoding
) 
 

Set the encoding of the event.

Note the encoding is just advisory, it is up to the user of the library to insure the encoding of strings matches what is placed here

Parameters:
[in] event the event to set the encoding of
[in] encoding the new encoding
Returns:
0 on success, a negative number on failure

int lwes_event_set_U_INT_16 (  struct lwes_event *  event,
LWES_CONST_SHORT_STRING  name,
LWES_U_INT_16  value
) 
 

Add a LWES_U_INT_16 attribute to the event.

Parameters:
[in] event the event to add the attribute to
[in] name the name of the attribute
[in] value the value of the attribute
Returns:
the new number of attributes on succes, a negative number on failure.

int lwes_event_set_INT_16 (  struct lwes_event *  event,
LWES_CONST_SHORT_STRING  name,
LWES_INT_16  value
) 
 

Add a LWES_INT_16 attribute to the event.

Parameters:
[in] event the event to add the attribute to
[in] name the name of the attribute
[in] value the value of the attribute
Returns:
the new number of attributes on succes, a negative number on failure.

int lwes_event_set_U_INT_32 (  struct lwes_event *  event,
LWES_CONST_SHORT_STRING  name,
LWES_U_INT_32  value
) 
 

Add a LWES_U_INT_32 attribute to the event.

Parameters:
[in] event the event to add the attribute to
[in] name the name of the attribute
[in] value the value of the attribute
Returns:
the new number of attributes on succes, a negative number on failure.

int lwes_event_set_INT_32 (  struct lwes_event *  event,
LWES_CONST_SHORT_STRING  name,
LWES_INT_32  value
) 
 

Add a LWES_INT_32 attribute to the event.

Parameters:
[in] event the event to add the attribute to
[in] name the name of the attribute
[in] value the value of the attribute
Returns:
the new number of attributes on succes, a negative number on failure.

int lwes_event_set_U_INT_64 (  struct lwes_event *  event,
LWES_CONST_SHORT_STRING  name,
LWES_U_INT_64  value
) 
 

Add a LWES_U_INT_64 attribute to the event.

Parameters:
[in] event the event to add the attribute to
[in] name the name of the attribute
[in] value the value of the attribute
Returns:
the new number of attributes on succes, a negative number on failure.

int lwes_event_set_U_INT_64_w_string (  struct lwes_event *  event,
LWES_CONST_SHORT_STRING  name,
LWES_CONST_SHORT_STRING  value
) 
 

Add a LWES_U_INT_64 attribute to the event with a string value.

Internally converts the string to an LWES_U_INT_64

Parameters:
[in] event the event to add the attribute to
[in] name the name of the attribute
[in] value the string value of the attribute
Returns:
the new number of attributes on succes, a negative number on failure.

int lwes_event_set_INT_64 (  struct lwes_event *  event,
LWES_CONST_SHORT_STRING  name,
LWES_INT_64  value
) 
 

Add a LWES_INT_64 attribute to the event.

Parameters:
[in] event the event to add the attribute to
[in] name the name of the attribute
[in] value the value of the attribute
Returns:
the new number of attributes on succes, a negative number on failure.

int lwes_event_set_INT_64_w_string (  struct lwes_event *  event,
LWES_CONST_SHORT_STRING  name,
LWES_CONST_SHORT_STRING  value
) 
 

Add a LWES_INT_64 attribute to the event with a string value.

Internally converts the string to an LWES_INT_64

Parameters:
[in] event the event to add the attribute to
[in] name the name of the attribute
[in] value the string value of the attribute
Returns:
the new number of attributes on succes, a negative number on failure.

int lwes_event_set_STRING (  struct lwes_event *  event,
LWES_CONST_SHORT_STRING  name,
LWES_CONST_LONG_STRING  value
) 
 

Add an LWES_LONG_STRING attribute to the event.

Parameters:
[in] event the event to add the attribute to
[in] name the name of the attribute
[in] value the value of the attribute
Returns:
the new number of attributes on succes, a negative number on failure.

int lwes_event_set_IP_ADDR (  struct lwes_event *  event,
LWES_CONST_SHORT_STRING  name,
LWES_IP_ADDR  value
) 
 

Add an LWES_IP_ADDR attribute to the event.

Parameters:
[in] event the event to add the attribute to
[in] name the name of the attribute
[in] value the value of the attribute
Returns:
the new number of attributes on succes, a negative number on failure.

int lwes_event_set_IP_ADDR_w_string (  struct lwes_event *  event,
LWES_CONST_SHORT_STRING  name,
LWES_CONST_SHORT_STRING  value
) 
 

Add a LWES_IP_ADDR attribute to the event with a string value.

The string should be of the form xxx.xxx.xxx.xxx, in other words dotted quad notation.

Internally converts the string from a dotted quad string to an LWES_IP_ADDR.

Parameters:
[in] event the event to add the attribute to
[in] name the name of the attribute
[in] value the string value of the attribute
Returns:
the new number of attributes on succes, a negative number on failure.

int lwes_event_set_BOOLEAN (  struct lwes_event *  event,
LWES_CONST_SHORT_STRING  name,
LWES_BOOLEAN  value
) 
 

Add an LWES_BOOLEAN attribute to the event.

Parameters:
[in] event the event to add the attribute to
[in] name the name of the attribute
[in] value the value of the attribute
Returns:
the new number of attributes on succes, a negative number on failure.

int lwes_event_get_name (  struct lwes_event *  event,
LWES_SHORT_STRING *  name
) 
 

Get the name of the event.

Parameters:
[in] event the event to get the name of
[in] name the name of the event, this should be treated as const
Returns:
0 on success, a negative number on failure

int lwes_event_get_number_of_attributes (  struct lwes_event *  event,
LWES_U_INT_16 *  number
) 
 

Get the number of attributes in the event.

Parameters:
[in] event the event to get the number of attributes from
[out] number the number of attributes
Returns:
0 on success, a negative number on failure

int lwes_event_get_encoding (  struct lwes_event *  event,
LWES_INT_16 *  encoding
) 
 

Get the encoding of the event.

Note the encoding is just advisory, it is up to the user of the library to insure the encoding of strings matches what is placed here

Parameters:
[in] event the event to get the encoding from
[out] encoding the encoding of the event
Returns:
0 on success, a negative number on failure

int lwes_event_get_U_INT_16 (  struct lwes_event *  event,
LWES_CONST_SHORT_STRING  name,
LWES_U_INT_16 *  value
) 
 

Get an LWES_U_INT_16 attribute from the event.

Parameters:
[in] event the event to get the attribute from
[in] name the name of the attribute
[out] value the value of the attribute
Returns:
0 on success, a negative number on failure

int lwes_event_get_INT_16 (  struct lwes_event *  event,
LWES_CONST_SHORT_STRING  name,
LWES_INT_16 *  value
) 
 

Get an LWES_INT_16 attribute from the event.

Parameters:
[in] event the event to get the attribute from
[in] name the name of the attribute
[out] value the value of the attribute
Returns:
0 on success, a negative number on failure

int lwes_event_get_U_INT_32 (  struct lwes_event *  event,
LWES_CONST_SHORT_STRING  name,
LWES_U_INT_32 *  value
) 
 

Get an LWES_U_INT_32 attribute from the event.

Parameters:
[in] event the event to get the attribute from
[in] name the name of the attribute
[out] value the value of the attribute
Returns:
0 on success, a negative number on failure

int lwes_event_get_INT_32 (  struct lwes_event *  event,
LWES_CONST_SHORT_STRING  name,
LWES_INT_32 *  value
) 
 

Get an LWES_INT_32 attribute from the event.

Parameters:
[in] event the event to get the attribute from
[in] name the name of the attribute
[out] value the value of the attribute
Returns:
0 on success, a negative number on failure

int lwes_event_get_U_INT_64 (  struct lwes_event *  event,
LWES_CONST_SHORT_STRING  name,
LWES_U_INT_64 *  value
) 
 

Get an LWES_U_INT_64 attribute from the event.

Parameters:
[in] event the event to get the attribute from
[in] name the name of the attribute
[out] value the value of the attribute
Returns:
0 on success, a negative number on failure

int lwes_event_get_INT_64 (  struct lwes_event *  event,
LWES_CONST_SHORT_STRING  name,
LWES_INT_64 *  value
) 
 

Get an LWES_INT_64 attribute from the event.

Parameters:
[in] event the event to get the attribute from
[in] name the name of the attribute
[out] value the value of the attribute
Returns:
0 on success, a negative number on failure

int lwes_event_get_STRING (  struct lwes_event *  event,
LWES_CONST_SHORT_STRING  name,
LWES_LONG_STRING *  value
) 
 

Get an LWES_LONG_STRING attribute to the event.

Parameters:
[in] event the event to add the attribute to
[in] name the name of the attribute
[in] value the value of the attribute, this should be treated as const
Returns:
0 on success, a negative number on failure

int lwes_event_get_IP_ADDR (  struct lwes_event *  event,
LWES_CONST_SHORT_STRING  name,
LWES_IP_ADDR *  value
) 
 

Get an LWES_IP_ADDR attribute from the event.

Parameters:
[in] event the event to add the attribute to
[in] name the name of the attribute
[in] value the value of the attribute
Returns:
0 on success, a negative number on failure

int lwes_event_get_BOOLEAN (  struct lwes_event *  event,
LWES_CONST_SHORT_STRING  name,
LWES_BOOLEAN *  value
) 
 

Get an LWES_BOOLEAN attribute from the event.

Parameters:
[in] event the event to get the attribute from
[in] name the name of the attribute
[out] value the value of the attribute
Returns:
0 on success, a negative number on failure

int lwes_event_to_bytes (  struct lwes_event *  event,
LWES_BYTE_P  bytes,
size_t  num_bytes,
size_t  offset
) 
 

Serialize an event.

Serialization format is

    1 byte event name length ( 1 < b <= 255 )
    b bytes
    2 bytes num_attributes ( 0 < n < 65535, 65535 is a theoretical limit )
    foreach attribute
      1 byte attribute name length ( 1 < a <= 255 )
      a bytes of attribute name
      1 byte type id
      n bytes data

   We want to determine the maximum possible number of attributes
   ( the real upper bound on n above ).

   So we need to minimize all the fields,

   Event name     = 1 byte of length + 1 byte of data = 2 bytes
   Num Attributes = 2 bytes

   So the minimum is 4 bytes, that leaves 65531 to play with

   For attributes,

    minimum attribute length =
        (minimum attr name length                     = 1 byte)
      + (minimum attr name value, given minimum length= 1 byte)
      + (type id length                               = 1 byte)
      + (minimum size of attribute);

    Where

    minimum size boolean attribute = 1 byte
    minimum size uint16  attribute = 2 bytes
    minimum size int16   attribute = 2 bytes
    minimum size uint32  attribute = 4 bytes
    minimum size int32   attribute = 4 bytes
    minimum size uint64  attribute = 8 bytes
    minimum size int64   attribute = 8 bytes
    minimum size ipaddr  attribute = 4 bytes
    minimum size string  attribute = 2 bytes length + 1 byte data = 3 bytes

    so

    minimum boolean attribute =  4 byte
    minimum uint16  attribute =  5 bytes
    minimum int16   attribute =  5 bytes
    minimum uint32  attribute =  7 bytes
    minimum int32   attribute =  7 bytes
    minimum uint64  attribute = 11 bytes
    minimum int64   attribute = 11 bytes
    minimum ipaddr  attribute =  7 bytes
    minimum string  attribute =  6 bytes

    If attribute names are allowed to be duplicated for a type, then the
    maximum number of attributes is

      floor ( (65535 - 4) / 4) = 16382

    However, attribute names are not allowed to be duplicated for any
    one type, so that puts a cap of 254, 1 non-zero byte attribute
    names ( 1 -> 255 ) for a single type, this means the actual number
    of attributes is actually less.

    To maximally pack attributes we would start with the smallest
    in terms of number of bytes, then work our way upward calculating
    the number of attributes of a certain attribute name length of
    the smallest current type, so to start the chain

    4 bytes overhead                  =    4

    1 byte attribute booleans 254*4   = 1016

    2 byte attribute booleans 254*5   = 1270
    1 byte attribute uint16   254*5   = 1270
    1 byte attribute int16    254*5   = 1270

    1 byte attribute string   254*6   = 1524
    3 byte attribute booleans 254*6   = 1524
    2 byte attribute uint16   254*6   = 1524
    2 byte attribute int16    254*6   = 1524

    1 byte attribute uint32   254*7   = 1778
    1 byte attribute int32    254*7   = 1778
    2 byte attribute string   254*7   = 1778
    4 byte attribute booleans 254*7   = 1778
    3 byte attribute uint16   254*7   = 1778
    3 byte attribute int16    254*7   = 1778
    1 byte attribute ipaddr   254*7   = 1778

    2 byte attribute uint32   254*8   = 2032
    2 byte attribute int32    254*8   = 2032
    3 byte attribute string   254*8   = 2032
    5 byte attribute booleans 254*8   = 2032
    4 byte attribute uint16   254*8   = 2032
    4 byte attribute int16    254*8   = 2032
    2 byte attribute ipaddr   254*8   = 2032

    3 byte attribute uint32   254*9   = 2286
    3 byte attribute int32    254*9   = 2286
    4 byte attribute string   254*9   = 2286
    6 byte attribute booleans 254*9   = 2286
    5 byte attribute uint16   254*9   = 2286
    5 byte attribute int16    254*9   = 2286
    3 byte attribute ipaddr   254*9   = 2286

    4 byte attribute uint32   254*10  = 2540
    4 byte attribute int32    254*10  = 2540
    5 byte attribute string   254*10  = 2540
    7 byte attribute booleans 254*10  = 2540

    6 byte attribute uint16   177*10  = 1770

    7 bytes left over                 =    7

    total attrs = 33 * 254 + 177 = 8559

Parameters:
[in] event the event to serialize
[in] bytes the byte array to serialize into
[in] num_bytes the size of the byte array
[in] offset the offset into the array to start serializing at
Returns:
The number of bytes written to the array on success, a negative number on failure

int lwes_event_from_bytes (  struct lwes_event *  event,
LWES_BYTE_P  bytes,
size_t  num_bytes,
size_t  offset,
struct lwes_event_deserialize_tmp *  dtmp
) 
 

Deserialize an event.

Parameters:
[in] event the event to deserialize into
[in] bytes the byte array to serialize into
[in] num_bytes the size of the byte array
[in] offset the offset into the array to start serializing at
[in] dtmp some temporary space to deserialize strings into
Returns:
The number of bytes read from the array on success, a negative number on failure

int lwes_event_keys (  struct lwes_event *  event,
struct lwes_event_enumeration *  enumeration
) 
 

Start an enumeration over the keys of the event.

The pattern for enumerating is as follows

struct lwes_event_enumeration e;

if (lwes_event_keys (event, &e)) { LWES_CONST_SHORT_STRING key; LWES_TYPE type; while (lwes_event_enumeration_next_element (&e, &key, &type)) { switch (type) { case LWES_TYPE_U_INT_16: { LWES_U_INT_16 value; lwes_event_get_U_INT_16 (event, key, &value); } break; // ... cases for rest of types } } }

Parameters:
[in] event the event to enumerate over
[in] enumeration keeps track of the enumeration
Returns:
1 if it's possible to enumerate over this event, 0 if it is not.

int lwes_event_enumeration_next_element (  struct lwes_event_enumeration *  enumeration,
LWES_CONST_SHORT_STRING *  key,
LWES_TYPE *  type
) 
 

Get the next element from the event.

Parameters:
[in] enumeration keeps track of the enumeration
[out] key the key for the next element of the event
[out] type the type of the next element of the event
Returns:
1 if it's possible to enumerate over this event, 0 if it is not.

Generated on Thu Aug 21 07:18:55 2008 for lwes by  doxygen 1.4.6