netwerk/base/nsICachingChannel.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsICacheInfoChannel.idl"
   7
   8 interface nsIFile;
   9
  10 /**
  11  * A channel may optionally implement this interface to allow clients
  12  * to affect its behavior with respect to how it uses the cache service.
  13  *
  14  * This interface provides:
  15  *   1) Support for "stream as file" semantics (for JAR and plugins).
  16  *   2) Support for "pinning" cached data in the cache (for printing and save-as).
  17  *   3) Support for uniquely identifying cached data in cases when the URL
  18  *      is insufficient (e.g., HTTP form submission).
  19  */
  20 [scriptable, uuid(dd1d6122-5ecf-4fe4-8f0f-995e7ab3121a)]
  21 interface nsICachingChannel : nsICacheInfoChannel
  22 {
  23     /**
  24      * Set/get the cache token... uniquely identifies the data in the cache.
  25      * Holding a reference to this token prevents the cached data from being
  26      * removed.
  27      *
  28      * A cache token retrieved from a particular instance of nsICachingChannel
  29      * could be set on another instance of nsICachingChannel provided the
  30      * underlying implementations are compatible.  The implementation of
  31      * nsICachingChannel would be expected to only read from the cache entry
  32      * identified by the cache token and not try to validate it.
  33      *
  34      * The cache token can be QI'd to a nsICacheEntryInfo if more detail
  35      * about the cache entry is needed (e.g., expiration time).
  36      */
  37     attribute nsISupports cacheToken;
  38
  39     /**
  40      * The same as above but accessing the offline app cache token if there
  41      * is any.
  42      *
  43      * @throws
  44      *      NS_ERROR_NOT_AVAILABLE when there is not offline cache token
  45      */
  46     attribute nsISupports offlineCacheToken;
  47
  48     /**
  49      * Instructs the channel to only store the metadata of the entry, and not
  50      * the content. When reading an existing entry, this automatically sets
  51      * LOAD_ONLY_IF_MODIFIED flag.
  52      * Must be called before asyncOpen().
  53      */
  54     attribute boolean cacheOnlyMetadata;
  55
  56     /**
  57      * Tells the channel to use the pinning storage.
  58      */
  59     attribute boolean pin;
  60
  61     /**
  62      * Overrides cache validation for a time specified in seconds.
  63      *
  64      * @param aSecondsToTheFuture
  65      *
  66      */
  67     void forceCacheEntryValidFor(in unsigned long aSecondsToTheFuture);
  68
  69     /**************************************************************************
  70      * Caching channel specific load flags:
  71      */
  72
  73     /**
  74      * This load flag inhibits fetching from the net.  An error of
  75      * NS_ERROR_DOCUMENT_NOT_CACHED will be sent to the listener's
  76      * onStopRequest if network IO is necessary to complete the request.
  77      *
  78      * This flag can be used to find out whether fetching this URL would
  79      * cause validation of the cache entry via the network.
  80      *
  81      * Combining this flag with LOAD_BYPASS_LOCAL_CACHE will cause all
  82      * loads to fail. This flag differs from LOAD_ONLY_FROM_CACHE in that
  83      * this flag fails the load if validation is required while
  84      * LOAD_ONLY_FROM_CACHE skips validation where possible.
  85      */
  86     const unsigned long LOAD_NO_NETWORK_IO = 1 << 26;
  87
  88     /**
  89      * This load flag causes the offline cache to be checked when fetching
  90      * a request.  It will be set automatically if the browser is offline.
  91      *
  92      * This flag will not be transferred through a redirect.
  93      */
  94     const unsigned long LOAD_CHECK_OFFLINE_CACHE = 1 << 27;
  95
  96     /**
  97      * This load flag causes the local cache to be skipped when fetching a
  98      * request.  Unlike LOAD_BYPASS_CACHE, it does not force an end-to-end load
  99      * (i.e., it does not affect proxy caches).
 100      */
 101     const unsigned long LOAD_BYPASS_LOCAL_CACHE = 1 << 28;
 102
 103     /**
 104      * This load flag causes the local cache to be skipped if the request
 105      * would otherwise block waiting to access the cache.
 106      */
 107     const unsigned long LOAD_BYPASS_LOCAL_CACHE_IF_BUSY = 1 << 29;
 108
 109     /**
 110      * This load flag inhibits fetching from the net if the data in the cache
 111      * has been evicted.  An error of NS_ERROR_DOCUMENT_NOT_CACHED will be sent
 112      * to the listener's onStopRequest in this case.  This flag is set
 113      * automatically when the application is offline.
 114      */
 115     const unsigned long LOAD_ONLY_FROM_CACHE = 1 << 30;
 116
 117     /**
 118      * This load flag controls what happens when a document would be loaded
 119      * from the cache to satisfy a call to AsyncOpen.  If this attribute is
 120      * set to TRUE, then the document will not be loaded from the cache.  A
 121      * stream listener can check nsICachingChannel::isFromCache to determine
 122      * if the AsyncOpen will actually result in data being streamed.
 123      *
 124      * If this flag has been set, and the request can be satisfied via the
 125      * cache, then the OnDataAvailable events will be skipped.  The listener
 126      * will only see OnStartRequest followed by OnStopRequest.
 127      */
 128     const unsigned long LOAD_ONLY_IF_MODIFIED = 1 << 31;
 129 };