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