nsICacheInfoChannel.idl (8895B)
1 /* This Source Code Form is subject to the terms of the Mozilla Public 2 * License, v. 2.0. If a copy of the MPL was not distributed with this 3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 4 5 #include "nsISupports.idl" 6 7 interface nsIAsyncOutputStream; 8 interface nsIInputStream; 9 10 %{C++ 11 #include "nsTArray.h" 12 namespace mozilla { 13 namespace net { 14 class PreferredAlternativeDataTypeParams; 15 } // namespace net 16 } // namespace mozilla 17 %} 18 19 [ref] native ConstPreferredAlternativeDataTypeArray(const nsTArray<mozilla::net::PreferredAlternativeDataTypeParams>); 20 21 [scriptable, uuid(1fb8ccf2-5fa5-45ec-bc57-8c8022a5d0d3)] 22 interface nsIInputStreamReceiver : nsISupports 23 { 24 void onInputStreamReady(in nsIInputStream aStream); 25 }; 26 27 28 /** 29 * A light variant of nsICacheInfoChannel, retrievable from 30 * nsICacheInfoChannel::getCacheEntryWriteHandle. 31 * 32 * When an alternate data is written asynchronously after the response, 33 * this can be used in order to avoid keeping the channels alive longer. 34 */ 35 [scriptable, builtinclass, uuid(0da1249c-d5f5-494e-842b-2c3197c92511)] 36 interface nsICacheEntryWriteHandle : nsISupports 37 { 38 /** 39 * Same as nsICacheInfoChannel::openAlternativeOutputStream. 40 */ 41 nsIAsyncOutputStream openAlternativeOutputStream(in ACString type, in long long predictedSize); 42 }; 43 44 [scriptable, builtinclass, uuid(72c34415-c6eb-48af-851f-772fa9ee5972)] 45 interface nsICacheInfoChannel : nsISupports 46 { 47 /** 48 * Get the number of times the cache entry has been opened. This attribute is 49 * equivalent to nsICachingChannel.cacheToken.fetchCount. 50 * 51 * @throws NS_ERROR_NOT_AVAILABLE if the cache entry or the alternate data 52 * cache entry cannot be read. 53 */ 54 readonly attribute uint32_t cacheTokenFetchCount; 55 56 /** 57 * Get expiration time from cache token. This attribute is equivalent to 58 * nsICachingChannel.cacheToken.expirationTime. 59 */ 60 readonly attribute uint32_t cacheTokenExpirationTime; 61 62 /** 63 * TRUE if this channel's data is being loaded from the cache. This value 64 * is undefined before the channel fires its OnStartRequest notification 65 * and after the channel fires its OnStopRequest notification. 66 */ 67 boolean isFromCache(); 68 69 /** 70 * True if this channel has a corresponding cache entry. This can be true 71 * even if isFromCache() is false. 72 */ 73 boolean hasCacheEntry(); 74 75 /** 76 * Returns true if the channel raced the cache and network requests. 77 * In order to determine if the response is coming from the cache or the 78 * network, the consumer can check isFromCache(). 79 * The method can only be called after the channel fires its OnStartRequest 80 * notification. 81 */ 82 boolean isRacing(); 83 84 /** 85 * The unique ID of the corresponding nsICacheEntry from which the response is 86 * retrieved. By comparing the returned value, we can judge whether the data 87 * of two distinct nsICacheInfoChannels is from the same nsICacheEntry. This 88 * scenario could be useful when verifying whether the alternative data from 89 * one nsICacheInfochannel matches the main data from another one. 90 * 91 * Note: NS_ERROR_NOT_AVAILABLE is thrown when a nsICacheInfoChannel has no 92 * valid corresponding nsICacheEntry. 93 */ 94 uint64_t getCacheEntryId(); 95 96 /** 97 * Set/get the cache key. This integer uniquely identifies the data in 98 * the cache for this channel. 99 * 100 * A cache key retrieved from a particular instance of nsICacheInfoChannel 101 * could be set on another instance of nsICacheInfoChannel provided the 102 * underlying implementations are compatible and provided the new 103 * channel instance was created with the same URI. The implementation of 104 * nsICacheInfoChannel would be expected to use the cache entry identified 105 * by the cache token. Depending on the value of nsIRequest::loadFlags, 106 * the cache entry may be validated, overwritten, or simply read. 107 * 108 * The cache key may be 0 indicating that the URI of the channel is 109 * sufficient to locate the same cache entry. Setting a 0 cache key 110 * is likewise valid. 111 */ 112 attribute unsigned long cacheKey; 113 114 /** 115 * Tells the channel to behave as if the LOAD_FROM_CACHE flag has been set, 116 * but without affecting the loads for the entire loadGroup in case of this 117 * channel being the default load group's channel. 118 */ 119 attribute boolean allowStaleCacheContent; 120 121 /** 122 * Tells the priority for LOAD_CACHE is raised over LOAD_BYPASS_CACHE or 123 * LOAD_BYPASS_LOCAL_CACHE in case those flags are set at the same time. 124 */ 125 attribute boolean preferCacheLoadOverBypass; 126 127 cenum PreferredAlternativeDataDeliveryType : 8 { 128 /** 129 * Do not deliver alternative data stream. 130 */ 131 NONE = 0, 132 133 /** 134 * Deliver alternative data stream upon additional request. 135 */ 136 ASYNC = 1, 137 138 /** 139 * Deliver alternative data stream during IPC parent/child serialization. 140 */ 141 SERIALIZE = 2, 142 }; 143 144 cenum CacheDisposition : 8 { 145 kCacheUnresolved = 0, 146 kCacheHit = 1, 147 kCacheHitViaReval = 2, 148 kCacheMissedViaReval = 3, 149 kCacheMissed = 4, 150 kCacheUnknown = 5, 151 // Insert new values here 152 kCacheDispositionEnd 153 }; 154 155 /** 156 * Tells the channel to be force validated during soft reload. 157 */ 158 attribute boolean forceValidateCacheContent; 159 160 /** 161 * Calling this method instructs the channel to serve the alternative data 162 * if that was previously saved in the cache, otherwise it will serve the 163 * real data. 164 * @param type 165 * a string identifying the alt-data format 166 * @param contentType 167 * the contentType for which the preference applies. 168 * an empty contentType means the preference applies for ANY contentType 169 * @param deliverAltData 170 * if false, also if alt-data is available, the channel will deliver 171 * the original data. 172 * 173 * The method may be called several times, with different type and contentType. 174 * 175 * Must be called before AsyncOpen. 176 */ 177 void preferAlternativeDataType(in ACString type, in ACString contentType, 178 in nsICacheInfoChannel_PreferredAlternativeDataDeliveryType deliverAltData); 179 180 /** 181 * Get the preferred alternative data type set by preferAlternativeDataType(). 182 * The returned types stand for the desired data type instead of the type of the 183 * information retrieved from the network stack. 184 */ 185 [noscript, notxpcom, nostdcall] 186 ConstPreferredAlternativeDataTypeArray preferredAlternativeDataTypes(); 187 188 /** 189 * Holds the type of the alternative data representation that the channel 190 * is returning. 191 * Is empty string if no alternative data representation was requested, or 192 * if the requested representation wasn't found in the cache. 193 * Can only be called during or after OnStartRequest. 194 */ 195 readonly attribute ACString alternativeDataType; 196 197 /** 198 * If preferAlternativeDataType() has been called passing deliverAltData 199 * equal to false, this attribute will expose the alt-data inputStream if 200 * avaiable. 201 */ 202 readonly attribute nsIInputStream alternativeDataInputStream; 203 204 /** 205 * Sometimes when the channel is delivering alt-data, we may want to somehow 206 * access the original content too. This method asynchronously opens the 207 * input stream and delivers it to the receiver. 208 */ 209 void getOriginalInputStream(in nsIInputStreamReceiver aReceiver); 210 211 /** 212 * Get a handle to open the alternative output stream for later use. 213 */ 214 nsICacheEntryWriteHandle getCacheEntryWriteHandle(); 215 216 /** 217 * Opens and returns an output stream that a consumer may use to save an 218 * alternate representation of the data. 219 * Must be called after the OnStopRequest that delivered the real data. 220 * The consumer may choose to replace the saved alt representation. 221 * Opening the output stream will fail if there are any open input streams 222 * reading the already saved alt representation. After successfully opening 223 * an output stream, if there is an error before the entire alt data can be 224 * written successfully, the client must signal failure by passing an error 225 * code to CloseWithStatus(). 226 * 227 * @param type 228 * type of the alternative data representation 229 * @param predictedSize 230 * Predicted size of the data that will be written. It's used to decide 231 * whether the resulting entry would exceed size limit, in which case 232 * an error is thrown. If the size isn't known in advance, -1 should be 233 * passed. 234 */ 235 nsIAsyncOutputStream openAlternativeOutputStream(in ACString type, in long long predictedSize); 236 237 /** 238 * Returns the cache disposition for this channel. 239 */ 240 nsICacheInfoChannel_CacheDisposition getCacheDisposition(); 241 }; 242 243 %{ C++ 244 namespace mozilla { 245 namespace net { 246 247 using PreferredAlternativeDataDeliveryTypeIPC = nsICacheInfoChannel::PreferredAlternativeDataDeliveryType; 248 249 } 250 } // namespace mozilla 251 %}