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, builtinclass, 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      * Instructs the channel to only store the metadata of the entry, and not
  41      * the content. When reading an existing entry, this automatically sets
  42      * LOAD_ONLY_IF_MODIFIED flag.
  43      * Must be called before asyncOpen().
  44      */
  45     attribute boolean cacheOnlyMetadata;
  46
  47     /**
  48      * Tells the channel to use the pinning storage.
  49      */
  50     attribute boolean pin;
  51
  52     /**
  53      * Overrides cache validation for a time specified in seconds.
  54      *
  55      * @param aSecondsToTheFuture
  56      *
  57      */
  58     void forceCacheEntryValidFor(in unsigned long aSecondsToTheFuture);
  59
  60     /**************************************************************************
  61      * Caching channel specific load flags:
  62      */
  63
  64     /**
  65      * This load flag inhibits fetching from the net.  An error of
  66      * NS_ERROR_DOCUMENT_NOT_CACHED will be sent to the listener's
  67      * onStopRequest if network IO is necessary to complete the request.
  68      *
  69      * This flag can be used to find out whether fetching this URL would
  70      * cause validation of the cache entry via the network.
  71      *
  72      * Combining this flag with LOAD_BYPASS_LOCAL_CACHE will cause all
  73      * loads to fail.
  74      */
  75     const unsigned long LOAD_NO_NETWORK_IO = 1 << 26;
  76
  77     /**
  78      * This load flag causes the local cache to be skipped when fetching a
  79      * request.  Unlike LOAD_BYPASS_CACHE, it does not force an end-to-end load
  80      * (i.e., it does not affect proxy caches).
  81      */
  82     const unsigned long LOAD_BYPASS_LOCAL_CACHE = 1 << 28;
  83
  84     /**
  85      * This load flag causes the local cache to be skipped if the request
  86      * would otherwise block waiting to access the cache.
  87      */
  88     const unsigned long LOAD_BYPASS_LOCAL_CACHE_IF_BUSY = 1 << 29;
  89
  90     /**
  91      * This load flag inhibits fetching from the net if the data in the cache
  92      * has been evicted.  An error of NS_ERROR_DOCUMENT_NOT_CACHED will be sent
  93      * to the listener's onStopRequest in this case.  This flag is set
  94      * automatically when the application is offline.
  95      */
  96     const unsigned long LOAD_ONLY_FROM_CACHE = 1 << 30;
  97
  98     /**
  99      * This load flag controls what happens when a document would be loaded
 100      * from the cache to satisfy a call to AsyncOpen.  If this attribute is
 101      * set to TRUE, then the document will not be loaded from the cache.  A
 102      * stream listener can check nsICachingChannel::isFromCache to determine
 103      * if the AsyncOpen will actually result in data being streamed.
 104      *
 105      * If this flag has been set, and the request can be satisfied via the
 106      * cache, then the OnDataAvailable events will be skipped.  The listener
 107      * will only see OnStartRequest followed by OnStopRequest.
 108      */
 109     const unsigned long LOAD_ONLY_IF_MODIFIED = 1 << 31;
 110 };