docs/reference-v3/func-event.md

   1 Functions of class **afb_event**
   2 ==============================
   3
   4 ## General functions
   5
   6 ### afb_event_is_valid
   7
   8 ```C
   9 /**
  10  * Checks whether the 'event' is valid or not.
  11  *
  12  * @param event the event to check
  13  *
  14  * @return 0 if not valid or 1 if valid.
  15  */
  16 int afb_event_is_valid(
  17                         afb_event_t event);
  18 ```
  19
  20 ### afb_event_name
  21
  22 ```C
  23 /**
  24  * Gets the name associated to 'event'.
  25  *
  26  * @param event the event whose name is requested
  27  *
  28  * @return the name of the event
  29  *
  30  * The returned name can be used until call to 'afb_event_unref'.
  31  * It shouldn't be freed.
  32  */
  33 const char *afb_event_name(
  34                         afb_event_t event);
  35 ```
  36
  37 ### afb_event_unref
  38
  39 ```C
  40 /**
  41  * Decrease the count of references to 'event'.
  42  * Call this function when the evenid is no more used.
  43  * It destroys the event_x2 when the reference count falls to zero.
  44  *
  45  * @param event the event
  46  */
  47 void afb_event_unref(
  48                         afb_event_t event);
  49 ```
  50
  51 ### afb_event_addref
  52
  53 ```C
  54 /**
  55  * Increases the count of references to 'event'
  56  *
  57  * @param event the event
  58  *
  59  * @return the event
  60  */
  61 afb_event_t *afb_event_addref(
  62                         afb_event_t event);
  63 ```
  64
  65 ## Pushing functions
  66
  67 ### afb_event_broadcast
  68
  69 ```C
  70 /**
  71  * Broadcasts widely an event of 'event' with the data 'object'.
  72  * 'object' can be NULL.
  73  *
  74  * For convenience, the function calls 'json_object_put' for 'object'.
  75  * Thus, in the case where 'object' should remain available after
  76  * the function returns, the function 'json_object_get' shall be used.
  77  *
  78  * @param event the event to broadcast
  79  * @param object the companion object to associate to the broadcasted event (can be NULL)
  80  *
  81  * @return the count of clients that received the event.
  82  */
  83 int afb_event_broadcast(
  84                         afb_event_t event,
  85                         struct json_object *object);
  86 ```
  87
  88 ### afb_event_push
  89
  90 ```C
  91 /**
  92  * Pushes an event of 'event' with the data 'object' to its observers.
  93  * 'object' can be NULL.
  94  *
  95  * For convenience, the function calls 'json_object_put' for 'object'.
  96  * Thus, in the case where 'object' should remain available after
  97  * the function returns, the function 'json_object_get' shall be used.
  98  *
  99  * @param event the event to push
 100  * @param object the companion object to associate to the pushed event (can be NULL)
 101  *
 102  * @return the count of clients that received the event.
 103  */
 104 int afb_event_push(
 105                         afb_event_t event,
 106                         struct json_object *object);
 107 ```
 108