queryresultintf.nc

用于传感器网络的节点操作系统 TinyOS 结构设计非常有意思

/*									tab:4
 *
 *
 * "Copyright (c) 2000-2002 The Regents of the University  of California.  
 * All rights reserved.
 *
 * Permission to use, copy, modify, and distribute this software and its
 * documentation for any purpose, without fee, and without written agreement is
 * hereby granted, provided that the above copyright notice, the following
 * two paragraphs and the author appear in all copies of this software.
 * 
 * IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR
 * DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT
 * OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
 * CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 * 
 * THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
 * AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
 * ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
 * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS."
 *
 */
/*									tab:4
 *  IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.  By
 *  downloading, copying, installing or using the software you agree to
 *  this license.  If you do not agree to this license, do not download,
 *  install, copy or use the software.
 *
 *  Intel Open Source License 
 *
 *  Copyright (c) 2002 Intel Corporation 
 *  All rights reserved. 
 *  Redistribution and use in source and binary forms, with or without
 *  modification, are permitted provided that the following conditions are
 *  met:
 * 
 *	Redistributions of source code must retain the above copyright
 *  notice, this list of conditions and the following disclaimer.
 *	Redistributions in binary form must reproduce the above copyright
 *  notice, this list of conditions and the following disclaimer in the
 *  documentation and/or other materials provided with the distribution.
 *      Neither the name of the Intel Corporation nor the names of its
 *  contributors may be used to endorse or promote products derived from
 *  this software without specific prior written permission.
 *  
 *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 *  ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
 *  PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE INTEL OR ITS
 *  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 *  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 *  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 *  PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 *  LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 *  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 *  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 * 
 * 
 */
/*
 * Authors:	Sam Madden
 *              Design by Sam Madden, Wei Hong, and Joe Hellerstein
 * Date last modified:  6/26/02
 *
 *
 */

includes TinyDB;

/** QueryResults are collections tuples or partially aggregated results, either produced locally or
   received over the network.
<p>
   This interface defines routines to marshall / unmarshall them from tuples and
   byte arrays.
<p>
    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. 
<p>
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 
<p>
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
*/
interface QueryResultIntf
{
    /** Reset / initialize the specified query result so that it contains no data
	(does NOT deallocate memory associated with prior data stored in the result
	@param qr The query result to initialize.
    */
    command TinyDBError initQueryResult(QueryResultPtr qr);

    /** Create a QueryResult from a TuplePtr.  Copies data from t (not just references!)
	@param qr The (initialized) QueryResult to fill in
	@param q The query that t belongs to
	@param t The tuple to write into the QueryResult

    */
    command TinyDBError fromTuple(QueryResultPtr qr, ParsedQueryPtr q, TuplePtr t);
    
    /** Create a Tuple from q QueryResult.  The returned tuple is a reference into the
	query result.  Should only be called if the type qr->qrType == kNOT_AGG.
      
	@param qr The QueryResult to build the tuple from
	@param q The query corresponding to the query result / tuple
	@param t (on return) The tuple containing the data from the query result
    */
    command TinyDBError toTuplePtr(QueryResultPtr qr, ParsedQueryPtr q, TupleHandle t);
    

    /** @return the size (in bytes) requiired to marshall the specified query result  for the spceified query */
    command uint16_t resultSize(QueryResultPtr qr, ParsedQueryPtr q);

    /** Marshall the specified query result into a byte array.  The byte array must be at least
	resultSize(...) bytes long.
	@param qr The QueryResult to marshall
	@param q The query corresponding to the query result
	@param bytes The byte array to write the result into.
	
    */
    command TinyDBError toBytes(QueryResultPtr qr, ParsedQueryPtr q, CharPtr bytes);
    
    /** Convert a set of bytes into a query result
	@param bytes The byte array containing the bytes to convert
	@param qr The QueryResult to create (WARNING: may contain pointers into bytes!)
	@param q The ParsedQuery that corresponds to the bytes / qr
	@param start The offset of the first byte of the query result in bytes
    */
    command TinyDBError fromBytes(CharPtr bytes, QueryResultPtr qr, ParsedQueryPtr q,uint8_t start);


    /** 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.
    */
    command TinyDBError fromMsgBytes(CharPtr bytes, QueryResultPtr qr, ParsedQueryPtr q);

    /** Create a QueryResult from a ResultTuple */
    command TinyDBError fromResultTuple(ResultTuple r, QueryResultPtr qr, ParsedQueryPtr pq);
    
    /** Return the queryId corresponding to the specified QueryResult network message */
    command short queryIdFromMsg(CharPtr bytes);


    /** @return The number of fields in this result */
    command short numRecords(QueryResultPtr qr, ParsedQueryPtr q);

    /** @return The specified sub result from this query result (will contain references into qr)
	@param i The result number to retrieve (0 .. numRecords) 
	@param q The query corresponding to this query result
    */
    command ResultTuple getResultTuple(QueryResultPtr qr, short i, ParsedQueryPtr q);

    /** 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
    */
    command TinyDBError addAggResult(QueryResultPtr qr, int16_t groupNo, char *bytes, int16_t size, ParsedQueryPtr q, short exprIdx);

    //note that we do not provide methods to automatically convert query results to / from network messages

}