From e5533d4cc5eb80845d8e58456a03d2188abda869 Mon Sep 17 00:00:00 2001
From: janhauer <janhauer>
Date: Wed, 5 Dec 2007 09:45:25 +0000
Subject: [PATCH] Updated the description of Packet.getPayload() as discussed
 during last core telconf: Added a sentence saying that for a given packet the
 command always returns the same pointer or NULL (no variable-sized headers).
 In addition, I tried to better describe how to use the "len" parameter in
 Packet.getPayload(), because I felt that was not becoming clear from the
 previous description.

---
 tos/interfaces/Packet.nc | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/tos/interfaces/Packet.nc b/tos/interfaces/Packet.nc
index 2e61a5fb..47b0c626 100644
--- a/tos/interfaces/Packet.nc
+++ b/tos/interfaces/Packet.nc
@@ -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 msg   the packet 
    * @param len   the length of payload required
    * @return      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);
 
-- 
2.39.2