Interface: tos.interfaces.Packet

interface Packet

The basic message data type accessors. Protocols may use additional packet interfaces for their protocol specific data/metadata.

Author:
Philip Levis
Date:
January 5 2005
See:
TEP 116: Packet Protocols

Commands
command void clear(message_t *msg) Clear out this packet.
command void *getPayload(message_t *msg, uint8_t len) Return a pointer to a protocol's payload region in a packet.
command uint8_t maxPayloadLength() Return the maximum payload length that this communication layer can provide.
command uint8_t payloadLength(message_t *msg) Return the length of the payload of msg.
command void setPayloadLength(message_t *msg, uint8_t len) Set the length field of the packet.

Commands - Details

clear

command void clear(message_t *msg)

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.

Parameters:
'message_t* ONE msg' the packet to clear

getPayload

command void *getPayload(message_t *msg, uint8_t len)

Return a pointer to a protocol's payload region in a packet. If the caller intends to write to the payload region then the len parameter must reflect the maximum required length. If the caller (only) wants to read from the payload region, then len may be set to the value of payloadLength(). If the payload region is smaller than len this command returns NULL. The offset where the payload region starts within a packet is fixed, i.e. for a given msg this command will always return the same pointer or NULL.

Parameters:
'message_t* ONE msg' the packet
len - the length of payload required
Returns:
'void* COUNT_NOK(len)' a pointer to the packet's data payload for this layer or NULL if len is too big

maxPayloadLength

command uint8_t maxPayloadLength()

Return the maximum payload length that this communication layer can provide. Note that, depending on protocol fields, a given request to send a packet may not be able to send the maximum payload length (e.g., if there are variable length fields). Protocols may provide specialized interfaces for these circumstances.

Returns:
the maximum size payload allowed by this layer

payloadLength

command uint8_t payloadLength(message_t *msg)

Return the length of the payload of msg. This value may be less than what maxPayloadLength() returns, if the packet is smaller than the MTU. If a communication component does not support variably sized data regions, then payloadLength() will always return the same value as maxPayloadLength().

Parameters:
'message_t* ONE msg' the packet to examine
Returns:
the length of its current payload

setPayloadLength

command void setPayloadLength(message_t *msg, uint8_t len)

Set the length field of the packet. This value is not checked for validity (e.g., if it is larger than the maximum payload size). This command is not used when sending packets, as calls to send include a length parameter. Rather, it is used by components, such as queues, that need to buffer requests to send. This command allows the component to store the length specified in the request and later recover it when actually sending.

Parameters:
'message_t* ONE msg' the packet
len - the value to set its length field to