network.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.
 * 
 * 
 */
includes TinyDB;

/** The network interface provides TinyDB to trap and monitor network communication --
   TupleRouter could simply be wired directly to the appropriate AM send / handlers, but
   the network monitors topology and filters events in a semi-intelligent
   way.
	<p>
   Eventually, we'd like to abstract out the parts of this that are similar to Alec's
   fancy routing from the parts that are TinyDB magic (e.g. snooped messages) 
   from the parts that really are just wrappers around other components (e.g. setPot).
<p>
   Implemented by NetworkC.td.

@author Sam Madden ([e-mail])
*/

interface Network {
  /** Send out a message containing a tuple 
	@param msg The message to send
	@return err_MsgSendFailed if message failed to xmit 
  */
  command TinyDBError sendDataMessage(TOS_MsgPtr msg);

  /** Send out a message containing (part of) a query 
	@param msg The message to send
	@return err_MsgSendFailed if message failed to xmit
  */
  command TinyDBError sendQueryMessage(TOS_MsgPtr msg);

  /** Send out a message requesting a neighbor describe a query
	@param msg The message to send
	@return err_MsgSendFailed if message failed to xmit 
  */
  command TinyDBError sendQueryRequest(TOS_MsgPtr msg, uint16_t from);
    
  /* Send some data over the uart (for debugging purposes, perhaps)
     @param msg The message to send
     @param amid The AMID of the message to send
     @return err_MsgSendFailed if the message failed to transmit
  */
  command result_t sendUart(char *msg, uint8_t amid);
    
  /** Limit the possible parents each mote can select 
   @param fanout The branching factor of the topology tree
  */
  command result_t forceTopology(uint8_t fanout);

  /** Route all the data to the root (perform no in-network aggregation)
   @param on Whether data should be routed to the root 
  */
  command result_t setCentralized(bool on);


  /** Called whenever an epoch ends */
  command void endOfEpoch();


  /** Signalled when a message has been sent 
   @param msg The message that was sent
   @param amId the AMId of the message that was sent
  */
  event result_t outputDone(TOS_MsgPtr msg, uint8_t amId);
    
  /** Signalled when a data (tuple) message is received from a neighbor 
   @param The data message that was received*/
  event TOS_MsgPtr dataSub(TOS_MsgPtr msg);
    
  /** Signalled when a query message is received from a neighbor 
   @param msg The query message that was received 
  */
  event TOS_MsgPtr querySub(TOS_MsgPtr msg);
    
  /** Signalled when a message not directed to us is heard (snooped) 
   @param msg The message that was heard
   @param msgid The amid of the message
   @param parent If the message was sent by our parent
  */
  event TOS_MsgPtr snoopedSub(TOS_MsgPtr msg, uint8_t msgid, bool parent);

  /** Signalled when a neighbor mote requests a query from us 
     @param The message our neighbor sent
  */
  event TOS_MsgPtr queryRequestSub(TOS_MsgPtr msg);

}