src/lwes_event.h

   1 /*======================================================================*
   2  * Copyright (C) 2008 Light Weight Event System                         *
   3  * All rights reserved.                                                 *
   4  *                                                                      *
   5  * This program is free software; you can redistribute it and/or modify *
   6  * it under the terms of the GNU General Public License as published by *
   7  * the Free Software Foundation; either version 2 of the License, or    *
   8  * (at your option) any later version.                                  *
   9  *                                                                      *
  10  * This program is distributed in the hope that it will be useful,      *
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of       *
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the        *
  13  * GNU General Public License for more details.                         *
  14  *                                                                      *
  15  * You should have received a copy of the GNU General Public License    *
  16  * along with this program; if not, write to the Free Software          *
  17  * Foundation, Inc., 51 Franklin Street, Fifth Floor,                   *
  18  * Boston, MA 02110-1301 USA.                                           *
  19  *======================================================================*/
  20 #ifndef __LWES_EVENT_FUNCTIONS_H
  21 #define __LWES_EVENT_FUNCTIONS_H
  22
  23 #include "lwes_types.h"
  24 #include "lwes_hash.h"
  25 #include "lwes_event_type_db.h"
  26
  27 #include <stdio.h>
  28
  29 #define LWES_ENCODING "enc"
  30
  31 #ifdef __cplusplus
  32 extern "C" {
  33 #endif
  34
  35 /*! \file lwes_event.h
  36  *  \brief Functions for dealing with LWES events
  37  */
  38
  39 /*! \struct lwes_event_deserialize_tmp lwes_event.h
  40  *  \brief Storage for use when deserializing strings from events
  41  */
  42 struct lwes_event_deserialize_tmp
  43 {
  44   /*! a LWES_SHORT_STRING of max size for use when deserializing short
  45    *  strings */
  46   LWES_CHAR     tmp_string[SHORT_STRING_MAX+1];
  47   /*! a LWES_LONG_STRING of max size for use when deserializing long
  48    *  strings */
  49   LWES_CHAR     tmp_string_long[LONG_STRING_MAX+1];
  50 };
  51
  52 /*! \struct lwes_event lwes_event.h
  53  *  \brief Structure representing an event
  54  */
  55 struct lwes_event
  56 {
  57   /*! Name of the event */
  58   LWES_SHORT_STRING            eventName;
  59   /*! Number of attributes that have been set in the event */
  60   LWES_U_INT_16                number_of_attributes;
  61   /*! DB used for validating this event */
  62   struct lwes_event_type_db *  type_db;
  63   /*! The attributes which have been set in the event.  This is a hash
  64    *   keyed by attribute name with a value of struct lwes_event_attribute
  65    */
  66   struct lwes_hash *           attributes;
  67 };
  68
  69 /*! \struct lwes_event_attribute lwes_event.h
  70  *  \brief Structure representing an attribute
  71  */
  72 struct lwes_event_attribute
  73 {
  74   /*! The type of the attribute */
  75   LWES_BYTE         type;
  76   /*! The value of the attribute */
  77   void             *value;
  78 };
  79
  80 /*! \struct lwes_event_enumeration lwes_event.h
  81  *  \brief Structure for enumerating over the values in the event
  82  */
  83 struct lwes_event_enumeration
  84 {
  85   /*! enumeration for the underlying hash */
  86   struct lwes_hash_enumeration hash_enum;
  87 };
  88
  89 /*! \brief Create the memory for an event with no name
  90  *
  91  *  This is used when deserializing an event from a byte array
  92  *
  93  * \param[in] db the event type db to use for this object, if NULL, disable type
  94  *               checking.
  95  *
  96  * \return the newly allocated event or NULL if an error occurred
  97  */
  98 struct lwes_event *
  99 lwes_event_create_no_name
 100   (struct lwes_event_type_db *db);
 101
 102 /*! \brief Create the memory for an event
 103  *
 104  * This allocate's space for name, so you don't have to dynamically
 105  * allocate the memory for it.
 106  *
 107  * \param[in] name the name of the event
 108  * \param[in] db the event type db to use for this object, if NULL, disable type
 109  *            checking.
 110  *
 111  * \return the newly allocated event or NULL if an error occurred
 112  */
 113 struct lwes_event *
 114 lwes_event_create
 115   (struct lwes_event_type_db *db,
 116    LWES_CONST_SHORT_STRING name);
 117
 118 /*! \brief Create the memory for an event with encoding
 119  *
 120  * This allocate's space for name, so you don't have to dynamically
 121  * allocate the memory for it
 122  *
 123  * \param[in] name the name of the event
 124  * \param[in] db the event type db to use for this object, if NULL, disable type
 125  *            checking.
 126  * \param[in] encoding the character encoding used for strings in this object
 127  *
 128  * \return the newly allocated event or NULL if an error occurred
 129  */
 130 struct lwes_event *
 131 lwes_event_create_with_encoding
 132   (struct lwes_event_type_db *db,
 133    LWES_CONST_SHORT_STRING name,
 134    LWES_INT_16 encoding);
 135
 136 /*! \brief Cleanup the memory for an event
 137  *
 138  * \param[in] event the event to free
 139  *
 140  * \return 0 on success, a negative number on failure
 141  */
 142 int
 143 lwes_event_destroy
 144   (struct lwes_event *event);
 145
 146 /*! \brief Set the name of the event
 147  *
 148  *  Usually only used when lwes_event_create_no_name is used.
 149  *  This sets the name of the event, clears the memory of previous
 150  *  settings, allocates new memory as necessary.
 151  *
 152  *  \param[in] event the event to set the name of
 153  *  \param[in] name the new name of the event
 154  *
 155  *  \return 0 on success, a negative number on failure
 156  */
 157 int
 158 lwes_event_set_name
 159   (struct lwes_event *event,
 160    LWES_CONST_SHORT_STRING name);
 161
 162 /*! \brief Set the encoding of the event
 163  *
 164  *  Note the encoding is just advisory, it is up to the user of the library
 165  *  to insure the encoding of strings matches what is placed here
 166  *
 167  *  \param[in] event the event to set the encoding of
 168  *  \param[in] encoding the new encoding
 169  *
 170  *  \return 0 on success, a negative number on failure
 171  */
 172 int
 173 lwes_event_set_encoding
 174   (struct lwes_event *event,
 175    LWES_INT_16 encoding);
 176
 177 /*! \brief Add a LWES_U_INT_16 attribute to the event
 178  *
 179  *  \param[in] event the event to add the attribute to
 180  *  \param[in] name the name of the attribute
 181  *  \param[in] value the value of the attribute
 182  *
 183  *  \return the new number of attributes on succes, a negative number on
 184  *          failure.
 185  */
 186 int
 187 lwes_event_set_U_INT_16
 188   (struct lwes_event *event,
 189    LWES_CONST_SHORT_STRING name,
 190    LWES_U_INT_16 value);
 191
 192 /*! \brief Add a LWES_INT_16 attribute to the event
 193  *
 194  *  \param[in] event the event to add the attribute to
 195  *  \param[in] name the name of the attribute
 196  *  \param[in] value the value of the attribute
 197  *
 198  *  \return the new number of attributes on succes, a negative number on
 199  *          failure.
 200  */
 201 int
 202 lwes_event_set_INT_16
 203   (struct lwes_event *event,
 204    LWES_CONST_SHORT_STRING name,
 205    LWES_INT_16   value);
 206
 207 /*! \brief Add a LWES_U_INT_32 attribute to the event
 208  *
 209  *  \param[in] event the event to add the attribute to
 210  *  \param[in] name the name of the attribute
 211  *  \param[in] value the value of the attribute
 212  *
 213  *  \return the new number of attributes on succes, a negative number on
 214  *          failure.
 215  */
 216 int
 217 lwes_event_set_U_INT_32
 218   (struct lwes_event *event,
 219    LWES_CONST_SHORT_STRING name,
 220    LWES_U_INT_32 value);
 221
 222 /*! \brief Add a LWES_INT_32 attribute to the event
 223  *
 224  *  \param[in] event the event to add the attribute to
 225  *  \param[in] name the name of the attribute
 226  *  \param[in] value the value of the attribute
 227  *
 228  *  \return the new number of attributes on succes, a negative number on
 229  *          failure.
 230  */
 231 int
 232 lwes_event_set_INT_32
 233   (struct lwes_event *event,
 234    LWES_CONST_SHORT_STRING name,
 235    LWES_INT_32   value);
 236
 237 /*! \brief Add a LWES_U_INT_64 attribute to the event
 238  *
 239  *  \param[in] event the event to add the attribute to
 240  *  \param[in] name the name of the attribute
 241  *  \param[in] value the value of the attribute
 242  *
 243  *  \return the new number of attributes on succes, a negative number on
 244  *          failure.
 245  */
 246 int
 247 lwes_event_set_U_INT_64
 248   (struct lwes_event *event,
 249    LWES_CONST_SHORT_STRING name,
 250    LWES_U_INT_64 value);
 251
 252 /*! \brief Add a LWES_U_INT_64 attribute to the event with a string value
 253  *
 254  *  Internally converts the string to an LWES_U_INT_64
 255  *
 256  *  \param[in] event the event to add the attribute to
 257  *  \param[in] name the name of the attribute
 258  *  \param[in] value the string value of the attribute
 259  *
 260  *  \return the new number of attributes on succes, a negative number on
 261  *          failure.
 262  */
 263 int
 264 lwes_event_set_U_INT_64_w_string
 265   (struct lwes_event *event,
 266    LWES_CONST_SHORT_STRING name,
 267    LWES_CONST_SHORT_STRING value);
 268
 269 /*! \brief Add a LWES_INT_64 attribute to the event
 270  *
 271  *  \param[in] event the event to add the attribute to
 272  *  \param[in] name the name of the attribute
 273  *  \param[in] value the value of the attribute
 274  *
 275  *  \return the new number of attributes on succes, a negative number on
 276  *          failure.
 277  */
 278 int
 279 lwes_event_set_INT_64
 280   (struct lwes_event *event,
 281    LWES_CONST_SHORT_STRING name,
 282    LWES_INT_64   value);
 283
 284 /*! \brief Add a LWES_INT_64 attribute to the event with a string value
 285  *
 286  *  Internally converts the string to an LWES_INT_64
 287  *
 288  *  \param[in] event the event to add the attribute to
 289  *  \param[in] name the name of the attribute
 290  *  \param[in] value the string value of the attribute
 291  *
 292  *  \return the new number of attributes on succes, a negative number on
 293  *          failure.
 294  */
 295 int
 296 lwes_event_set_INT_64_w_string
 297   (struct lwes_event *event,
 298    LWES_CONST_SHORT_STRING name,
 299    LWES_CONST_SHORT_STRING value);
 300
 301 /*! \brief Add an LWES_LONG_STRING attribute to the event
 302  *
 303  *  \param[in] event the event to add the attribute to
 304  *  \param[in] name the name of the attribute
 305  *  \param[in] value the value of the attribute
 306  *
 307  *  \return the new number of attributes on succes, a negative number on
 308  *          failure.
 309  */
 310 int
 311 lwes_event_set_STRING
 312   (struct lwes_event *event,
 313    LWES_CONST_SHORT_STRING name,
 314    LWES_CONST_LONG_STRING  value);
 315
 316 /*! \brief Add an LWES_IP_ADDR attribute to the event
 317  *
 318  *  \param[in] event the event to add the attribute to
 319  *  \param[in] name the name of the attribute
 320  *  \param[in] value the value of the attribute
 321  *
 322  *  \return the new number of attributes on succes, a negative number on
 323  *          failure.
 324  */
 325 int
 326 lwes_event_set_IP_ADDR
 327   (struct lwes_event *event,
 328    LWES_CONST_SHORT_STRING name,
 329    LWES_IP_ADDR      value);
 330
 331 /*! \brief Add a LWES_IP_ADDR attribute to the event with a string value
 332  *
 333  *  The string should be of the form xxx.xxx.xxx.xxx, in other words dotted
 334  *  quad notation.
 335  *
 336  *  Internally converts the string from a dotted quad string
 337  *  to an LWES_IP_ADDR.
 338  *
 339  *  \param[in] event the event to add the attribute to
 340  *  \param[in] name the name of the attribute
 341  *  \param[in] value the string value of the attribute
 342  *
 343  *  \return the new number of attributes on succes, a negative number on
 344  *          failure.
 345  */
 346 int
 347 lwes_event_set_IP_ADDR_w_string
 348   (struct lwes_event *event,
 349    LWES_CONST_SHORT_STRING name,
 350    LWES_CONST_SHORT_STRING value);
 351
 352 /*! \brief Add an LWES_BOOLEAN attribute to the event
 353  *
 354  *  \param[in] event the event to add the attribute to
 355  *  \param[in] name the name of the attribute
 356  *  \param[in] value the value of the attribute
 357  *
 358  *  \return the new number of attributes on succes, a negative number on
 359  *          failure.
 360  */
 361 int
 362 lwes_event_set_BOOLEAN
 363   (struct lwes_event *event,
 364    LWES_CONST_SHORT_STRING name,
 365    LWES_BOOLEAN      value);
 366
 367 /*! \brief Get the name of the event
 368  *
 369  *  \param[in] event the event to get the name of
 370  *  \param[in] name the name of the event, this should be treated as const
 371  *
 372  *  \return 0 on success, a negative number on failure
 373  */
 374 int
 375 lwes_event_get_name
 376   (struct lwes_event *event,
 377    LWES_SHORT_STRING *name);
 378
 379 /*! \brief Get the number of attributes in the event
 380  *
 381  *  \param[in] event the event to get the number of attributes from
 382  *  \param[out] number the number of attributes
 383  *
 384  *  \return 0 on success, a negative number on failure
 385  */
 386 int
 387 lwes_event_get_number_of_attributes
 388   (struct lwes_event *event,
 389    LWES_U_INT_16 *number);
 390
 391 /*! \brief Get the encoding of the event
 392  *
 393  *  Note the encoding is just advisory, it is up to the user of the library
 394  *  to insure the encoding of strings matches what is placed here
 395  *
 396  *  \param[in] event the event to get the encoding from
 397  *  \param[out] encoding the encoding of the event
 398  *
 399  *  \return 0 on success, a negative number on failure
 400  */
 401 int
 402 lwes_event_get_encoding
 403   (struct lwes_event *event,
 404    LWES_INT_16       *encoding);
 405
 406 /*! \brief Get an LWES_U_INT_16 attribute from the event
 407  *
 408  *  \param[in] event the event to get the attribute from
 409  *  \param[in] name the name of the attribute
 410  *  \param[out] value the value of the attribute
 411  *
 412  *  \return 0 on success, a negative number on failure
 413  */
 414 int
 415 lwes_event_get_U_INT_16
 416   (struct lwes_event *event,
 417    LWES_CONST_SHORT_STRING  name,
 418    LWES_U_INT_16     *value);
 419
 420 /*! \brief Get an LWES_INT_16 attribute from the event
 421  *
 422  *  \param[in] event the event to get the attribute from
 423  *  \param[in] name the name of the attribute
 424  *  \param[out] value the value of the attribute
 425  *
 426  *  \return 0 on success, a negative number on failure
 427  */
 428 int
 429 lwes_event_get_INT_16
 430   (struct lwes_event *event,
 431    LWES_CONST_SHORT_STRING  name,
 432    LWES_INT_16       *value);
 433
 434 /*! \brief Get an LWES_U_INT_32 attribute from the event
 435  *
 436  *  \param[in] event the event to get the attribute from
 437  *  \param[in] name the name of the attribute
 438  *  \param[out] value the value of the attribute
 439  *
 440  *  \return 0 on success, a negative number on failure
 441  */
 442 int
 443 lwes_event_get_U_INT_32
 444   (struct lwes_event *event,
 445    LWES_CONST_SHORT_STRING  name,
 446    LWES_U_INT_32     *value);
 447
 448 /*! \brief Get an LWES_INT_32 attribute from the event
 449  *
 450  *  \param[in] event the event to get the attribute from
 451  *  \param[in] name the name of the attribute
 452  *  \param[out] value the value of the attribute
 453  *
 454  *  \return 0 on success, a negative number on failure
 455  */
 456 int
 457 lwes_event_get_INT_32
 458   (struct lwes_event *event,
 459    LWES_CONST_SHORT_STRING  name,
 460    LWES_INT_32       *value);
 461
 462 /*! \brief Get an LWES_U_INT_64 attribute from the event
 463  *
 464  *  \param[in] event the event to get the attribute from
 465  *  \param[in] name the name of the attribute
 466  *  \param[out] value the value of the attribute
 467  *
 468  *  \return 0 on success, a negative number on failure
 469  */
 470 int
 471 lwes_event_get_U_INT_64
 472   (struct lwes_event *event,
 473    LWES_CONST_SHORT_STRING  name,
 474    LWES_U_INT_64     *value);
 475
 476 /*! \brief Get an LWES_INT_64 attribute from the event
 477  *
 478  *  \param[in] event the event to get the attribute from
 479  *  \param[in] name the name of the attribute
 480  *  \param[out] value the value of the attribute
 481  *
 482  *  \return 0 on success, a negative number on failure
 483  */
 484 int
 485 lwes_event_get_INT_64
 486   (struct lwes_event *event,
 487    LWES_CONST_SHORT_STRING  name,
 488    LWES_INT_64       *value);
 489
 490 /*! \brief Get an LWES_LONG_STRING attribute to the event
 491  *
 492  *  \param[in] event the event to add the attribute to
 493  *  \param[in] name the name of the attribute
 494  *  \param[in] value the value of the attribute, this should be treated
 495  *                   as const
 496  *
 497  *
 498  *  \return 0 on success, a negative number on failure
 499  */
 500 int
 501 lwes_event_get_STRING
 502   (struct lwes_event *event,
 503    LWES_CONST_SHORT_STRING  name,
 504    LWES_LONG_STRING  *value);
 505
 506 /*! \brief Get an LWES_IP_ADDR attribute from the event
 507  *
 508  *  \param[in] event the event to add the attribute to
 509  *  \param[in] name the name of the attribute
 510  *  \param[in] value the value of the attribute
 511  *
 512  *  \return 0 on success, a negative number on failure
 513  */
 514 int
 515 lwes_event_get_IP_ADDR
 516   (struct lwes_event       *event,
 517    LWES_CONST_SHORT_STRING  name,
 518    LWES_IP_ADDR            *value);
 519
 520 /*! \brief Get an LWES_BOOLEAN attribute from the event
 521  *
 522  *  \param[in] event the event to get the attribute from
 523  *  \param[in] name the name of the attribute
 524  *  \param[out] value the value of the attribute
 525  *
 526  *  \return 0 on success, a negative number on failure
 527  */
 528 int
 529 lwes_event_get_BOOLEAN
 530   (struct lwes_event       *event,
 531    LWES_CONST_SHORT_STRING  name,
 532    LWES_BOOLEAN            *value);
 533
 534 /*! \brief Serialize an event
 535
 536    Serialization format is
 537
 538    <pre>
 539     1 byte event name length ( 1 < b <= 255 )
 540     b bytes
 541     2 bytes num_attributes ( 0 < n < 65535, 65535 is a theoretical limit )
 542     foreach attribute
 543       1 byte attribute name length ( 1 < a <= 255 )
 544       a bytes of attribute name
 545       1 byte type id
 546       n bytes data
 547
 548    We want to determine the maximum possible number of attributes
 549    ( the real upper bound on n above ).
 550
 551    So we need to minimize all the fields,
 552
 553    Event name     = 1 byte of length + 1 byte of data = 2 bytes
 554    Num Attributes = 2 bytes
 555
 556    So the minimum is 4 bytes, that leaves 65531 to play with
 557
 558    For attributes,
 559
 560     minimum attribute length =
 561         (minimum attr name length                     = 1 byte)
 562       + (minimum attr name value, given minimum length= 1 byte)
 563       + (type id length                               = 1 byte)
 564       + (minimum size of attribute);
 565
 566     Where
 567
 568     minimum size boolean attribute = 1 byte
 569     minimum size uint16  attribute = 2 bytes
 570     minimum size int16   attribute = 2 bytes
 571     minimum size uint32  attribute = 4 bytes
 572     minimum size int32   attribute = 4 bytes
 573     minimum size uint64  attribute = 8 bytes
 574     minimum size int64   attribute = 8 bytes
 575     minimum size ipaddr  attribute = 4 bytes
 576     minimum size string  attribute = 2 bytes length + 1 byte data = 3 bytes
 577
 578     so
 579
 580     minimum boolean attribute =  4 byte
 581     minimum uint16  attribute =  5 bytes
 582     minimum int16   attribute =  5 bytes
 583     minimum uint32  attribute =  7 bytes
 584     minimum int32   attribute =  7 bytes
 585     minimum uint64  attribute = 11 bytes
 586     minimum int64   attribute = 11 bytes
 587     minimum ipaddr  attribute =  7 bytes
 588     minimum string  attribute =  6 bytes
 589
 590     If attribute names are allowed to be duplicated for a type, then the
 591     maximum number of attributes is
 592
 593       floor ( (65535 - 4) / 4) = 16382
 594
 595     However, attribute names are not allowed to be duplicated for any
 596     one type, so that puts a cap of 254, 1 non-zero byte attribute
 597     names ( 1 -> 255 ) for a single type, this means the actual number
 598     of attributes is actually less.
 599
 600     To maximally pack attributes we would start with the smallest
 601     in terms of number of bytes, then work our way upward calculating
 602     the number of attributes of a certain attribute name length of
 603     the smallest current type, so to start the chain
 604
 605     4 bytes overhead                  =    4
 606
 607     1 byte attribute booleans 254*4   = 1016
 608
 609     2 byte attribute booleans 254*5   = 1270
 610     1 byte attribute uint16   254*5   = 1270
 611     1 byte attribute int16    254*5   = 1270
 612
 613     1 byte attribute string   254*6   = 1524
 614     3 byte attribute booleans 254*6   = 1524
 615     2 byte attribute uint16   254*6   = 1524
 616     2 byte attribute int16    254*6   = 1524
 617
 618     1 byte attribute uint32   254*7   = 1778
 619     1 byte attribute int32    254*7   = 1778
 620     2 byte attribute string   254*7   = 1778
 621     4 byte attribute booleans 254*7   = 1778
 622     3 byte attribute uint16   254*7   = 1778
 623     3 byte attribute int16    254*7   = 1778
 624     1 byte attribute ipaddr   254*7   = 1778
 625
 626     2 byte attribute uint32   254*8   = 2032
 627     2 byte attribute int32    254*8   = 2032
 628     3 byte attribute string   254*8   = 2032
 629     5 byte attribute booleans 254*8   = 2032
 630     4 byte attribute uint16   254*8   = 2032
 631     4 byte attribute int16    254*8   = 2032
 632     2 byte attribute ipaddr   254*8   = 2032
 633
 634     3 byte attribute uint32   254*9   = 2286
 635     3 byte attribute int32    254*9   = 2286
 636     4 byte attribute string   254*9   = 2286
 637     6 byte attribute booleans 254*9   = 2286
 638     5 byte attribute uint16   254*9   = 2286
 639     5 byte attribute int16    254*9   = 2286
 640     3 byte attribute ipaddr   254*9   = 2286
 641
 642     4 byte attribute uint32   254*10  = 2540
 643     4 byte attribute int32    254*10  = 2540
 644     5 byte attribute string   254*10  = 2540
 645     7 byte attribute booleans 254*10  = 2540
 646
 647     6 byte attribute uint16   177*10  = 1770
 648
 649     7 bytes left over                 =    7
 650
 651     total attrs = 33 * 254 + 177 = 8559
 652     </pre>
 653
 654     \param[in] event the event to serialize
 655     \param[in] bytes the byte array to serialize into
 656     \param[in] num_bytes the size of the byte array
 657     \param[in] offset the offset into the array to start serializing at
 658
 659     \return The number of bytes written to the array on success,
 660              a negative number on failure
 661 */
 662 int
 663 lwes_event_to_bytes
 664   (struct lwes_event *event,
 665    LWES_BYTE_P bytes,
 666    size_t num_bytes,
 667    size_t offset);
 668
 669 /*! \brief Deserialize an event
 670
 671     \param[in] event the event to deserialize into
 672     \param[in] bytes the byte array to serialize into
 673     \param[in] num_bytes the size of the byte array
 674     \param[in] offset the offset into the array to start serializing at
 675     \param[in] dtmp some temporary space to deserialize strings into
 676
 677     \return The number of bytes read from the array on success,
 678              a negative number on failure
 679 */
 680 int
 681 lwes_event_from_bytes
 682   (struct lwes_event *event,
 683    LWES_BYTE_P bytes,
 684    size_t num_bytes,
 685    size_t offset,
 686    struct lwes_event_deserialize_tmp *dtmp);
 687
 688 /*! \brief Start an enumeration over the keys of the event
 689  *
 690  *  The pattern for enumerating is as follows
 691  *
 692  *  struct lwes_event_enumeration e;
 693  *
 694  *  if (lwes_event_keys (event, &e))
 695  *    {
 696  *      LWES_CONST_SHORT_STRING key;
 697  *      LWES_TYPE type;
 698  *      while (lwes_event_enumeration_next_element (&e, &key, &type))
 699  *        {
 700  *           switch (type)
 701  *            {
 702  *              case LWES_TYPE_U_INT_16:
 703  *                {
 704  *                  LWES_U_INT_16     value;
 705  *                  lwes_event_get_U_INT_16 (event, key, &value);
 706  *                }
 707  *                break;
 708  *              // ... cases for rest of types
 709  *            }
 710  *        }
 711  *    }
 712  *
 713  *  \param[in] event the event to enumerate over
 714  *  \param[in] enumeration keeps track of the enumeration
 715  *
 716  *  \return 1 if it's possible to enumerate over this event, 0 if it is not.
 717  */
 718 int
 719 lwes_event_keys
 720   (struct lwes_event * event,
 721    struct lwes_event_enumeration *enumeration);
 722
 723 /*! \brief Get the next element from the event
 724  *
 725  *  \param[in] enumeration keeps track of the enumeration
 726  *  \param[out] key the key for the next element of the event
 727  *  \param[out] type the type of the next element of the event
 728  *
 729  *  \return 1 if it's possible to enumerate over this event, 0 if it is not.
 730  */
 731 int
 732 lwes_event_enumeration_next_element
 733   (struct lwes_event_enumeration *enumeration,
 734    LWES_CONST_SHORT_STRING *key,
 735    LWES_TYPE *type);
 736
 737 #ifdef __cplusplus
 738 }
 739 #endif
 740 #endif /* __LWES_EVENT_FUNCTIONS_H */