X-Git-Url: https://oss.titaniummirror.com/gitweb/?a=blobdiff_plain;f=tos%2Finterfaces%2FPacket.nc;h=179fe8fe8902816c696464736ac62975644a5642;hb=3fe8f13e05a2bcbc4a224f5a7b7f0ae45398a9b5;hp=2e61a5fb1b7cca08d1cbc04bd289c86805a79888;hpb=da0cfeda9689aa64cfce0aa209f51803dcb11c21;p=tinyos-2.x.git

diff --git a/tos/interfaces/Packet.nc b/tos/interfaces/Packet.nc
index 2e61a5fb..179fe8fe 100644
--- a/tos/interfaces/Packet.nc
+++ b/tos/interfaces/Packet.nc
@@ -1,5 +1,5 @@
 // $Id$
-/*									tab:4
+/*
  * "Copyright (c) 2004-5 The Regents of the University  of California.  
  * All rights reserved.
  *
@@ -48,7 +48,7 @@ interface Packet {
     * Clear out this packet.  Note that this is a deep operation and
     * total operation: calling clear() on any layer will completely
     * clear the packet for reuse.
-    * @param  msg    the packet to clear
+    * @param  'message_t* ONE msg'    the packet to clear
     */
 
   command void clear(message_t* msg);
@@ -60,7 +60,7 @@ interface Packet {
     * sized data regions, then payloadLength() will always return
     * the same value as maxPayloadLength(). 
     *
-    * @param  msg    the packet to examine
+    * @param  'message_t* ONE msg'    the packet to examine
     * @return        the length of its current payload
     */
 
@@ -76,7 +76,7 @@ interface Packet {
     * specified in the request and later recover it when actually
     * sending.
     *
-    * @param msg   the packet
+    * @param 'message_t* ONE msg'   the packet
     * @param len   the value to set its length field to
     */
 
@@ -94,14 +94,23 @@ interface Packet {
    */
   command uint8_t maxPayloadLength();
 
+
  /**
-   * Return a pointer to a protocol's payload region in a packet which
-   * at least a certain length.  If the payload region is smaller than
-   * the len parameter, then getPayload returns NULL.
+   * Return a pointer to a protocol's payload region in a packet.
+   * If the caller intends to write to the payload region then
+   * the <tt>len</tt> parameter must reflect the maximum required
+   * length. If the caller (only) wants to read from the payload
+   * region, then <tt>len</tt> may be set to the value of
+   * payloadLength(). If the payload region is smaller than 
+   * <tt>len</tt> this command returns NULL. The offset where
+   * the payload region starts within a packet is fixed, i.e. for
+   * a given <tt>msg</tt> this command will always return the same
+   * pointer or NULL.
    *
-   * @param msg   the packet
+   * @param 'message_t* ONE msg'   the packet 
    * @param len   the length of payload required
-   * @return      a pointer to the packet's data payload for this layer
+   * @return 'void* COUNT_NOK(len)'     a pointer to the packet's data payload for this layer
+   *              or NULL if <tt>len</tt> is too big
    */
   command void* getPayload(message_t* msg, uint8_t len);