Interface: tos.interfaces.ReadStream

interface ReadStream<typedef val_t>

The ReadStream interface is intended for buffered high data rate reading, usually from sensor devices. The type of the values being read is given as a template argument.

To use this interface, allocate one or more buffers in your own space. Then, call postBuffer to pass these buffers into the device. Call read() to begin the sampling process. The buffers will be filled in the order originally posted, and a bufferDone() event will be signaled once each buffer has been filled with data. At any time while the read() is running, you may post new buffers to be filled. If the lower layer finishes signaling readDone() and then finds that no more buffers have been posted, it will consider the read to be finished, and signal readDone().

See TEP114 - SIDs: Source and Sink Independent Drivers for details.

Parameters:: val_t - the type of the object that will be returned
Author:: Gilman Tolle <gtolle@archrock.com>
Version:: $Revision: 1.5 $ $Date: 2008/06/04 03:00:31 $

Commands

command error_t postBuffer(val_t *buf, uint16_t count) Passes a buffer to the device, and indicates how many values should be placed into the buffer.

command error_t read(uint32_t usPeriod) Directs the device to start filling buffers by sampling with the specified period.

Events

event void bufferDone(error_t result, val_t *buf, uint16_t count) Signalled when a previously posted buffer has been filled by the device.

event void readDone(error_t result, uint32_t usActualPeriod) Signalled when a buffer has been filled but no more buffers have been posted.

Commands - Details

postBuffer

command error_t postBuffer(val_t *buf, uint16_t count)

Passes a buffer to the device, and indicates how many values should be placed into the buffer. Make sure your count doesn't overrun the buffer.

Parameters:: 'val_t* COUNT(count) buf' a pointer to the buffer; count - the number of values the buffer should hold
Returns:: SUCCESS if the post was successful

read

command error_t read(uint32_t usPeriod)

Directs the device to start filling buffers by sampling with the specified period.

Parameters:: usPeriod - the between-sample period in microseconds
Returns:: SUCCESS if the reading process began

Events - Details

bufferDone

event void bufferDone(error_t result, val_t *buf, uint16_t count)

Signalled when a previously posted buffer has been filled by the device. In the event of a read error, result will not equal SUCCESS, and the buffer will be filled with zeroes.

Parameters:: result - SUCCESS if the buffer was filled without errors; 'val_t* COUNT(count) buf' a pointer to the buffer that has been filled; count - the number of values actually read

readDone

event void readDone(error_t result, uint32_t usActualPeriod)

Signalled when a buffer has been filled but no more buffers have been posted. In the event of a read error, all previously posted buffers will have their bufferDone() event signalled, and then this event will be signalled with a non-SUCCESS argument.

Parameters:: result - SUCCESS if all buffers were filled without errors; usActualPeriod - Actual sampling period used - may be different from period requested at read time. Undefined if result != SUCCESS.