API 9.04 KB
Newer Older
Ian Murdock's avatar
Ian Murdock committed
1 2 3 4
* event_register: Register with the testbed event system

      #include <event.h>

Ian Murdock's avatar
Ian Murdock committed
5
      event_handle_t event_register(char *name, int threaded);
Ian Murdock's avatar
Ian Murdock committed
6

7 8 9 10 11
  Register with the testbed event system.  NAME specifies the name of
  the event server.  Returns a pointer to a handle that may be passed
  to other event system routines if the operation is successful, NULL
  otherwise.

Ian Murdock's avatar
Ian Murdock committed
12 13 14 15 16 17 18 19 20
  The THREADED parameter should be set to 1 if the registering
  client is multi-threaded. If THREADED is 1, the event
  library will call routines that are thread-safe, and event
  notifications will be dispatched using background threads (i.e.,
  the client will supply its own event loop). If THREADED is 0, event
  notifications will be dispatched using an event system-provided
  event loop, and the client must call event_main after connecting in
  order to receive notifications.

21 22 23 24 25 26 27 28 29
  Elvin note: NAME is a URL of the form "elvin:/[protocol
  stack]/[endpoint]", where a protocol stack names a transport
  module, a security module, and a marshaling module as a comma
  separated list (e.g., "http,none,xml"), and the endpoint format
  is dependent on the transport module used.  If no protocol
  stack is given, the default stack (tcp, none, xdr) is used.  For the
  testbed's purposes, "elvin://HOSTNAME" should suffice.  If NAME
  is NULL, then Elvin's server discovery protocol will be used to find
  the Elvin server.
Ian Murdock's avatar
Ian Murdock committed
30 31 32 33 34 35 36 37


* event_unregister: Unregister with the testbed event system

      #include <event.h>

      int event_unregister(event_handle_t handle);

Ian Murdock's avatar
Ian Murdock committed
38
  Unregister with the testbed event system. Returns non-zero if the
Ian Murdock's avatar
Ian Murdock committed
39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57
  operation is successful, 0 otherwise.


* event_main: Enter the main loop of the event system

      #include <event.h>

      int event_main(event_handle_t handle);

  Enter the main loop of the event system, waiting to receive event
  notifications. Returns non-zero if the operation is successful, 0
  otherwise.


* event_notify: Send an event notification

      #include <event.h>

      int event_notify(event_handle_t handle,
58
                       event_notification_t notification);
Ian Murdock's avatar
Ian Murdock committed
59 60 61

  Send the event notification NOTIFICATION.  NOTIFICATION is
  allocated by event_notification_alloc, and may optionally
Ian Murdock's avatar
Ian Murdock committed
62
  have attributes added to it by event_notification_put_*.
Ian Murdock's avatar
Ian Murdock committed
63 64
  Returns non-zero if the operation is successful, 0 otherwise.

Ian Murdock's avatar
Ian Murdock committed
65 66 67 68
  Note that NOTIFICATION is not deallocated by event_notify.  The
  caller is responsible for deallocating the notification when it
  is finished with it.

Ian Murdock's avatar
Ian Murdock committed
69

Ian Murdock's avatar
Ian Murdock committed
70 71 72 73 74
* event_schedule: Schedule an event notification

      #include <event.h>

      int event_schedule(event_handle_t handle,
75
                         event_notification_t notification,
Ian Murdock's avatar
Ian Murdock committed
76 77 78 79 80 81 82 83 84 85 86 87
                         struct timeval *time);

  Schedule the event notification NOTIFICATION to be sent at time
  TIME. NOTIFICATION is allocated by event_notification_alloc,
  and may optionally have attributes added to it by
  event_notification_put_*. Returns non-zero if the operation
  is successful, 0 otherwise.

  This function essentially operates as a deferred event_notify.
  event_notify sends notifications immediately,
  whereas event_schedule sends notifications at some later time.

Ian Murdock's avatar
Ian Murdock committed
88 89 90 91
  Note that NOTIFICATION is not deallocated by event_schedule.
  The caller is responsible for deallocating the notification
  when it is finished with it.

Ian Murdock's avatar
Ian Murdock committed
92

Ian Murdock's avatar
Ian Murdock committed
93 94 95 96 97 98 99 100 101 102 103
* event_notification_alloc: Allocate an event notification

      #include <event.h>

      event_notification_t event_notification_alloc(event_handle_t handle,
                                                    char *host,
                                                    event_type_t type);

  Allocate an event notification.  The HOST parameter specifies
  the hostname of the node that should receive the notification,
  or EVENT_HOST_ANY if the notification should go to all hosts.
Ian Murdock's avatar
Ian Murdock committed
104 105 106
  The TYPE parameter specifies the event type. Returns
  a pointer to an event notification structure if the operation
  is successful, 0 otherwise.
Ian Murdock's avatar
Ian Murdock committed
107 108 109 110 111 112 113 114 115


