Commit 1749564d authored by Ian Murdock's avatar Ian Murdock
Browse files

Make function header comments easier to read.

parent 71363091
......@@ -7,7 +7,7 @@
* @COPYRIGHT@
*/
static char rcsid[] = "$Id: event.c,v 1.4 2001-11-06 17:12:39 imurdock Exp $";
static char rcsid[] = "$Id: event.c,v 1.5 2001-12-04 15:10:21 imurdock Exp $";
#include <stdio.h>
#include <assert.h>
......@@ -23,20 +23,24 @@ static char rcsid[] = "$Id: event.c,v 1.4 2001-11-06 17:12:39 imurdock Exp $";
static char hostname[MAXHOSTNAMELEN];
/* 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.
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. */
/*
* 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.
*
* 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.
*/
event_handle_t
event_register(char *name)
{
......@@ -97,8 +101,12 @@ event_register(char *name)
return handle;
}
/* Unregister with the testbed event system. Returns non-zero if the
operation is successful, 0 otherwise. */
/*
* Unregister with the testbed event system. Returns non-zero if the
* operation is successful, 0 otherwise.
*/
int
event_unregister(event_handle_t handle)
{
......@@ -134,9 +142,13 @@ event_unregister(event_handle_t handle)
return 1;
}
/* Enter the main loop of the event system, waiting to receive event
notifications. Returns non-zero if the operation is successful, 0
otherwise. */
/*
* Enter the main loop of the event system, waiting to receive event
* notifications. Returns non-zero if the operation is successful, 0
* otherwise.
*/
int
event_main(event_handle_t handle)
{
......@@ -158,10 +170,14 @@ event_main(event_handle_t handle)
return 1;
}
/* 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.
Returns non-zero if the operation is successful, 0 otherwise. */
/*
* 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.
* Returns non-zero if the operation is successful, 0 otherwise.
*/
int
event_notify(event_handle_t handle, event_notification_t notification)
{
......@@ -185,12 +201,16 @@ event_notify(event_handle_t handle, event_notification_t notification)
return 1;
}
/* 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. Returns
a pointer to an event notification structure if the operation
is successful, 0 otherwise. */
/*
* 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. Returns
* a pointer to an event notification structure if the operation
* is successful, 0 otherwise.
*/
event_notification_t
event_notification_alloc(event_handle_t handle, char *host, event_type_t type)
{
......@@ -235,8 +255,12 @@ event_notification_alloc(event_handle_t handle, char *host, event_type_t type)
return notification;
}
/* Free the event notification NOTIFICATION. Returns non-zero if the
operation is successful, 0 otherwise. */
/*
* Free the event notification NOTIFICATION. Returns non-zero if the
* operation is successful, 0 otherwise.
*/
int
event_notification_free(event_handle_t handle,
event_notification_t notification)
......@@ -257,6 +281,7 @@ event_notification_free(event_handle_t handle,
return 1;
}
struct attr_traverse_arg {
event_attr_type_t type;
char *name;
......@@ -266,10 +291,13 @@ struct attr_traverse_arg {
static int attr_traverse(void *rock, char *name, elvin_basetypes_t type,
elvin_value_t value, elvin_error_t error);
/* Get the attribute with name NAME and type TYPE from the event
notification NOTIFICATION.
Writes the value of the attribute to *VALUE and returns
non-zero if the named attribute is found, 0 otherwise. */
/*
* Get the attribute with name NAME and type TYPE from the event
* notification NOTIFICATION.
* Writes the value of the attribute to *VALUE and returns
* non-zero if the named attribute is found, 0 otherwise.
*/
int
event_notification_attr_get(event_handle_t handle,
event_notification_t notification,
......@@ -307,9 +335,13 @@ event_notification_attr_get(event_handle_t handle,
return 0;
}
/* Add an attribute with name NAME, type TYPE, and value
VALUE to the notification NOTIFICATION. Returns
non-zero if the operation is successful, 0 otherwise. */
/*
* Add an attribute with name NAME, type TYPE, and value
* VALUE to the notification NOTIFICATION. Returns
* non-zero if the operation is successful, 0 otherwise.
*/
int
event_notification_attr_put(event_handle_t handle,
event_notification_t notification,
......@@ -378,6 +410,7 @@ event_notification_attr_put(event_handle_t handle,
return 1;
}
struct notify_callback_arg {
event_notify_callback_t callback;
void *data;
......@@ -390,19 +423,22 @@ static void notify_callback(elvin_handle_t server,
#define EXPRESSION_LENGTH 1024
/* 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,
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,
* void *data);
*
* where HANDLE is the handle to the event server, NOTIFICATION is
* 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.
*/
where HANDLE is the handle to the event server, NOTIFICATION is
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. */
event_subscription_t
event_subscribe(event_handle_t handle, event_notify_callback_t callback,
event_type_t type, void *data)
......@@ -443,9 +479,13 @@ event_subscribe(event_handle_t handle, event_notify_callback_t callback,
return subscription;
}
/* Callback passed to elvin_notification_traverse in
event_notification_attr_get.
Returns 0 if the desired attribute is found, 1 otherwise. */
/*
* Callback passed to elvin_notification_traverse in
* event_notification_attr_get.
* Returns 0 if the desired attribute is found, 1 otherwise.
*/
static int
attr_traverse(void *rock, char *name, elvin_basetypes_t type,
elvin_value_t value, elvin_error_t error)
......@@ -464,8 +504,12 @@ attr_traverse(void *rock, char *name, elvin_basetypes_t type,
return 1;
}
/* Callback passed to elvin_sync_add_subscription in
event_subscribe. Used to provide our own callback above Elvin's. */
/*
* Callback passed to elvin_sync_add_subscription in
* event_subscribe. Used to provide our own callback above Elvin's.
*/
static void
notify_callback(elvin_handle_t server,
elvin_subscription_t subscription,
......
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