Interface: TupleIntf

TupleIntf allows interactions with Tuples, which are base data fetched from the Attr interface and stored in a packed array of fixed width fields.

Note that Tuple's should not be confused with QueryResults (or QueryResultTuples) which represent more complicated, arbitrary sized data structures consisting of an arbitrary number of records. Tuples are used internally to collect data about sensors -- QueryResults are sent to neighboring motes and stored in result buffers for external processing.

Components providing this interface:: tos.lib.TinyDB.Tuple

Components requiring this interface:: tos.lib.TinyDB.AggOperator
tos.lib.TinyDB.DBBufferC
tos.lib.TinyDB.ParsedQuery
tos.lib.TinyDB.QueryResult
tos.lib.TinyDB.SelOperator
tos.lib.TinyDB.TupleRouterM

Commands

uint16_t tupleSize(ParsedQueryPtr q)

Returns: The size (in bytes) of Tuples corresponding to the specified query
uint16_t fieldSize(ParsedQueryPtr q, uint8_t fieldNo)

Returns: The size (in bytes) of the specified field of the specified query, or 0 if the field is null or out of range
result_t setField (ParsedQueryPtr q, TuplePtr t, uint8_t fieldIdx, CharPtr data) Set the speccified field in the specified tuple corresponding to the specified query to the specified data.
result_t setFieldNoQuery (TuplePtr t, uint8_t fieldIdx, uint8_t numFields, uint8_t sizes[], uint8_t types[], CharPtr data) Set the specified field in the specified tuple, using the provided size and type arrays to determine where to write the data.

CharPtr getFieldPtr(ParsedQueryPtr q, TuplePtr t, uint8_t fieldIdx) Return a pointer to the field data for the specified field of the specified query

Parameters:	q - The query that t belongs to t - The Tuple to get the field from fieldIdx - The idx of the field to retrieve
Returns:	A pointer to the requested field, or NULL if no such field exists (note that writing to this pointer will overwrite the tuple data!)

CharPtr getFieldPtrNoQuery (TuplePtr t, uint8_t fieldIdx, uint8_t numFields, uint8_t sizes[], uint8_t types[]) Return a pointer into the field data for the specified field, using the provided arrays of sizes and types to compute the appropriate offset.
result_t tupleInit(ParsedQueryPtr q, TuplePtr t) Set all the fields of the specified tuple to 0, and reset the bitmap that tracks which fields have been written
bool isTupleComplete(ParsedQueryPtr q, TuplePtr t)

Returns: TRUE iff all fields of the specified tuple have been set since it was last reset
AttrDescPtr getNextQueryField (ParsedQueryPtr q, TuplePtr t)
TinyDBError getNextEmptyFieldIdx(ParsedQueryPtr q, TuplePtr t, uint8_t *fieldIdx) Fetch the index of the next empty field in the tuple

Parameters:
(on - return) fieldIdx The index of the next empty field in the query

Returns: err_NoMoreResults if there are no more empty fields

Commands - Details

setField

result_t setField(ParsedQueryPtr q, TuplePtr t, uint8_t fieldIdx, CharPtr data)

Set the speccified field in the specified tuple corresponding to the specified query to the specified data.

Parameters:	q - The query that t belongs to t - The tuple whose field should be set fieldIdx - The field to set in t data - The data to write to t (fieldSize(...) bytes will be copied
Returns:	FAIL if the field is out of range or NULL, or SUCCESS otherwise

setFieldNoQuery

result_t setFieldNoQuery(TuplePtr t, uint8_t fieldIdx, uint8_t numFields, uint8_t sizes[], uint8_t types[], CharPtr data)

Set the specified field in the specified tuple, using the provided size and type arrays to determine where to write the data.

Parameters:	fieldIdx - The index of the field to set t - The tuple whose field is to be set numFields - The number of fields in the tuple sizes - The size of each field (in bytes); must be at least numFields long types - The types of each field (From SchemaType.h); must be at least numFields long data - The data to write into the field
Returns:	FAIL if the field is out or range or NULL, SUCCESS otherwise.

getFieldPtrNoQuery

CharPtr getFieldPtrNoQuery(TuplePtr t, uint8_t fieldIdx, uint8_t numFields, uint8_t sizes[], uint8_t types[])

Return a pointer into the field data for the specified field, using the provided arrays of sizes and types to compute the appropriate offset.

Parameters:	t - The tuple to get the field from fieldIdx - The index of the field to retrieve numFields - The total number of fields in the tuple sizes - The sizes (in bytes) of the fields in the tuple; this array must be at least numFields entries The - typs (from SchemaType.h) of the fields in the tuple; this array must be at least numFields entries
Returns:	A pointer to the requested field, or NULL if no such field exists (note that writing to this pointer will overwrite tuple data!)

getNextQueryField

AttrDescPtr getNextQueryField(ParsedQueryPtr q, TuplePtr t)

Returns:

An attribute descriptor for the next unset field in the specified tuple, or NULL if all fields are set.

Parameters:	(on - return) fieldIdx The index of the next empty field in the query
Returns:	err_NoMoreResults if there are no more empty fields