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