Updated API documentation.

event/API

@@ -26,7 +26,7 @@
 
       int event_unregister(event_handle_t handle);
 
-  Unregister with the testbed event system.  Returns non-zero if the
+  Unregister with the testbed event system. Returns non-zero if the
   operation is successful, 0 otherwise.
 
 
@@ -50,10 +50,29 @@
 
   Send the event notification NOTIFICATION.  NOTIFICATION is
   allocated by event_notification_alloc, and may optionally
-  have attributes added to it by event_notification_attr_put.
+  have attributes added to it by event_notification_put_*.
   Returns non-zero if the operation is successful, 0 otherwise.
 
 
+* event_schedule: Schedule an event notification
+
+      #include <event.h>
+
+      int event_schedule(event_handle_t handle,
+                         event_notification notification,
+                         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.
+
+
 * event_notification_alloc: Allocate an event notification
 
       #include <event.h>
@@ -65,15 +84,9 @@
   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.
-  The TYPE parameter specifies the event type.  The event types
-  currently recognized are:
-
-      EVENT_TEST - test event
-      EVENT_TRAFGEN_START - start generating traffic
-      EVENT_TRAFGEN_STOP - stop generating traffic
-
-  Returns a pointer to an event notification structure if the
-  operation is successful, 0 otherwise.
+  The TYPE parameter specifies the event type. Returns
+  a pointer to an event notification structure if the operation
+  is successful, 0 otherwise.
 
 
 * event_notification_free: Free an event notification
@@ -83,51 +96,92 @@
       int event_notification_free(event_handle_t handle,
                                   event_notification_t notification);
 
-  Free the event notification NOTIFICATION.  Returns non-zero if the
+  Free the event notification NOTIFICATION. Returns non-zero if the
   operation is successful, 0 otherwise.
 
 
-* event_notification_attr_get: Get an attribute from an event notification
+* event_notification_get_*: Get an attribute from an event notification
 
       #include <event.h>
 
-      int event_notification_attr_get(event_handle_t handle,
-                                      event_notification_t notification,
-                                      event_attr_type_t type,
-                                      char *name,
-                                      event_attr_value_t *value);
-
-  Get the attribute with name NAME and type TYPE from the event
-  notification NOTIFICATION.  Valid attribute types are:
-
-      EVENT_ATTR_INT32: 32-bit integer
-      EVENT_ATTR_INT64: 64-bit integer
-      EVENT_ATTR_DOUBLE: double precision floating point
-      EVENT_ATTR_STRING: string
+      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.
 
-  Writes the value of the attribute to *VALUE and returns non-zero
-  if the named attribute is found, 0 otherwise.
+  For _opaque and _string: Writes LENGTH bytes into *BUFFER and
+  returns non-zero if the named attribute is found, 0 otherwise.
 
 
-* event_notification_attr_put: Add an attribute to an event notification
+* event_notification_put_*: Add an attribute to an event notification
 
       #include <event.h>
 
-      int event_notification_attr_put(event_handle_t handle,
-                                      event_notification_t notification,
-                                      event_attr_type_t type,
-                                      char *name,
-                                      event_attr_value_t value);
+      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
 
-  Add an attribute with name NAME, type TYPE, and value VALUE to the
-  notification NOTIFICATION.  Valid attribute types are:
+      #include <event.h>
 
-      EVENT_ATTR_INT32: 32-bit integer
-      EVENT_ATTR_INT64: 64-bit integer
-      EVENT_ATTR_DOUBLE: double precision floating point
-      EVENT_ATTR_STRING: string
+      int event_notification_remove(event_handle_t handle,
+                                    event_notification_t notification,
+                                    char *name);
 
-  Returns non-zero if the operation is successful, 0 otherwise.
+  Remove the attribute with name NAME from the event notification
+  NOTIFICATION.  Returns non-zero if the operation is successful,
+  0 otherwise.
 
 
 * event_subscribe: Subscribe to an event
@@ -146,9 +200,12 @@
 
       void callback(event_handle_t handle,
                     event_notification_t notification,
+                    char *host,
+                    event_type_t type,
                     void *data);
 
-  where HANDLE is the handle to the event server, NOTIFICATION is
+  where HANDLE is the handle to the event server, NOTIFICATION is the
+  event notification, HOST and TYPE are the respective attributes of
   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.