* event_notification_free: Free an event notification

      #include <event.h>

      int event_notification_free(event_handle_t handle,
                                  event_notification_t notification);

Ian Murdock's avatar
Ian Murdock committed
116
  Free the event notification NOTIFICATION. Returns non-zero if the
Ian Murdock's avatar
Ian Murdock committed
117 118 119
  operation is successful, 0 otherwise.


Ian Murdock's avatar
Ian Murdock committed
120
* event_notification_get_*: Get an attribute from an event notification
Ian Murdock's avatar
Ian Murdock committed
121 122 123

      #include <event.h>

Ian Murdock's avatar
Ian Murdock committed
124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152
      int event_notification_get_double(event_handle_t handle,
                                        event_notification_t notification,
                                        char *name,
                                        double *value);
      int event_notification_get_int32(event_handle_t handle,
                                       event_notification_t notification,
                                       char *name,
                                       int32_t *value);
      int event_notification_get_int64(event_handle_t handle,
                                       event_notification_t notification,
                                       char *name,
                                       int64_t *value);
      int event_notification_get_opaque(event_handle_t handle,
                                        event_notification_t notification,
                                        char *name,
                                        void *buffer,
                                        int length);
      int event_notification_get_string(event_handle_t handle,
                                        event_notification_t notification,
                                        char *name,
                                        char *buffer,
                                        int length);

  Get the attribute with name NAME from the event notification
  NOTIFICATION.

  For _double, _int32 and _int64: Writes the value of the attribute
  to *VALUE and returns non-zero if the named attribute is found, 0
  otherwise.
Ian Murdock's avatar
Ian Murdock committed
153

Ian Murdock's avatar
Ian Murdock committed
154 155
  For _opaque and _string: Writes LENGTH bytes into *BUFFER and
  returns non-zero if the named attribute is found, 0 otherwise.
Ian Murdock's avatar
Ian Murdock committed
156 157


Ian Murdock's avatar
Ian Murdock committed
158
* event_notification_put_*: Add an attribute to an event notification
Ian Murdock's avatar
Ian Murdock committed
159 160 161

      #include <event.h>

Ian Murdock's avatar
Ian Murdock committed
162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191
      int event_notification_put_double(event_handle_t handle,
                                        event_notification_t notification,
                                        char *name,
                                        double value);
      int event_notification_put_int32(event_handle_t handle,
                                       event_notification_t notification,
                                       char *name,
                                       int32_t value);
      int event_notification_put_int64(event_handle_t handle,
                                       event_notification_t notification,
                                       char *name,
                                       int64_t value);
      int event_notification_put_opaque(event_handle_t handle,
                                        event_notification_t notification,
                                        char *name,
                                        void *buffer,
                                        int length);
      int event_notification_put_string(event_handle_t handle,
                                        event_notification_t notification,
                                        char *value);

  Add an attribute with name NAME to the event notification
  NOTIFICATION. For _double, _int32, _int64, and _string: The value
  is specified in VALUE. For _opaque: The value is specified
  in the buffer BUFFER which has length LENGTH. Returns non-zero if
  the operation is successful, 0 otherwise.


* event_notification_attr_remove: Remove an attribute from an event
  notification
Ian Murdock's avatar
Ian Murdock committed
192

Ian Murdock's avatar
Ian Murdock committed
193
      #include <event.h>
Ian Murdock's avatar
Ian Murdock committed
194

Ian Murdock's avatar
Ian Murdock committed
195 196 197
      int event_notification_remove(event_handle_t handle,
                                    event_notification_t notification,
                                    char *name);
Ian Murdock's avatar
Ian Murdock committed
198

Ian Murdock's avatar
Ian Murdock committed
199 200 201
  Remove the attribute with name NAME from the event notification
  NOTIFICATION.  Returns non-zero if the operation is successful,
  0 otherwise.
Ian Murdock's avatar
Ian Murdock committed
202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219


* event_subscribe: Subscribe to an event

      #include <event.h>

      event_subscription_t event_subscribe(event_handle_t handle,
                                           event_notify_callback_t callback,
                                           event_type_t type,
                                           void *data);

  Subscribe to events of type TYPE.  Event notifications that match
  TYPE will be passed to the callback function CALLBACK; DATA is
  an arbitrary pointer that will be passed to the callback function.
  Callback functions are of the form

      void callback(event_handle_t handle,
                    event_notification_t notification,
Ian Murdock's avatar
Ian Murdock committed
220 221
                    char *host,
                    event_type_t type,
Ian Murdock's avatar
Ian Murdock committed
222 223
                    void *data);

Ian Murdock's avatar
Ian Murdock committed
224 225
  where HANDLE is the handle to the event server, NOTIFICATION is the
  event notification, HOST and TYPE are the respective attributes of
Ian Murdock's avatar
Ian Murdock committed
226 227 228
  the event notification, and DATA is the arbitrary pointer passed to
  event_subscribe.  Returns a pointer to an event
  subscription structure if the operation is successful, 0 otherwise.