contiki/ek/ek-service.h - contiki-1.x - Gitiles

 /*
  * 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__ */
	/*
	* 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__ */