netwerk/base/public/nsICachingChannel.idl@b8a032363ba2 (annotated)
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
| michael@0 | 1 | /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ |
| michael@0 | 2 | /* This Source Code Form is subject to the terms of the Mozilla Public |
| michael@0 | 3 | * License, v. 2.0. If a copy of the MPL was not distributed with this |
| michael@0 | 4 | * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ |
| michael@0 | 5 | |
| michael@0 | 6 | #include "nsICacheInfoChannel.idl" |
| michael@0 | 7 | |
| michael@0 | 8 | interface nsIFile; |
| michael@0 | 9 | |
| michael@0 | 10 | /** |
| michael@0 | 11 | * A channel may optionally implement this interface to allow clients |
| michael@0 | 12 | * to affect its behavior with respect to how it uses the cache service. |
| michael@0 | 13 | * |
| michael@0 | 14 | * This interface provides: |
| michael@0 | 15 | * 1) Support for "stream as file" semantics (for JAR and plugins). |
| michael@0 | 16 | * 2) Support for "pinning" cached data in the cache (for printing and save-as). |
| michael@0 | 17 | * 3) Support for uniquely identifying cached data in cases when the URL |
| michael@0 | 18 | * is insufficient (e.g., HTTP form submission). |
| michael@0 | 19 | */ |
| michael@0 | 20 | [scriptable, uuid(a77b664e-e707-4017-9c03-47bcedcb5b05)] |
| michael@0 | 21 | interface nsICachingChannel : nsICacheInfoChannel |
| michael@0 | 22 | { |
| michael@0 | 23 | /** |
| michael@0 | 24 | * Set/get the cache token... uniquely identifies the data in the cache. |
| michael@0 | 25 | * Holding a reference to this token prevents the cached data from being |
| michael@0 | 26 | * removed. |
| michael@0 | 27 | * |
| michael@0 | 28 | * A cache token retrieved from a particular instance of nsICachingChannel |
| michael@0 | 29 | * could be set on another instance of nsICachingChannel provided the |
| michael@0 | 30 | * underlying implementations are compatible. The implementation of |
| michael@0 | 31 | * nsICachingChannel would be expected to only read from the cache entry |
| michael@0 | 32 | * identified by the cache token and not try to validate it. |
| michael@0 | 33 | * |
| michael@0 | 34 | * The cache token can be QI'd to a nsICacheEntryInfo if more detail |
| michael@0 | 35 | * about the cache entry is needed (e.g., expiration time). |
| michael@0 | 36 | */ |
| michael@0 | 37 | attribute nsISupports cacheToken; |
| michael@0 | 38 | |
| michael@0 | 39 | /** |
| michael@0 | 40 | * The same as above but accessing the offline app cache token if there |
| michael@0 | 41 | * is any. |
| michael@0 | 42 | * |
| michael@0 | 43 | * @throws |
| michael@0 | 44 | * NS_ERROR_NOT_AVAILABLE when there is not offline cache token |
| michael@0 | 45 | */ |
| michael@0 | 46 | attribute nsISupports offlineCacheToken; |
| michael@0 | 47 | |
| michael@0 | 48 | /** |
| michael@0 | 49 | * Set/get the cache key... uniquely identifies the data in the cache |
| michael@0 | 50 | * for this channel. Holding a reference to this key does NOT prevent |
| michael@0 | 51 | * the cached data from being removed. |
| michael@0 | 52 | * |
| michael@0 | 53 | * A cache key retrieved from a particular instance of nsICachingChannel |
| michael@0 | 54 | * could be set on another instance of nsICachingChannel provided the |
| michael@0 | 55 | * underlying implementations are compatible and provided the new |
| michael@0 | 56 | * channel instance was created with the same URI. The implementation of |
| michael@0 | 57 | * nsICachingChannel would be expected to use the cache entry identified |
| michael@0 | 58 | * by the cache token. Depending on the value of nsIRequest::loadFlags, |
| michael@0 | 59 | * the cache entry may be validated, overwritten, or simply read. |
| michael@0 | 60 | * |
| michael@0 | 61 | * The cache key may be NULL indicating that the URI of the channel is |
| michael@0 | 62 | * sufficient to locate the same cache entry. Setting a NULL cache key |
| michael@0 | 63 | * is likewise valid. |
| michael@0 | 64 | */ |
| michael@0 | 65 | attribute nsISupports cacheKey; |
| michael@0 | 66 | |
| michael@0 | 67 | /** |
| michael@0 | 68 | * Set/get the cache domain... uniquely identifies the data in the cache |
| michael@0 | 69 | * for this channel. Holding a reference to this key does NOT prevent |
| michael@0 | 70 | * the cached data from being removed. |
| michael@0 | 71 | */ |
| michael@0 | 72 | attribute AUTF8String cacheDomain; |
| michael@0 | 73 | |
| michael@0 | 74 | /************************************************************************** |
| michael@0 | 75 | * Caching channel specific load flags: |
| michael@0 | 76 | */ |
| michael@0 | 77 | |
| michael@0 | 78 | /** |
| michael@0 | 79 | * This load flag inhibits fetching from the net. An error of |
| michael@0 | 80 | * NS_ERROR_DOCUMENT_NOT_CACHED will be sent to the listener's |
| michael@0 | 81 | * onStopRequest if network IO is necessary to complete the request. |
| michael@0 | 82 | * |
| michael@0 | 83 | * This flag can be used to find out whether fetching this URL would |
| michael@0 | 84 | * cause validation of the cache entry via the network. |
| michael@0 | 85 | * |
| michael@0 | 86 | * Combining this flag with LOAD_BYPASS_LOCAL_CACHE will cause all |
| michael@0 | 87 | * loads to fail. This flag differs from LOAD_ONLY_FROM_CACHE in that |
| michael@0 | 88 | * this flag fails the load if validation is required while |
| michael@0 | 89 | * LOAD_ONLY_FROM_CACHE skips validation where possible. |
| michael@0 | 90 | */ |
| michael@0 | 91 | const unsigned long LOAD_NO_NETWORK_IO = 1 << 26; |
| michael@0 | 92 | |
| michael@0 | 93 | /** |
| michael@0 | 94 | * This load flag causes the offline cache to be checked when fetching |
| michael@0 | 95 | * a request. It will be set automatically if the browser is offline. |
| michael@0 | 96 | * |
| michael@0 | 97 | * This flag will not be transferred through a redirect. |
| michael@0 | 98 | */ |
| michael@0 | 99 | const unsigned long LOAD_CHECK_OFFLINE_CACHE = 1 << 27; |
| michael@0 | 100 | |
| michael@0 | 101 | /** |
| michael@0 | 102 | * This load flag causes the local cache to be skipped when fetching a |
| michael@0 | 103 | * request. Unlike LOAD_BYPASS_CACHE, it does not force an end-to-end load |
| michael@0 | 104 | * (i.e., it does not affect proxy caches). |
| michael@0 | 105 | */ |
| michael@0 | 106 | const unsigned long LOAD_BYPASS_LOCAL_CACHE = 1 << 28; |
| michael@0 | 107 | |
| michael@0 | 108 | /** |
| michael@0 | 109 | * This load flag causes the local cache to be skipped if the request |
| michael@0 | 110 | * would otherwise block waiting to access the cache. |
| michael@0 | 111 | */ |
| michael@0 | 112 | const unsigned long LOAD_BYPASS_LOCAL_CACHE_IF_BUSY = 1 << 29; |
| michael@0 | 113 | |
| michael@0 | 114 | /** |
| michael@0 | 115 | * This load flag inhibits fetching from the net if the data in the cache |
| michael@0 | 116 | * has been evicted. An error of NS_ERROR_DOCUMENT_NOT_CACHED will be sent |
| michael@0 | 117 | * to the listener's onStopRequest in this case. This flag is set |
| michael@0 | 118 | * automatically when the application is offline. |
| michael@0 | 119 | */ |
| michael@0 | 120 | const unsigned long LOAD_ONLY_FROM_CACHE = 1 << 30; |
| michael@0 | 121 | |
| michael@0 | 122 | /** |
| michael@0 | 123 | * This load flag controls what happens when a document would be loaded |
| michael@0 | 124 | * from the cache to satisfy a call to AsyncOpen. If this attribute is |
| michael@0 | 125 | * set to TRUE, then the document will not be loaded from the cache. A |
| michael@0 | 126 | * stream listener can check nsICachingChannel::isFromCache to determine |
| michael@0 | 127 | * if the AsyncOpen will actually result in data being streamed. |
| michael@0 | 128 | * |
| michael@0 | 129 | * If this flag has been set, and the request can be satisfied via the |
| michael@0 | 130 | * cache, then the OnDataAvailable events will be skipped. The listener |
| michael@0 | 131 | * will only see OnStartRequest followed by OnStopRequest. |
| michael@0 | 132 | */ |
| michael@0 | 133 | const unsigned long LOAD_ONLY_IF_MODIFIED = 1 << 31; |
| michael@0 | 134 | }; |
