netwerk/cache2/nsICacheEntryOpenCallback.idl

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this
   3  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 #include "nsISupports.idl"
   6
   7 interface nsICacheEntry;
   8
   9 [scriptable, uuid(1fc9fe11-c6ac-4748-94bd-8555a5a12b94)]
  10 interface nsICacheEntryOpenCallback : nsISupports
  11 {
  12   /**
  13    * State of the entry determined by onCacheEntryCheck.
  14    *
  15    * ENTRY_WANTED - the consumer is interested in the entry, we will pass it.
  16    * RECHECK_AFTER_WRITE_FINISHED - the consumer cannot use the entry while data is
  17    *    still being written and wants to check it again after the current write is
  18    *    finished. This actually prevents concurrent read/write and is used with
  19    *    non-resumable HTTP responses.
  20    * ENTRY_NEEDS_REVALIDATION - entry needs to be revalidated first with origin server,
  21    *    this means the loading channel will decide whether to use the entry content
  22    *    as is after it gets a positive response from the server about validity of the
  23    *    content ; when a new content needs to be loaded from the server, the loading
  24    *    channel opens a new entry with OPEN_TRUNCATE flag which dooms the one
  25    *    this check has been made for.
  26    * ENTRY_NOT_WANTED - the consumer is not interested in the entry, we will not pass it.
  27    */
  28   const unsigned long ENTRY_WANTED = 0;
  29   const unsigned long RECHECK_AFTER_WRITE_FINISHED = 1;
  30   const unsigned long ENTRY_NEEDS_REVALIDATION = 2;
  31   const unsigned long ENTRY_NOT_WANTED = 3;
  32
  33   /**
  34    * Callback to perform any validity checks before the entry should be used.
  35    * Called before onCacheEntryAvailable callback, depending on the result it
  36    * may be called more then one time.
  37    *
  38    * This callback is ensured to be called on the same thread on which asyncOpenURI
  39    * has been called, unless nsICacheStorage.CHECK_MULTITHREADED flag has been specified.
  40    * In that case this callback can be invoked on any thread, usually it is the cache I/O
  41    * or cache management thread.
  42    *
  43    * IMPORTANT NOTE:
  44    * This callback may be invoked sooner then respective asyncOpenURI call exits.
  45    *
  46    * @param aEntry
  47    *    An entry to examine.  Consumer has a chance to decide whether the
  48    *    entry is valid or not.
  49    * @return
  50    *    State of the entry, see the constants just above.
  51    */
  52   unsigned long onCacheEntryCheck(in nsICacheEntry aEntry);
  53
  54   /**
  55    * Callback giving actual result of asyncOpenURI.  It may give consumer the cache
  56    * entry or a failure result when it's not possible to open it from some reason.
  57    * This callback is ensured to be called on the same thread on which asyncOpenURI
  58    * has been called.
  59    *
  60    * IMPORTANT NOTE:
  61    * This callback may be invoked sooner then respective asyncOpenURI call exits.
  62    *
  63    * @param aEntry
  64    *    The entry bound to the originally requested URI.
  65    * @param aNew
  66    *    Whether no data so far has been stored for this entry, i.e. reading
  67    *    it will just fail.  When aNew is true, a server request should be
  68    *    made and data stored to this new entry.
  69    * @param aResult
  70    *    Result of the request.  This may be a failure only when one of these
  71    *    issues occur:
  72    *    - the cache storage service could not be started due to some unexpected
  73    *      faulure
  74    *    - there is not enough disk space to create new entries
  75    */
  76   void onCacheEntryAvailable(in nsICacheEntry aEntry,
  77                              in boolean aNew,
  78                              in nsresult aResult);
  79 };