Interface: tos.interfaces.Send

interface Send

Author:
Phil Levis
David Gay Revision: $Revision: 1.11 $ Defines global error codes for error_t in TinyOS.

Commands
command error_t cancel(message_t *msg) Cancel a requested transmission.
command void *getPayload(message_t *msg, uint8_t len) Return a pointer to a protocol's payload region in a packet which at least a certain length.
command uint8_t maxPayloadLength() Return the maximum payload length that this communication layer can provide.
command error_t send(message_t *msg, uint8_t len) Send a packet with a data payload of len.

Events
event void sendDone(message_t *msg, error_t error) Signaled in response to an accepted send request.

Commands - Details

cancel

command error_t cancel(message_t *msg)

Cancel a requested transmission. Returns SUCCESS if the transmission was cancelled properly (not sent in its entirety). Note that the component may not know if the send was successfully cancelled, if the radio is handling much of the logic; in this case, a component should be conservative and return an appropriate error code.

Parameters:
'message_t* ONE msg' the packet whose transmission should be cancelled
Returns:
SUCCESS if the packet was successfully cancelled, FAIL otherwise

getPayload

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

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. This command behaves identicallt to Packet.getPayload and is included in this interface as a convenience.

Parameters:
'message_t* ONE msg' the packet
Returns:
'void* COUNT_NOK(len)' a pointer to the packet's payload

maxPayloadLength

command uint8_t maxPayloadLength()

Return the maximum payload length that this communication layer can provide. This command behaves identically to Packet.maxPayloadLength and is included in this interface as a convenience.

Returns:
the maximum payload length

send

command error_t send(message_t *msg, uint8_t len)

Send a packet with a data payload of len. To determine the maximum available size, use the Packet interface of the component providing Send. If send returns SUCCESS, then the component will signal the sendDone event in the future; if send returns an error, it will not signal sendDone. Note that a component may accept a send request which it later finds it cannot satisfy; in this case, it will signal sendDone with an appropriate error code.

Parameters:
'message_t* ONE msg' the packet to send
len - the length of the packet payload
Returns:
SUCCESS if the request was accepted and will issue a sendDone event, EBUSY if the component cannot accept the request now but will be able to later, FAIL if the stack is in a state that cannot accept requests (e.g., it's off).

Events - Details

sendDone

event void sendDone(message_t *msg, error_t error)

Signaled in response to an accepted send request. msg is the sent buffer, and error indicates whether the send was succesful, and if not, the cause of the failure.

Parameters:
'message_t* ONE msg' the message which was requested to send
error - SUCCESS if it was transmitted successfully, FAIL if it was not, ECANCEL if it was cancelled via cancel