[Tinyos-devel] Interface change proposals for 2.1

[J. Ryan Stinnett]

David Gay wrote:
> On 8/11/07, J. Ryan Stinnett <jryans at rice.edu> wrote:
>> Philip Levis wrote:
>>> PROPOSED SOLUTION: The getPayload call will change from
>>>
>>>   command void* getPayload(message_t* msg, uint8_t* len);
>>>
>>> to
>>>
>>>   command void* getPayload(message_t* msg, uint8_t minLen);
>>>
>>> such that the caller tells the callee the size it requires. If the
>>> callee cannot provide a payload of that size, then it returns NULL. (The
>>> memory checking tools handle null pointers, so you don't smash your
>>> control registers.)
>> I'm not quite sure I understand how the minLen parameter would be used
>> in practice.  In a sending context, I suppose you'd always know what
>> length you are sending and can use that as minLen, though the Send
>> interface has its own getPayload which doesn't currently require a
>> length parameter.  In a receiving context, you could be dealing with
>> data of arbitrary size, in which case you could also pass 0 for minLen,
>> though that would seem to defeat the purpose of such a thing.  It seems
>> you would just want to get at whatever data there is and don't "require"
>> anything.  It makes a bit more sense with static data sizes.  Overall,
>> I'm not sure I understand the intended use of the parameter.
> 
> The getPayload in Send would acquire the minLen parameter too. Usage
> looks something like:
> 
> - when sending a payload of known size N: call getPayload(..., N)
> 
> - when sending a variable-sized payload: call maxPayloadLength() to
> get the maximum length M, then call getPayload(..., M) to get the
> payload
> 
> - when receiving a packet: in the receive event you already have the
> payload, so nothing new
> 
> - when reading a received packet later:
>   call getPayload(msg, N) for known-size payloads
>   call getPayload(msg, call payloadLength(msg)) for variable-sized payloads
> 
> Note that all commands called getPayload now behave the same way...
> 
> David
> 

Thanks for the clarification.  It seems like a reasonable change to me.

- Ryan