move tep 132/133 interfaces to tos/interfaces

[tinyos-2.x.git] / tos / interfaces / TimeSyncAMSend.nc

diff --git a/tos/interfaces/TimeSyncAMSend.nc b/tos/interfaces/TimeSyncAMSend.nc
new file mode 100644 (file)
index 0000000..eb86277
--- /dev/null
+++ b/tos/interfaces/TimeSyncAMSend.nc
@@ -0,0 +1,104 @@
+/*
+ * 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);
+}