contiki/ek/ek-service.h

/*
 * Copyright (c) 2004, Swedish Institute of Computer Science.
 * All rights reserved. 
 *
 * Redistribution and use in source and binary forms, with or without 
 * modification, are permitted provided that the following conditions 
 * are met: 
 * 1. Redistributions of source code must retain the above copyright 
 *    notice, this list of conditions and the following disclaimer. 
 * 2. Redistributions in binary form must reproduce the above copyright 
 *    notice, this list of conditions and the following disclaimer in the 
 *    documentation and/or other materials provided with the distribution. 
 * 3. Neither the name of the Institute nor the names of its contributors 
 *    may be used to endorse or promote products derived from this software 
 *    without specific prior written permission. 
 *
 * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND 
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 
 * ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE 
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 
 * SUCH DAMAGE. 
 *
 * This file is part of the Contiki operating system.
 * 
 * Author: Adam Dunkels <adam@sics.se>
 *
 * $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__

#include "ek.h"

struct ek_service {
  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__ */