Fix the issue with tos-deluge not timing out properly.

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

diff --git a/tos/interfaces/AMPacket.nc b/tos/interfaces/AMPacket.nc
index 48c39b641c8176b99ec2ac1f15e0bc0115f53e37..af0d5fa12e83ceea3f1da601ee0e271cabbf8576 100644 (file)
--- a/tos/interfaces/AMPacket.nc
+++ b/tos/interfaces/AMPacket.nc
@@ -1,5 +1,5 @@
 // $Id$
-/*                                                                     tab:4
+/*
  * "Copyright (c) 2004-5 The Regents of the University  of California.  
  * All rights reserved.
  *
@@ -30,7 +30,11 @@
 
 /**
   * The Active Message accessors, which provide the AM local address and
-  * functionality for querying packets. Also see the Packet interface.
+  * functionality for querying packets. Active Messages are a single-hop
+  * communication protocol. Therefore, fields such as source and destination
+  * represent the single-hop source and destination. Multihop sources and
+  * destinations are defined by the corresponding multihop protocol (if any).
+  * Also see the Packet interface.
   *
   * @author Philip Levis 
   * @date   January 18 2005
@@ -53,15 +57,25 @@ interface AMPacket {
   command am_addr_t address();
 
   /**
-   * Return the AM address of the destination field of an AM packet.
+   * Return the AM address of the destination of the AM packet.
    * If <tt>amsg</tt> is not an AM packet, the results of this command
    * are undefined.
-   * @param amsg    the packet
+   * @param 'message_t* ONE amsg'    the packet
    * @return        the destination address of the packet.
    */
   
   command am_addr_t destination(message_t* amsg);
 
+  /**
+   * Return the AM address of the source of the AM packet.
+   * If <tt>amsg</tt> is not an AM packet, the results of this command
+   * are undefined.
+   * @param 'message_t* ONE amsg'  the packet
+   * @return      the source address of the packet.
+   */
+   
+  command am_addr_t source(message_t* amsg);
+  
   /**
    * Set the AM address of the destination field of the AM packet.  As
    * the AM address is set as part of sending with the AMSend
@@ -71,12 +85,30 @@ interface AMPacket {
    * and then recover it when actually sending. If <tt>amsg</tt> is
    * not an AM packet, the results of this command are undefined.
    *
-   * @param  amsg   the packet
+   * @param  'message_t* ONE amsg'   the packet
    * @param  addr   the address
    */
 
   command void setDestination(message_t* amsg, am_addr_t addr);
 
+  /**
+   * Set the AM address of the source field of the AM packet.  As
+   * the AM address is set as part of sending with the AMSend
+   * interface, this command is not used for sending packets.  Rather,
+   * it is used when a component, such as a queue, needs to buffer a
+   * request to send. The component can save the source address
+   * and then recover it when actually sending. As an AM layer generally
+   * sets the source address to be the local address, this interface
+   * is not commonly used except when a system is bypassing the AM
+   * layer (e.g., a protocol bridge). If <tt>amsg</tt> is
+   * not an AM packet, the results of this command are undefined.
+   *
+   * @param  'message_t* ONE amsg'   the packet
+   * @param  addr   the address
+   */
+
+  command void setSource(message_t* amsg, am_addr_t addr);
+
   /**
    * Return whether <tt>amsg</tt> is destined for this mote. This is
    * partially a shortcut for testing whether the return value of
@@ -87,7 +119,7 @@ interface AMPacket {
    * the mote's local address. If <tt>amsg</tt> is not an AM packet,
    * the results of this command are undefined.
    *
-   * @param  amsg   the packet
+   * @param  'message_t* ONE amsg'   the packet
    * @return        whether the packet is addressed to this AM stack
    */
   command bool isForMe(message_t* amsg);
@@ -97,7 +129,7 @@ interface AMPacket {
    * If <tt>amsg</tt> is not an AM packet, the results of this command
    * are undefined.
    *
-   * @param  amsg   the packet
+   * @param  'message_t* ONE amsg'   the packet
    * @return        the AM type
    */
   
@@ -112,10 +144,42 @@ interface AMPacket {
    * sending. If <tt>amsg</tt> is not an AM packet, the results of
    * this command are undefined.
    * 
-   * @param  amsg    the packet
+   * @param  'message_t* ONE amsg'    the packet
    * @param  t       the AM type
    */
   
   command void setType(message_t* amsg, am_id_t t);
 
+  /**
+   * Get the AM group of the AM packet. The AM group is a logical
+   * identifier that distinguishes sets of nodes which may share
+   * a physical communication medium but wish to not communicate.
+   * The AM group logically separates the sets of nodes. When
+   * a node sends a packet, it fills in its AM group, and typically
+   * nodes only receive packets whose AM group field matches their
+   * own.
+   *
+   * @param 'message_t* ONE amsg' the packet
+   * @return the AM group of this packet
+   */
+  
+  command am_group_t group(message_t* amsg);
+
+  /**
+   * Set the AM group field of a packet. Note that most data link
+   * stacks will set this field automatically on a send request, which
+   * may overwrite changes made with this command.
+   *
+   * @param 'message_t* ONE amsg' the packet
+   * @param group the packet's new AM group value
+   */
+  command void setGroup(message_t* amsg, am_group_t grp);
+
+  /**
+   * Provides the current AM group of this communication interface.
+   *
+   * @return The AM group.
+   */
+  
+  command am_group_t localGroup();
 }