1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/netwerk/base/public/nsICachingChannel.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,134 @@
1.4 +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsICacheInfoChannel.idl"
1.10 +
1.11 +interface nsIFile;
1.12 +
1.13 +/**
1.14 + * A channel may optionally implement this interface to allow clients
1.15 + * to affect its behavior with respect to how it uses the cache service.
1.16 + *
1.17 + * This interface provides:
1.18 + * 1) Support for "stream as file" semantics (for JAR and plugins).
1.19 + * 2) Support for "pinning" cached data in the cache (for printing and save-as).
1.20 + * 3) Support for uniquely identifying cached data in cases when the URL
1.21 + * is insufficient (e.g., HTTP form submission).
1.22 + */
1.23 +[scriptable, uuid(a77b664e-e707-4017-9c03-47bcedcb5b05)]
1.24 +interface nsICachingChannel : nsICacheInfoChannel
1.25 +{
1.26 + /**
1.27 + * Set/get the cache token... uniquely identifies the data in the cache.
1.28 + * Holding a reference to this token prevents the cached data from being
1.29 + * removed.
1.30 + *
1.31 + * A cache token retrieved from a particular instance of nsICachingChannel
1.32 + * could be set on another instance of nsICachingChannel provided the
1.33 + * underlying implementations are compatible. The implementation of
1.34 + * nsICachingChannel would be expected to only read from the cache entry
1.35 + * identified by the cache token and not try to validate it.
1.36 + *
1.37 + * The cache token can be QI'd to a nsICacheEntryInfo if more detail
1.38 + * about the cache entry is needed (e.g., expiration time).
1.39 + */
1.40 + attribute nsISupports cacheToken;
1.41 +
1.42 + /**
1.43 + * The same as above but accessing the offline app cache token if there
1.44 + * is any.
1.45 + *
1.46 + * @throws
1.47 + * NS_ERROR_NOT_AVAILABLE when there is not offline cache token
1.48 + */
1.49 + attribute nsISupports offlineCacheToken;
1.50 +
1.51 + /**
1.52 + * Set/get the cache key... uniquely identifies the data in the cache
1.53 + * for this channel. Holding a reference to this key does NOT prevent
1.54 + * the cached data from being removed.
1.55 + *
1.56 + * A cache key retrieved from a particular instance of nsICachingChannel
1.57 + * could be set on another instance of nsICachingChannel provided the
1.58 + * underlying implementations are compatible and provided the new
1.59 + * channel instance was created with the same URI. The implementation of
1.60 + * nsICachingChannel would be expected to use the cache entry identified
1.61 + * by the cache token. Depending on the value of nsIRequest::loadFlags,
1.62 + * the cache entry may be validated, overwritten, or simply read.
1.63 + *
1.64 + * The cache key may be NULL indicating that the URI of the channel is
1.65 + * sufficient to locate the same cache entry. Setting a NULL cache key
1.66 + * is likewise valid.
1.67 + */
1.68 + attribute nsISupports cacheKey;
1.69 +
1.70 + /**
1.71 + * Set/get the cache domain... uniquely identifies the data in the cache
1.72 + * for this channel. Holding a reference to this key does NOT prevent
1.73 + * the cached data from being removed.
1.74 + */
1.75 + attribute AUTF8String cacheDomain;
1.76 +
1.77 + /**************************************************************************
1.78 + * Caching channel specific load flags:
1.79 + */
1.80 +
1.81 + /**
1.82 + * This load flag inhibits fetching from the net. An error of
1.83 + * NS_ERROR_DOCUMENT_NOT_CACHED will be sent to the listener's
1.84 + * onStopRequest if network IO is necessary to complete the request.
1.85 + *
1.86 + * This flag can be used to find out whether fetching this URL would
1.87 + * cause validation of the cache entry via the network.
1.88 + *
1.89 + * Combining this flag with LOAD_BYPASS_LOCAL_CACHE will cause all
1.90 + * loads to fail. This flag differs from LOAD_ONLY_FROM_CACHE in that
1.91 + * this flag fails the load if validation is required while
1.92 + * LOAD_ONLY_FROM_CACHE skips validation where possible.
1.93 + */
1.94 + const unsigned long LOAD_NO_NETWORK_IO = 1 << 26;
1.95 +
1.96 + /**
1.97 + * This load flag causes the offline cache to be checked when fetching
1.98 + * a request. It will be set automatically if the browser is offline.
1.99 + *
1.100 + * This flag will not be transferred through a redirect.
1.101 + */
1.102 + const unsigned long LOAD_CHECK_OFFLINE_CACHE = 1 << 27;
1.103 +
1.104 + /**
1.105 + * This load flag causes the local cache to be skipped when fetching a
1.106 + * request. Unlike LOAD_BYPASS_CACHE, it does not force an end-to-end load
1.107 + * (i.e., it does not affect proxy caches).
1.108 + */
1.109 + const unsigned long LOAD_BYPASS_LOCAL_CACHE = 1 << 28;
1.110 +
1.111 + /**
1.112 + * This load flag causes the local cache to be skipped if the request
1.113 + * would otherwise block waiting to access the cache.
1.114 + */
1.115 + const unsigned long LOAD_BYPASS_LOCAL_CACHE_IF_BUSY = 1 << 29;
1.116 +
1.117 + /**
1.118 + * This load flag inhibits fetching from the net if the data in the cache
1.119 + * has been evicted. An error of NS_ERROR_DOCUMENT_NOT_CACHED will be sent
1.120 + * to the listener's onStopRequest in this case. This flag is set
1.121 + * automatically when the application is offline.
1.122 + */
1.123 + const unsigned long LOAD_ONLY_FROM_CACHE = 1 << 30;
1.124 +
1.125 + /**
1.126 + * This load flag controls what happens when a document would be loaded
1.127 + * from the cache to satisfy a call to AsyncOpen. If this attribute is
1.128 + * set to TRUE, then the document will not be loaded from the cache. A
1.129 + * stream listener can check nsICachingChannel::isFromCache to determine
1.130 + * if the AsyncOpen will actually result in data being streamed.
1.131 + *
1.132 + * If this flag has been set, and the request can be satisfied via the
1.133 + * cache, then the OnDataAvailable events will be skipped. The listener
1.134 + * will only see OnStartRequest followed by OnStopRequest.
1.135 + */
1.136 + const unsigned long LOAD_ONLY_IF_MODIFIED = 1 << 31;
1.137 +};
