Interface: QueryResultIntf

QueryResults are collections tuples or partially aggregated results, either produced locally or received over the network.

This interface defines routines to marshall / unmarshall them from tuples and byte arrays.

Note that QueryResults (or ResultTuples) should not be confused with Tuples (see TupleIntf) which are simple, fixed width packed arrays of attribute data collected from local fields. Tuples are used internally to collect data about sensors -- QueryResults are sent to neighboring motes and stored in result buffers for external processing.

ResultTuples can be used to get information about specified subtuples of a result. ResultTuple is defined in TinyDB.h. They are either aggregates (in which case the individual ResultTuples should be converted to QueryResults via fromResultTuple and passed to AggOperator for processing), or

Note that you must be careful with QueryResults, since they are sometimes initalized with pointers into the data structures that they are created from, such that overwriting their data can cause dangerous things to happen and the underlying pointers can become invalid when current tuples / buffers are reused. Situations in which references may be returned are noted carefully below (usually this is done for large results for which extra copies would incur a significant memory overhead).

Author:

Sam Madden

Components providing this interface:

tos.lib.TinyDB.QueryResult

Components requiring this interface:

tos.lib.TinyDB.AggOperator
tos.lib.TinyDB.DBBufferC
tos.lib.TinyDB.ParsedQuery
tos.lib.TinyDB.TupleRouterM

Commands

• TinyDBError initQueryResult (QueryResultPtr qr) Reset / initialize the specified query result so that it contains no data (does NOT deallocate memory associated with prior data stored in the result

• TinyDBError fromTuple (QueryResultPtr qr, ParsedQueryPtr q, TuplePtr t) Create a QueryResult from a TuplePtr.

• TinyDBError toTuplePtr (QueryResultPtr qr, ParsedQueryPtr q, TupleHandle t) Create a Tuple from q QueryResult.

• uint16_t resultSize(QueryResultPtr qr, ParsedQueryPtr q)

  Returns:

  the size (in bytes) requiired to marshall the specified query result for the spceified query

• TinyDBError toBytes (QueryResultPtr qr, ParsedQueryPtr q, CharPtr bytes) Marshall the specified query result into a byte array.

• TinyDBError fromBytes(CharPtr bytes, QueryResultPtr qr, ParsedQueryPtr q, uint8_t start) Convert a set of bytes into a query result

  Parameters:

  bytes - The byte array containing the bytes to convert qr - The QueryResult to create (WARNING: may contain pointers into bytes!) q - The ParsedQuery that corresponds to the bytes / qr start - The offset of the first byte of the query result in bytes

• TinyDBError fromMsgBytes(CharPtr bytes, QueryResultPtr qr, ParsedQueryPtr q) Convert a set of bytes from a network message into a query result (pull the header off the byte array and use fromBytes to parse.

• TinyDBError fromResultTuple(ResultTuple r, QueryResultPtr qr, ParsedQueryPtr pq) Create a QueryResult from a ResultTuple

• short queryIdFromMsg(CharPtr bytes) Return the queryId corresponding to the specified QueryResult network message

• short numRecords(QueryResultPtr qr, ParsedQueryPtr q)

  Returns:

  The number of fields in this result

• ResultTuple getResultTuple (QueryResultPtr qr, short i, ParsedQueryPtr q)

• TinyDBError addAggResult(QueryResultPtr qr, int16_t groupNo, char *bytes, int16_t size, ParsedQueryPtr q, short exprIdx) Add an agggreate result for the specified query for the specified expression If this query result has already been initialized from a tuple, returns err_AlreadyTupleResult If this query result contains results for a different query id, return err_InvalidQueryId

initQueryResult

fromTuple

toTuplePtr

toBytes

getResultTuple