[Tinyos-2-commits] CVS: tinyos-2.x/tos/interfaces Packet.nc, 1.5, 1.6

[Jan-Hinrich Hauer]

Update of /cvsroot/tinyos/tinyos-2.x/tos/interfaces
In directory sc8-pr-cvs10.sourceforge.net:/tmp/cvs-serv22318

Modified Files:
	Packet.nc 
Log Message:
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.


Index: Packet.nc
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/tos/interfaces/Packet.nc,v
retrieving revision 1.5
retrieving revision 1.6
diff -C2 -d -r1.5 -r1.6
*** Packet.nc	13 Sep 2007 23:10:17 -0000	1.5
--- Packet.nc	5 Dec 2007 09:45:25 -0000	1.6
***************
*** 95,106 ****
    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.
     *
!    * @param msg   the packet
     * @param len   the length of payload required
     * @return      a pointer to the packet's data payload for this layer
     */
    command void* getPayload(message_t* msg, uint8_t len);
--- 95,115 ----
    command uint8_t maxPayloadLength();
  
+ 
   /**
!    * 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 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);