netwerk/base/public/nsICachingChannel.idl@b8a032363ba2
netwerk/base/public/nsICachingChannel.idl
Thu, 22 Jan 2015 13:21:57 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Thu, 22 Jan 2015 13:21:57 +0100
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
- permissions
- -rw-r--r--
Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6
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/. */
6 #include "nsICacheInfoChannel.idl"
8 interface nsIFile;
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(a77b664e-e707-4017-9c03-47bcedcb5b05)]
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;
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;
48 /**
49 * Set/get the cache key... uniquely identifies the data in the cache
50 * for this channel. Holding a reference to this key does NOT prevent
51 * the cached data from being removed.
52 *
53 * A cache key retrieved from a particular instance of nsICachingChannel
54 * could be set on another instance of nsICachingChannel provided the
55 * underlying implementations are compatible and provided the new
56 * channel instance was created with the same URI. The implementation of
57 * nsICachingChannel would be expected to use the cache entry identified
58 * by the cache token. Depending on the value of nsIRequest::loadFlags,
59 * the cache entry may be validated, overwritten, or simply read.
60 *
61 * The cache key may be NULL indicating that the URI of the channel is
62 * sufficient to locate the same cache entry. Setting a NULL cache key
63 * is likewise valid.
64 */
65 attribute nsISupports cacheKey;
67 /**
68 * Set/get the cache domain... uniquely identifies the data in the cache
69 * for this channel. Holding a reference to this key does NOT prevent
70 * the cached data from being removed.
71 */
72 attribute AUTF8String cacheDomain;
74 /**************************************************************************
75 * Caching channel specific load flags:
76 */
78 /**
79 * This load flag inhibits fetching from the net. An error of
80 * NS_ERROR_DOCUMENT_NOT_CACHED will be sent to the listener's
81 * onStopRequest if network IO is necessary to complete the request.
82 *
83 * This flag can be used to find out whether fetching this URL would
84 * cause validation of the cache entry via the network.
85 *
86 * Combining this flag with LOAD_BYPASS_LOCAL_CACHE will cause all
87 * loads to fail. This flag differs from LOAD_ONLY_FROM_CACHE in that
88 * this flag fails the load if validation is required while
89 * LOAD_ONLY_FROM_CACHE skips validation where possible.
90 */
91 const unsigned long LOAD_NO_NETWORK_IO = 1 << 26;
93 /**
94 * This load flag causes the offline cache to be checked when fetching
95 * a request. It will be set automatically if the browser is offline.
96 *
97 * This flag will not be transferred through a redirect.
98 */
99 const unsigned long LOAD_CHECK_OFFLINE_CACHE = 1 << 27;
101 /**
102 * This load flag causes the local cache to be skipped when fetching a
103 * request. Unlike LOAD_BYPASS_CACHE, it does not force an end-to-end load
104 * (i.e., it does not affect proxy caches).
105 */
106 const unsigned long LOAD_BYPASS_LOCAL_CACHE = 1 << 28;
108 /**
109 * This load flag causes the local cache to be skipped if the request
110 * would otherwise block waiting to access the cache.
111 */
112 const unsigned long LOAD_BYPASS_LOCAL_CACHE_IF_BUSY = 1 << 29;
114 /**
115 * This load flag inhibits fetching from the net if the data in the cache
116 * has been evicted. An error of NS_ERROR_DOCUMENT_NOT_CACHED will be sent
117 * to the listener's onStopRequest in this case. This flag is set
118 * automatically when the application is offline.
119 */
120 const unsigned long LOAD_ONLY_FROM_CACHE = 1 << 30;
122 /**
123 * This load flag controls what happens when a document would be loaded
124 * from the cache to satisfy a call to AsyncOpen. If this attribute is
125 * set to TRUE, then the document will not be loaded from the cache. A
126 * stream listener can check nsICachingChannel::isFromCache to determine
127 * if the AsyncOpen will actually result in data being streamed.
128 *
129 * If this flag has been set, and the request can be satisfied via the
130 * cache, then the OnDataAvailable events will be skipped. The listener
131 * will only see OnStartRequest followed by OnStopRequest.
132 */
133 const unsigned long LOAD_ONLY_IF_MODIFIED = 1 << 31;
134 };
