timesyncamsend.nc

来自「tinyos-2.x.rar」· NC 代码 · 共 105 行

/*
 * Copyright (c) 2007, Vanderbilt University
 * All rights reserved.
 *
 * Permission to use, copy, modify, and distribute this software and its
 * documentation for any purpose, without fee, and without written agreement is
 * hereby granted, provided that the above copyright notice, the following
 * two paragraphs and the author appear in all copies of this software.
 *
 * IN NO EVENT SHALL THE VANDERBILT UNIVERSITY BE LIABLE TO ANY PARTY FOR
 * DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT
 * OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE VANDERBILT
 * UNIVERSITY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * THE VANDERBILT UNIVERSITY SPECIFICALLY DISCLAIMS ANY WARRANTIES,
 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
 * AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
 * ON AN "AS IS" BASIS, AND THE VANDERBILT UNIVERSITY HAS NO OBLIGATION TO
 * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
 */

/**
  * @author Philip Levis
  * @author Miklos Maroti
  *
  * @see TimeSyncPacket
  */

#include <TinyError.h>
#include <message.h>
#include <AM.h>

interface TimeSyncAMSend<precision_tag, size_type>
{
	/**
	* This command sends a regular message just like <tt>AMSend.send</tt>, but
	* it also performs sender-receiver time synchronization. The <tt>event_time</tt>
	* parameter holds the time of some event as expressed in the local clock of
	* the sender. The receiver can obtain the time of this event (expressed in its
	* own local time) via the <tt>TimeSyncPacket</tt> interface.
	*
	* @param addr         address to which to send the packet
	* @param msg          the packet
	* @param len          the length of the data in the packet payload
	* @param event_time	  the synchronization point to be transfered with the message
	* @return             SUCCESS if the request to send succeeded and a
	*                     sendDone will be signaled later, EBUSY if the
	*                     abstraction cannot send now but will be able to
	*                     later, or FAIL if the communication layer is not
	*                     in a state that can send (e.g., off).
  * @see sendDone
	*/
  command error_t send(am_addr_t addr, message_t* msg, uint8_t len, size_type event_time);

	/**
	* Cancel a requested transmission. Returns SUCCESS if the
	* transmission was canceled properly (not sent in its
	* entirety). Note that the component may not know
	* if the send was successfully canceled, if the radio is
	* handling much of the logic; in this case, a component
	* should be conservative and return an appropriate error code.
	* A successful call to cancel must always result in a
	* sendFailed event, and never a sendSucceeded event.
	*
	* @param  msg     the packet whose transmission should be cancelled.
	* @return SUCCESS if the transmission was cancelled, FAIL otherwise.
	* @see    sendDone
	*/
	command error_t cancel(message_t* msg);

	/**
	* Signaled in response to an accepted send request. <tt>msg</tt> is
	* the message buffer sent, and <tt>error</tt> indicates whether
	* the send was successful.
	*
	* @param  msg   the packet which was submitted as a send request
	* @param  error SUCCESS if it was sent successfully, FAIL if it was not,
	*               ECANCEL if it was cancelled
	* @see send
	* @see cancel
	*/
	event void sendDone(message_t* msg, error_t error);

	/**
	* Return the maximum payload length that this communication layer
	* can provide. This command behaves identically to
	* <tt>Packet.maxPayloadLength</tt> and is included in this
	* interface as a convenience.
	*
	* @return the maximum payload length
	*/
	command uint8_t maxPayloadLength();

	/**
	* Return a pointer to a protocol's payload region in a packet.
	* This command behaves identically to <tt>Packet.getPayload</tt>
	* (minus the length parameter) and is included in this interface
	* as a convenience.
	*
	* @param  msg    the packet
	* @return        the payload of the packet
	*/
	command void* getPayload(message_t* msg, uint8_t len);
}