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 7interface nsIInputStream; 8interface nsIOutputStream; 9interface nsIAsyncOutputStream; 10interface nsICacheEntryDoomCallback; 11 12interface nsIFile; 13interface nsICacheEntryMetaDataVisitor; 14interface nsILoadContextInfo; 15 16[scriptable, uuid(607c2a2c-0a48-40b9-a956-8cf2bb9857cf)] 17interface nsICacheEntry : nsISupports 18{ 19 const unsigned long CONTENT_TYPE_UNKNOWN = 0; 20 const unsigned long CONTENT_TYPE_OTHER = 1; 21 const unsigned long CONTENT_TYPE_JAVASCRIPT = 2; 22 const unsigned long CONTENT_TYPE_IMAGE = 3; 23 const unsigned long CONTENT_TYPE_MEDIA = 4; 24 const unsigned long CONTENT_TYPE_STYLESHEET = 5; 25 const unsigned long CONTENT_TYPE_WASM = 6; 26 /** 27 * Content type that is used internally to check whether the value parsed 28 * from disk is within allowed limits. Don't pass CONTENT_TYPE_LAST to 29 * setContentType method. 30 */ 31 const unsigned long CONTENT_TYPE_LAST = 7; 32 33 /** 34 * Placeholder for the initial value of expiration time. 35 */ 36 const unsigned long NO_EXPIRATION_TIME = 0xFFFFFFFF; 37 38 /** 39 * Get the key identifying the cache entry. 40 */ 41 readonly attribute ACString key; 42 43 /** 44 * The unique ID for every nsICacheEntry instance, which can be used to check 45 * whether two pieces of information are from the same nsICacheEntry instance. 46 */ 47 readonly attribute uint64_t cacheEntryId; 48 49 /** 50 * Whether the entry is memory/only or persisted to disk. 51 * Note: private browsing entries are reported as persistent for consistency 52 * while are not actually persisted to disk. 53 */ 54 readonly attribute boolean persistent; 55 56 /** 57 * Get the number of times the cache entry has been opened. 58 */ 59 readonly attribute long fetchCount; 60 61 /** 62 * Get the last time the cache entry was opened (in seconds since the Epoch). 63 */ 64 readonly attribute uint32_t lastFetched; 65 66 /** 67 * Get the last time the cache entry was modified (in seconds since the Epoch). 68 */ 69 readonly attribute uint32_t lastModified; 70 71 /** 72 * Get the expiration time of the cache entry (in seconds since the Epoch). 73 */ 74 readonly attribute uint32_t expirationTime; 75 76 /** 77 * Set the time at which the cache entry should be considered invalid (in 78 * seconds since the Epoch). 79 */ 80 void setExpirationTime(in uint32_t expirationTime); 81 82 /** 83 * Get the last network response times for onStartReqeust/onStopRequest (in ms). 84 * @throws 85 * - NS_ERROR_NOT_AVAILABLE if onStartTime/onStopTime does not exist. 86 */ 87 readonly attribute uint64_t onStartTime; 88 readonly attribute uint64_t onStopTime; 89 90 /** 91 * Set the network response times for onStartReqeust/onStopRequest (in ms). 92 */ 93 void setNetworkTimes(in uint64_t onStartTime, in uint64_t onStopTime); 94 95 /** 96 * Set content type. Available types are defined at the begining of this file. 97 * The content type is used internally for cache partitioning and telemetry 98 * purposes so there is no getter. 99 */ 100 void setContentType(in uint8_t contentType); 101 102 /** 103 * This method is intended to override the per-spec cache validation 104 * decisions for a duration specified in seconds. The current state can 105 * be examined with isForcedValid (see below). This value is not persisted, 106 * so it will not survive session restart. Cache entries that are forced valid 107 * will not be evicted from the cache for the duration of forced validity. 108 * This means that there is a potential problem if the number of forced valid 109 * entries grows to take up more space than the cache size allows. 110 * 111 * NOTE: entries that have been forced valid will STILL be ignored by HTTP 112 * channels if they have expired AND the resource in question requires 113 * validation after expiring. This is to avoid using known-stale content. 114 * 115 * @param aSecondsToTheFuture 116 * the number of seconds the default cache validation behavior will be 117 * overridden before it returns to normal 118 */ 119 void forceValidFor(in unsigned long aSecondsToTheFuture); 120 121 /** 122 * The state variable for whether this entry is currently forced valid. 123 * Defaults to false for normal cache validation behavior, and will return 124 * true if the number of seconds set by forceValidFor() has yet to be reached. 125 */ 126 readonly attribute boolean isForcedValid; 127 128 /** 129 * Open blocking input stream to cache data. Use the stream transport 130 * service to asynchronously read this stream on a background thread. 131 * The returned stream MAY implement nsISeekableStream. 132 * 133 * @param offset 134 * read starting from this offset into the cached data. an offset 135 * beyond the end of the stream has undefined consequences. 136 * 137 * @return non-blocking, buffered input stream. 138 */ 139 nsIInputStream openInputStream(in long long offset); 140 141 /** 142 * Open non-blocking output stream to cache data. The returned stream 143 * MAY implement nsISeekableStream. 144 * 145 * If opening an output stream to existing cached data, the data will be 146 * truncated to the specified offset. 147 * 148 * @param offset 149 * write starting from this offset into the cached data. an offset 150 * beyond the end of the stream has undefined consequences. 151 * @param predictedSize 152 * Predicted size of the data that will be written. It's used to decide 153 * whether the resulting entry would exceed size limit, in which case 154 * an error is thrown. If the size isn't known in advance, -1 should be 155 * passed. 156 * 157 * @return blocking, buffered output stream. 158 */ 159 nsIOutputStream openOutputStream(in long long offset, in long long predictedSize); 160 161 /** 162 * Get/set security info on the cache entry for this descriptor. 163 */ 164 attribute nsISupports securityInfo; 165 166 /** 167 * Get the size of the cache entry data, as stored. This may differ 168 * from the entry's dataSize, if the entry is compressed. 169 */ 170 readonly attribute unsigned long storageDataSize; 171 172 /** 173 * Asynchronously doom an entry. Listener will be notified about the status 174 * of the operation. Null may be passed if caller doesn't care about the 175 * result. 176 */ 177 void asyncDoom(in nsICacheEntryDoomCallback listener); 178 179 /** 180 * Methods for accessing meta data. Meta data is a table of key/value 181 * string pairs. The strings do not have to conform to any particular 182 * charset, but they must be null terminated. 183 */ 184 string getMetaDataElement(in string key); 185 void setMetaDataElement(in string key, in string value); 186 187 /** 188 * Obtain the list of metadata keys this entry keeps. 189 * 190 * NOTE: The callback is invoked under the CacheFile's lock. It means 191 * there should not be made any calls to the entry from the visitor and 192 * if the values need to be processed somehow, it's better to cache them 193 * and process outside the callback. 194 */ 195 void visitMetaData(in nsICacheEntryMetaDataVisitor visitor); 196 197 /** 198 * Claims that all metadata on this entry are up-to-date and this entry 199 * now can be delivered to other waiting consumers. 200 * 201 * We need such method since metadata must be delivered synchronously. 202 */ 203 void metaDataReady(); 204 205 /** 206 * Called by consumer upon 304/206 response from the server. This marks 207 * the entry content as positively revalidated. 208 * Consumer uses this method after the consumer has returned ENTRY_NEEDS_REVALIDATION 209 * result from onCacheEntryCheck and after successfull revalidation with the server. 210 */ 211 void setValid(); 212 213 /** 214 * Explicitly tell the cache backend this consumer is no longer going to modify 215 * this cache entry data or metadata. In case the consumer was responsible to 216 * either of writing the cache entry or revalidating it, calling this method 217 * reverts the state to initial (as never written) or as not-validated and 218 * immediately notifies the next consumer in line waiting for this entry. 219 * This is the way to prevent deadlocks when someone else than the responsible 220 * channel references the cache entry being in a non-written or revalidating 221 * state. 222 */ 223 void dismiss(); 224 225 /** 226 * Returns the size in kilobytes used to store the cache entry on disk. 227 */ 228 readonly attribute uint32_t diskStorageSizeInKB; 229 230 /** 231 * Doom this entry and open a new, empty, entry for write. Consumer has 232 * to exchange the entry this method is called on for the newly created. 233 * Used on 200 responses to conditional requests. 234 * 235 * @param aMemoryOnly 236 * - whether the entry is to be created as memory/only regardless how 237 * the entry being recreated persistence is set 238 * @returns 239 * - an entry that can be used to write to 240 * @throws 241 * - NS_ERROR_NOT_AVAILABLE when the entry cannot be from some reason 242 * recreated for write 243 */ 244 nsICacheEntry recreate([optional] in boolean aMemoryOnly); 245 246 /** 247 * Returns the length of data this entry holds. 248 * @throws 249 * NS_ERROR_IN_PROGRESS when the write is still in progress. 250 */ 251 readonly attribute long long dataSize; 252 253 /** 254 * Returns the length of data this entry holds. 255 * @throws 256 * - NS_ERROR_IN_PROGRESS when a write is still in progress (either real 257 content or alt data). 258 * - NS_ERROR_NOT_AVAILABLE if alt data does not exist. 259 */ 260 readonly attribute long long altDataSize; 261 262 /** 263 * Returns the type of the saved alt data. 264 * @throws 265 * - NS_ERROR_NOT_AVAILABLE if alt data does not exist. 266 */ 267 readonly attribute ACString altDataType; 268 269 /** 270 * Opens and returns an output stream that a consumer may use to save an 271 * alternate representation of the data. 272 * 273 * @param type 274 * type of the alternative data representation 275 * @param predictedSize 276 * Predicted size of the data that will be written. It's used to decide 277 * whether the resulting entry would exceed size limit, in which case 278 * an error is thrown. If the size isn't known in advance, -1 should be 279 * passed. 280 * 281 * @throws 282 * - NS_ERROR_NOT_AVAILABLE if the real data hasn't been written. 283 * - NS_ERROR_IN_PROGRESS when the writing regular content or alt-data to 284 * the cache entry is still in progress. 285 * 286 * If there is alt-data already saved, it will be overwritten. 287 */ 288 nsIAsyncOutputStream openAlternativeOutputStream(in ACString type, in long long predictedSize); 289 290 /** 291 * Opens and returns an input stream that can be used to read the alternative 292 * representation previously saved in the cache. 293 * If this call is made while writing alt-data is still in progress, it is 294 * still possible to read content from the input stream as it's being written. 295 * @throws 296 * - NS_ERROR_NOT_AVAILABLE if the alt-data representation doesn't exist at 297 * all or if alt-data of the given type doesn't exist. 298 */ 299 nsIInputStream openAlternativeInputStream(in ACString type); 300 301 /** 302 * Get the nsILoadContextInfo of the cache entry 303 */ 304 readonly attribute nsILoadContextInfo loadContextInfo; 305 306 /**************************************************************************** 307 * The following methods might be added to some nsICacheEntryInternal 308 * interface since we want to remove them as soon as the old cache backend is 309 * completely removed. 310 */ 311 312 /** 313 * @deprecated 314 * FOR BACKWARD COMPATIBILITY ONLY 315 * When the old cache backend is eventually removed, this method 316 * can be removed too. 317 * 318 * In the new backend: this method is no-op 319 * In the old backend: this method delegates to nsICacheEntryDescriptor.close() 320 */ 321 void close(); 322 323 /** 324 * @deprecated 325 * FOR BACKWARD COMPATIBILITY ONLY 326 * Marks the entry as valid so that others can use it and get only readonly 327 * access when the entry is held by the 1st writer. 328 */ 329 void markValid(); 330 331 /** 332 * @deprecated 333 * FOR BACKWARD COMPATIBILITY ONLY 334 * Marks the entry as valid when write access is acquired. 335 */ 336 void maybeMarkValid(); 337 338 /** 339 * @deprecated 340 * FOR BACKWARD COMPATIBILITY ONLY / KINDA HACK 341 * @param aWriteAllowed 342 * Consumer indicates whether write to the entry is allowed for it. 343 * Depends on implementation how the flag is handled. 344 * @returns 345 * true when write access is acquired for this entry, 346 * false otherwise 347 */ 348 boolean hasWriteAccess(in boolean aWriteAllowed); 349}; 350 351/** 352 * Argument for nsICacheEntry.visitMetaData, provides access to all metadata 353 * keys and values stored on the entry. 354 */ 355[scriptable, uuid(fea3e276-6ba5-4ceb-a581-807d1f43f6d0)] 356interface nsICacheEntryMetaDataVisitor : nsISupports 357{ 358 /** 359 * Called over each key / value pair. 360 */ 361 void onMetaDataElement(in string key, in string value); 362}; 363