src/lwes_emitter.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_EMITTER_H
  21 #define __LWES_EMITTER_H
  22
  23 #include "lwes_types.h"
  24 #include "lwes_net_functions.h"
  25 #include "lwes_event.h"
  26
  27 #include <stdio.h>
  28 #include <time.h>
  29
  30 #ifdef __cplusplus
  31 extern "C" {
  32 #endif
  33
  34 /*! \file lwes_emitter.h
  35  *  \brief Functions for emitting LWES events
  36  */
  37
  38 /*! \struct lwes_emitter lwes_emitter.h
  39  *  \brief Emits LWES events
  40  */
  41 struct lwes_emitter
  42 {
  43   /*! multicast channel to emit to */
  44   struct lwes_net_connection connection;
  45   /*! buffer for serialization of events */
  46   LWES_BYTE_P buffer;
  47   /*! count of total events sent */
  48   LWES_INT_64 count;
  49   /*! count of events sent since last heartbeat event */
  50   LWES_INT_64 count_since_last_beat;
  51   /*! sequence number of heartbeats */
  52   LWES_INT_64 sequence;
  53   /*! frequency in seconds of heartbeats */
  54   LWES_INT_16 frequency;
  55   /*! boolean for whether or not to emit heartbeats */
  56   LWES_BOOLEAN emitHeartbeat;
  57   /*! time of last heartbeat */
  58   time_t last_beat_time;
  59 };
  60
  61 /*! \brief Create an Emitter
  62  *
  63  *  \param[in] address        The multicast ip address as a dotted quad string
  64  *                            of the channel to emit to.
  65  *  \param[in] iface          The dotted quad ip address of the interface to
  66  *                            send messages on, can be NULL to use default.
  67  *  \param[in] port           The port of the channel to emit to.
  68  *  \param[in] emit_heartbeat Set to 1 to emit heartbeats, set to 0 to not
  69  *                            emit heartbeats.
  70  *  \param[in] freq           Number of seconds between heartbeats.
  71  *
  72  *  \see lwes_emitter_destroy
  73  *
  74  *  \return A newly created emitter, use lwes_emitter_destroy to free
  75  */
  76 struct lwes_emitter *
  77 lwes_emitter_create
  78   (LWES_CONST_SHORT_STRING address,
  79    LWES_CONST_SHORT_STRING iface,
  80    LWES_U_INT_32 port,
  81    LWES_BOOLEAN emit_heartbeat,
  82    LWES_INT_16 freq);
  83
  84 /*! \brief Create an Emitter with a TTL
  85  *
  86  *  \param[in] address        The multicast ip address as a dotted quad string
  87  *                            of the channel to emit to.
  88  *  \param[in] iface          The dotted quad ip address of the interface to
  89  *                            send messages on, can be NULL to use default.
  90  *  \param[in] port           The port of the channel to emit to.
  91  *  \param[in] emit_heartbeat Set to 1 to emit heartbeats, set to 0 to not
  92  *                            emit heartbeats.
  93  *  \param[in] freq           Number of seconds between heartbeats.
  94  *  \param[in] ttl            The ttl to use for emitted events
  95  *
  96  *  \see lwes_emitter_destroy
  97  *
  98  *  \return A newly created emitter, use lwes_emitter_destroy to free
  99  */
 100 struct lwes_emitter *
 101 lwes_emitter_create_with_ttl
 102   (LWES_CONST_SHORT_STRING address,
 103    LWES_CONST_SHORT_STRING iface,
 104    LWES_U_INT_32 port,
 105    LWES_BOOLEAN emit_heartbeat,
 106    LWES_INT_16 freq,
 107    LWES_U_INT_32 ttl);
 108
 109 /*! \brief Emit an event to the multicast channel defined in the emitter
 110  *
 111  *  \param[in] emitter The emitter to emit to
 112  *  \param[in] event   The event to emit
 113  *
 114  *  \return 0 on success, a negative number on failure
 115  */
 116 int
 117 lwes_emitter_emit
 118   (struct lwes_emitter *emitter,
 119    struct lwes_event *event);
 120
 121 /*! \brief Emit an event to a different multicast channel
 122  *
 123  *  \param[in] address The multicast ip address as a dotted quad string
 124  *                     of the channel to emit to.
 125  *  \param[in] iface   The dotted quad ip address of the interface to
 126  *                     send messages on, can be NULL to use default.
 127  *  \param[in] port    The port of the channel to emit to.
 128  *  \param[in] emitter The emitter to use for holding the send buffer
 129  *  \param[in] event   The event to emit
 130  *
 131  *  \return 0 on success, a negative number on failure
 132  */
 133 int
 134 lwes_emitter_emitto
 135   (LWES_SHORT_STRING address,
 136    LWES_SHORT_STRING iface,
 137    LWES_U_INT_32 port,
 138    struct lwes_emitter *emitter,
 139    struct lwes_event *event);
 140
 141 /*! \brief Emit bytes to a multicast channel
 142  *
 143  * Use this in re-emitter's so that you don't have to deserialize and
 144  * reserialize, NOTE: this will not result in statistics being incremented
 145  *
 146  *  \param[in] emitter The emitter to emit to
 147  *  \param[in] bytes   The bytes to emit
 148  *  \param[in] length  The number of bytes to emit
 149  *
 150  *  \return the number of bytes sent on success, a negative number on failure
 151  */
 152 int
 153 lwes_emitter_emit_bytes
 154   (struct lwes_emitter *emitter,
 155    LWES_BYTE_P bytes,
 156    size_t length);
 157
 158 /*! \brief Destroy an Emitter
 159  *
 160  * \param[in] emitter The emitter to destroy by freeing all of it's used
 161  *                    memory.
 162  *
 163  * \return 0 on success, negative number on failure
 164  */
 165 int
 166 lwes_emitter_destroy
 167   (struct lwes_emitter *emitter);
 168
 169 #ifdef __cplusplus
 170 }
 171 #endif
 172
 173 #endif /* __LWES_EMITTER_H */