*/
command uint8_t maxPayloadLength();
+
/**
- * Return a pointer to a protocol's payload region in a packet. If
- * len is not NULL, getPayload will return the length of the payload
- * in it, which is the same as the return value from
- * payloadLength(). If a protocol does not support variable length
- * packets, then *len is equal to 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 pointer to where the current payload length should be stored.
+ * @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);
+ command void* getPayload(message_t* msg, uint8_t len);
}