nsICachingChannel.idl (4437B)
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/. */ 5 6 #include "nsICacheInfoChannel.idl" 7 8 interface nsIFile; 9 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, builtinclass, uuid(dd1d6122-5ecf-4fe4-8f0f-995e7ab3121a)] 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; 38 39 /** 40 * Instructs the channel to only store the metadata of the entry, and not 41 * the content. When reading an existing entry, this automatically sets 42 * LOAD_ONLY_IF_MODIFIED flag. 43 * Must be called before asyncOpen(). 44 */ 45 attribute boolean cacheOnlyMetadata; 46 47 /** 48 * Tells the channel to use the pinning storage. 49 */ 50 attribute boolean pin; 51 52 /** 53 * Overrides cache validation for a time specified in seconds. 54 * 55 * @param aSecondsToTheFuture 56 * 57 */ 58 void forceCacheEntryValidFor(in unsigned long aSecondsToTheFuture); 59 60 /************************************************************************** 61 * Caching channel specific load flags: 62 */ 63 64 /** 65 * This load flag inhibits fetching from the net. An error of 66 * NS_ERROR_DOCUMENT_NOT_CACHED will be sent to the listener's 67 * onStopRequest if network IO is necessary to complete the request. 68 * 69 * This flag can be used to find out whether fetching this URL would 70 * cause validation of the cache entry via the network. 71 * 72 * Combining this flag with LOAD_BYPASS_LOCAL_CACHE will cause all 73 * loads to fail. 74 */ 75 const unsigned long LOAD_NO_NETWORK_IO = 1 << 26; 76 77 /** 78 * This load flag causes the local cache to be skipped when fetching a 79 * request. Unlike LOAD_BYPASS_CACHE, it does not force an end-to-end load 80 * (i.e., it does not affect proxy caches). 81 */ 82 const unsigned long LOAD_BYPASS_LOCAL_CACHE = 1 << 28; 83 84 /** 85 * This load flag causes the local cache to be skipped if the request 86 * would otherwise block waiting to access the cache. 87 */ 88 const unsigned long LOAD_BYPASS_LOCAL_CACHE_IF_BUSY = 1 << 29; 89 90 /** 91 * This load flag inhibits fetching from the net if the data in the cache 92 * has been evicted. An error of NS_ERROR_DOCUMENT_NOT_CACHED will be sent 93 * to the listener's onStopRequest in this case. This flag is set 94 * automatically when the application is offline. 95 */ 96 const unsigned long LOAD_ONLY_FROM_CACHE = 1 << 30; 97 98 /** 99 * This load flag controls what happens when a document would be loaded 100 * from the cache to satisfy a call to AsyncOpen. If this attribute is 101 * set to TRUE, then the document will not be loaded from the cache. A 102 * stream listener can check nsICachingChannel::isFromCache to determine 103 * if the AsyncOpen will actually result in data being streamed. 104 * 105 * If this flag has been set, and the request can be satisfied via the 106 * cache, then the OnDataAvailable events will be skipped. The listener 107 * will only see OnStartRequest followed by OnStopRequest. 108 */ 109 const unsigned long LOAD_ONLY_IF_MODIFIED = 1 << 31; 110 };