Commit 2a859a70 authored by Ian Murdock's avatar Ian Murdock

Updated API documentation.

parent 737cd1a1
......@@ -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.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment