delugemetadata.nc

来自「tinyos最新版」· NC 代码 · 共 163 行

// $Id: DelugeMetadata.nc,v 1.9 2004/08/18 18:53:16 jwhui Exp $

/*									tab:4
 *
 *
 * "Copyright (c) 2000-2004 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."
 *
 */

/**
 * Manages Deluge metadata.
 *
 * @author Jonathan Hui <[e-mail]>
 */

includes DelugeMetadata;

interface DelugeMetadata {

  /**
   * Check if metadata component is ready.
   *
   * @return  <code>TRUE</code> if the metadata component is ready;
   *          <code>FALSE</code> otherwise.
   */
  command bool isReady();

  /**
   * Returns the most recent version number whether or not the image
   * is completely downloaded.
   *
   * @return  The version number of the most recent image.
   */
  command imgvnum_t getVNum(uint8_t imgNum);

  /**
   * Returns the number of pages in the most recent image whether or
   * not the image is completely downloaded.
   *
   * @return  The number of pages in the most recent image
   */
  command pgnum_t getNumPgs(uint8_t imgNum);

  /**
   * Returns the number of pages complete in the most recent
   * image. Page <code>i</code> is considered complete if all of the
   * data for page <code>i</code> has been received and all pages
   * between <code>0</code> and <code>i</code>, inclusive, are also
   * complete.
   *
   * @return  the number of pages complete in the most recent image.
   */
  command pgnum_t getNumPgsComplete(uint8_t imgNum);

  command bool isValidTOSApp(uint8_t imgNum);

  /**
   * Check if a given list of Deluge summaries matches the list of
   * summaries within the metadata component.
   *
   * @param summaries  List of Deluge summaries to check against.
   * @return           <code>TRUE</code> if the summaries match;
   *                   <code>FAIL</code> otherwise.
   */
  command bool     isImgSummariesEqual(DelugeImgSummary* summaries);

  /**
   * Get the list of image Deluge summaries from the metadata
   * component.
   *
   * @param summaries  Deluge summary list to fill.
   * @return           <code>SUCCESS</code> if the request completes successfully;
   *                   <code>FAIL</code> otherwise.
   */
  command result_t getImgSummaries(DelugeImgSummary* summaries);

  /**
   * Upgrade metadata to match what is contained in the Deluge summary
   * list. Upgrades are done using the image version numbers.
   *
   * @param summaries  Deluge summary list to upgrade to.
   * @return           <code>SUCCESS</code> if the request completes successfully;
   *                   <code>FAIL</code> otherwise.
   */
  command result_t setImgSummaries(DelugeImgSummary* summaries);

  /**
   * Check if the list of summaries indicates the availability of
   * data.
   *
   * @param summaries  Deluge summary list to check against.
   * @return           <code>TRUE</code> if there is data available;
   *                   <code>FAIL</code> otherwise.
   */
  command bool     canProvideData(DelugeImgSummary* summaries);

  /**
   * Get the first incomplete image that should be requested.
   *
   * @return        <code>SUCCESS</code> if the request completes successfully;
   *                <code>FAIL</code> otherwise.
   */
  command uint8_t getNextIncompleteImage();

  /**
   * Get the first incomplete page that should be requested.
   *
   * @return        <code>SUCCESS</code> if the request completes successfully;
   *                <code>FAIL</code> otherwise.
   */
  command uint8_t getNextIncompletePage();

  /**
   * Update the metadata to reflect that a new page has been received.
   *
   * @return        <code>SUCCESS</code> if the update happened successfully;
   *                <code>FAIL</code> otherwise.
   */
  command result_t pgFlushed();

  /**
   * Notify that sync of changed metadata has completed.
   *
   * @param result  <code>SUCCESS</code> if the diff has been applied 
   *                successfully;
   *                <code>FAIL</code> otherwise.
   * @return        <code>SUCCESS</code> if the event is handled successfully;
   *                <code>FAIL</code> otherwise.
   */
  event result_t applyPageDiffDone(result_t result);

  /**
   * Notify that metadata has been read from stable store and is ready
   * to be used. Only occurs when node is starting up to restore
   * metadata in RAM.
   *
   * @param result  <code>SUCCESS</code> if the metadata has been read 
   *                successfully;
   *                <code>FAIL</code> otherwise.
   * @return        <code>SUCCESS</code> if the event is handled successfully;
   *                <code>FAIL</code> otherwise.
   */
  event result_t ready(result_t result);

}