michael@0: /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #include "nsICacheInfoChannel.idl"
michael@0: 
michael@0: interface nsIFile;
michael@0: 
michael@0: /**
michael@0:  * A channel may optionally implement this interface to allow clients
michael@0:  * to affect its behavior with respect to how it uses the cache service.
michael@0:  *
michael@0:  * This interface provides:
michael@0:  *   1) Support for "stream as file" semantics (for JAR and plugins).
michael@0:  *   2) Support for "pinning" cached data in the cache (for printing and save-as).
michael@0:  *   3) Support for uniquely identifying cached data in cases when the URL
michael@0:  *      is insufficient (e.g., HTTP form submission).
michael@0:  */
michael@0: [scriptable, uuid(a77b664e-e707-4017-9c03-47bcedcb5b05)]
michael@0: interface nsICachingChannel : nsICacheInfoChannel
michael@0: {
michael@0:     /**
michael@0:      * Set/get the cache token... uniquely identifies the data in the cache.
michael@0:      * Holding a reference to this token prevents the cached data from being
michael@0:      * removed.
michael@0:      * 
michael@0:      * A cache token retrieved from a particular instance of nsICachingChannel
michael@0:      * could be set on another instance of nsICachingChannel provided the
michael@0:      * underlying implementations are compatible.  The implementation of
michael@0:      * nsICachingChannel would be expected to only read from the cache entry
michael@0:      * identified by the cache token and not try to validate it.
michael@0:      *
michael@0:      * The cache token can be QI'd to a nsICacheEntryInfo if more detail
michael@0:      * about the cache entry is needed (e.g., expiration time).
michael@0:      */
michael@0:     attribute nsISupports cacheToken;
michael@0: 
michael@0:     /**
michael@0:      * The same as above but accessing the offline app cache token if there
michael@0:      * is any.
michael@0:      *
michael@0:      * @throws
michael@0:      *      NS_ERROR_NOT_AVAILABLE when there is not offline cache token
michael@0:      */
michael@0:     attribute nsISupports offlineCacheToken;
michael@0: 
michael@0:     /**
michael@0:      * Set/get the cache key... uniquely identifies the data in the cache
michael@0:      * for this channel.  Holding a reference to this key does NOT prevent
michael@0:      * the cached data from being removed.
michael@0:      * 
michael@0:      * A cache key retrieved from a particular instance of nsICachingChannel
michael@0:      * could be set on another instance of nsICachingChannel provided the
michael@0:      * underlying implementations are compatible and provided the new 
michael@0:      * channel instance was created with the same URI.  The implementation of
michael@0:      * nsICachingChannel would be expected to use the cache entry identified
michael@0:      * by the cache token.  Depending on the value of nsIRequest::loadFlags,
michael@0:      * the cache entry may be validated, overwritten, or simply read.
michael@0:      *
michael@0:      * The cache key may be NULL indicating that the URI of the channel is
michael@0:      * sufficient to locate the same cache entry.  Setting a NULL cache key
michael@0:      * is likewise valid.
michael@0:      */
michael@0:     attribute nsISupports cacheKey;
michael@0: 
michael@0:     /**
michael@0:      * Set/get the cache domain... uniquely identifies the data in the cache
michael@0:      * for this channel.  Holding a reference to this key does NOT prevent
michael@0:      * the cached data from being removed.
michael@0:      */
michael@0:     attribute AUTF8String cacheDomain;
michael@0: 
michael@0:     /**************************************************************************
michael@0:      * Caching channel specific load flags:
michael@0:      */
michael@0: 
michael@0:     /**
michael@0:      * This load flag inhibits fetching from the net.  An error of
michael@0:      * NS_ERROR_DOCUMENT_NOT_CACHED will be sent to the listener's
michael@0:      * onStopRequest if network IO is necessary to complete the request.
michael@0:      *
michael@0:      * This flag can be used to find out whether fetching this URL would
michael@0:      * cause validation of the cache entry via the network.
michael@0:      *
michael@0:      * Combining this flag with LOAD_BYPASS_LOCAL_CACHE will cause all
michael@0:      * loads to fail. This flag differs from LOAD_ONLY_FROM_CACHE in that
michael@0:      * this flag fails the load if validation is required while
michael@0:      * LOAD_ONLY_FROM_CACHE skips validation where possible.
michael@0:      */
michael@0:     const unsigned long LOAD_NO_NETWORK_IO = 1 << 26;
michael@0: 
michael@0:     /**
michael@0:      * This load flag causes the offline cache to be checked when fetching
michael@0:      * a request.  It will be set automatically if the browser is offline.
michael@0:      *
michael@0:      * This flag will not be transferred through a redirect.
michael@0:      */
michael@0:     const unsigned long LOAD_CHECK_OFFLINE_CACHE = 1 << 27;
michael@0: 
michael@0:     /**
michael@0:      * This load flag causes the local cache to be skipped when fetching a
michael@0:      * request.  Unlike LOAD_BYPASS_CACHE, it does not force an end-to-end load
michael@0:      * (i.e., it does not affect proxy caches).
michael@0:      */
michael@0:     const unsigned long LOAD_BYPASS_LOCAL_CACHE = 1 << 28;
michael@0: 
michael@0:     /**
michael@0:      * This load flag causes the local cache to be skipped if the request
michael@0:      * would otherwise block waiting to access the cache.
michael@0:      */
michael@0:     const unsigned long LOAD_BYPASS_LOCAL_CACHE_IF_BUSY = 1 << 29;
michael@0: 
michael@0:     /**
michael@0:      * This load flag inhibits fetching from the net if the data in the cache
michael@0:      * has been evicted.  An error of NS_ERROR_DOCUMENT_NOT_CACHED will be sent
michael@0:      * to the listener's onStopRequest in this case.  This flag is set
michael@0:      * automatically when the application is offline.
michael@0:      */
michael@0:     const unsigned long LOAD_ONLY_FROM_CACHE = 1 << 30;
michael@0: 
michael@0:     /**
michael@0:      * This load flag controls what happens when a document would be loaded
michael@0:      * from the cache to satisfy a call to AsyncOpen.  If this attribute is
michael@0:      * set to TRUE, then the document will not be loaded from the cache.  A
michael@0:      * stream listener can check nsICachingChannel::isFromCache to determine
michael@0:      * if the AsyncOpen will actually result in data being streamed.
michael@0:      *
michael@0:      * If this flag has been set, and the request can be satisfied via the
michael@0:      * cache, then the OnDataAvailable events will be skipped.  The listener
michael@0:      * will only see OnStartRequest followed by OnStopRequest.
michael@0:      */
michael@0:     const unsigned long LOAD_ONLY_IF_MODIFIED = 1 << 31;
michael@0: };