Added documentation
diff --git a/contiki/ek/ek-service.h b/contiki/ek/ek-service.h
index 829a329..ebede37 100644
--- a/contiki/ek/ek-service.h
+++ b/contiki/ek/ek-service.h
@@ -30,8 +30,25 @@
*
* Author: Adam Dunkels <adam@sics.se>
*
- * $Id: ek-service.h,v 1.3 2004/09/12 20:24:55 adamdunkels Exp $
+ * $Id: ek-service.h,v 1.4 2005/02/07 07:50:35 adamdunkels Exp $
*/
+
+/**
+ * \addtogroup ek
+ * @{
+ */
+
+/**
+ * \defgroup ekservice The service layer
+ * @{
+ */
+
+/**
+ * \file
+ * Service layer header file.
+ * \author Adam Dunkels <adam@sics.se>
+ */
+
#ifndef __EK_SERVICE_H__
#define __EK_SERVICE_H__
@@ -41,19 +58,155 @@
const char *name;
ek_id_t id;
};
+
+/**
+ * Declare a service state.
+ *
+ * This macro declares a service state. The service state is used to
+ * access a particular service. The declared service state serves as
+ * the input to all other service functions.
+ *
+ * \param service The name of the service state.
+ * \param name The name of the service - this is defined in the header file of the service.
+ *
+ * \hideinitializer
+ */
#define EK_SERVICE(service, name) \
static struct ek_service service = {name, EK_ID_NONE}
+/**
+ * Start a service.
+ *
+ * This function is called from within a service in order to start the
+ * service process and to register the service with Contiki. If
+ * another instance of the same service is running, it is requested to
+ * shut itself down before the current service is started.
+ *
+ * This function is the equivalent of ek_start() but for services.
+ *
+ * \note Do not call the function ek_start() from a service, use
+ * ek_service_start() instead.
+ *
+ * \param name The name of the service. The first part of the name
+ * must be indentical for all services of the same kind.
+ *
+ * \param p The process structure for the service.
+ *
+ * \return The process ID of the service.
+ */
ek_id_t ek_service_start(const char *name, struct ek_proc *p);
+/**
+ * Find a running service.
+ *
+ * This function finds a running service. The function is called from
+ * programs that utilize the service, not from within a service process.
+ *
+ * Example:
+ \code
+ #include "packet-service.h"
+
+ EK_SERVICE(packetservice, PACKET_SERVICE_NAME);
+
+ void stop_packetservice(void) {
+ if(ek_service_find(&packetservice) == EK_ERR_OK) {
+ ek_service_post(&packetservice, EK_EVENT_REQUEST_EXIT, NULL);
+ ek_service_reset(&packetservice);
+ }
+ }
+ \endcode
+ *
+ * \param s The service state. This state is filled in with
+ * information by the ek_service_find() function.
+ *
+ * \retval EK_ERR_OK The requested service was found.
+ * \retval EK_ERR_NOTFOUND The requested service was not found.
+ */
ek_err_t ek_service_find(struct ek_service *s);
+/**
+ * Retrieve the service interface for a running service.
+ *
+ * This function retrieves the service interface (the API for the
+ * service) for a running service. The service state must first have
+ * been looked up using the ek_service_find() function.
+ *
+ * This function is used in the service stub.
+ *
+ * Example
+ \code
+ #include "packet-service.h"
+
+ EK_SERVICE(packetservice, PACKET_SERVICE_NAME);
+
+ static struct packet_service_interface *
+ find_interface(void)
+ {
+ struct packet_service_interface *interface;
+ interface = (struct packet_service_interface *)ek_service_state(&service);
+ if(interface != NULL &&
+ interface->version == PACKET_SERVICE_VERSION) {
+ return interface;
+ } else {
+ return NULL;
+ }
+ }
+ \endcode
+ *
+ * \param s The service state that previously has been looked up with
+ * ek_service_find().
+ *
+ * \return A pointer to the service interface if the requested service
+ * is running, or NULL if no such service was found.
+ */
void *ek_service_state(struct ek_service *s);
+/**
+ * Reset a service.
+ *
+ * When a service is looked up by Contiki, the process ID of the
+ * service is cached. This function resets the cache so that a running
+ * service can be removed from the system.
+ *
+ * Example:
+ \code
+ #include "packet-service.h"
+
+ EK_SERVICE(packetservice, PACKET_SERVICE_NAME);
+
+ void stop_packetservice(void) {
+ if(ek_service_find(&packetservice) == EK_ERR_OK) {
+ ek_service_post(&packetservice, EK_EVENT_REQUEST_EXIT, NULL);
+ ek_service_reset(&packetservice);
+ }
+ }
+ \endcode
+ *
+ * \param s The service state.
+ */
void ek_service_reset(struct ek_service *s);
+/**
+ * Post an event to a running service.
+ *
+ * This macro posts an event to a running service. The service must
+ * first be looked up using ek_service_find().
+ *
+ * \sa ek_post().
+ *
+ * \param s The service state
+ * \param ev The event to be posted.
+ * \param data An opaque pointer to be posted with the event.
+ *
+ * \hideinitializer
+ */
+#define ek_service_post(s, ev, data) ek_post((s)->id, (ev), (data))
/*ek_err_t ek_service_call(struct ek_service *s,
ek_event_t ev, ek_data_t data);*/
+/** @} */
+/** @} */
+
#endif /* __EK_SERVICE_H__ */
+