[Tinyos-devel] Interface change proposals for 2.1

[David Gay]

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