netwerk/cache2/nsICacheEntry.idl

   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 nsIInputStream;
   8 interface nsIOutputStream;
   9 interface nsICacheEntryDoomCallback;
  10
  11 // ************************ REMOVE **********************
  12 typedef long nsCacheAccessMode;
  13 typedef long nsCacheStoragePolicy;
  14
  15 interface nsICacheListener;
  16 interface nsIFile;
  17 interface nsICacheEntryMetaDataVisitor;
  18
  19 [scriptable, uuid(607c2a2c-0a48-40b9-a956-8cf2bb9857cf)]
  20 interface nsICacheEntry : nsISupports
  21 {
  22   /**
  23    * Placeholder for the initial value of expiration time.
  24    */
  25   const unsigned long NO_EXPIRATION_TIME = 0xFFFFFFFF;
  26
  27   /**
  28    * Get the key identifying the cache entry.
  29    */
  30   readonly attribute ACString key;
  31
  32   /**
  33    * Whether the entry is memory/only or persisted to disk.
  34    * Note: private browsing entries are reported as persistent for consistency
  35    * while are not actually persisted to disk.
  36    */
  37   readonly attribute boolean persistent;
  38
  39   /**
  40    * Get the number of times the cache entry has been opened.
  41    */
  42   readonly attribute long  fetchCount;
  43
  44   /**
  45    * Get the last time the cache entry was opened (in seconds since the Epoch).
  46    */
  47   readonly attribute uint32_t  lastFetched;
  48
  49   /**
  50    * Get the last time the cache entry was modified (in seconds since the Epoch).
  51    */
  52   readonly attribute uint32_t  lastModified;
  53
  54   /**
  55    * Get the expiration time of the cache entry (in seconds since the Epoch).
  56    */
  57   readonly attribute uint32_t  expirationTime;
  58
  59   /**
  60    * Set the time at which the cache entry should be considered invalid (in
  61    * seconds since the Epoch).
  62    */
  63   void setExpirationTime(in uint32_t expirationTime);
  64
  65   /**
  66    * This method is intended to override the per-spec cache validation
  67    * decisions for a duration specified in seconds. The current state can
  68    * be examined with isForcedValid (see below). This value is not persisted,
  69    * so it will not survive session restart. Cache entries that are forced valid
  70    * will not be evicted from the cache for the duration of forced validity.
  71    * This means that there is a potential problem if the number of forced valid
  72    * entries grows to take up more space than the cache size allows.
  73    *
  74    * @param aSecondsToTheFuture
  75    *        the number of seconds the default cache validation behavior will be
  76    *        overridden before it returns to normal
  77    */
  78   void forceValidFor(in unsigned long aSecondsToTheFuture);
  79
  80   /**
  81    * The state variable for whether this entry is currently forced valid.
  82    * Defaults to false for normal cache validation behavior, and will return
  83    * true if the number of seconds set by forceValidFor() has yet to be reached.
  84    */
  85   readonly attribute boolean isForcedValid;
  86
  87   /**
  88    * Open blocking input stream to cache data.  Use the stream transport
  89    * service to asynchronously read this stream on a background thread.
  90    * The returned stream MAY implement nsISeekableStream.
  91    *
  92    * @param offset
  93    *        read starting from this offset into the cached data.  an offset
  94    *        beyond the end of the stream has undefined consequences.
  95    *
  96    * @return non-blocking, buffered input stream.
  97    */
  98   nsIInputStream openInputStream(in long long offset);
  99
 100   /**
 101    * Open non-blocking output stream to cache data.  The returned stream
 102    * MAY implement nsISeekableStream.
 103    *
 104    * If opening an output stream to existing cached data, the data will be
 105    * truncated to the specified offset.
 106    *
 107    * @param offset
 108    *        write starting from this offset into the cached data.  an offset
 109    *        beyond the end of the stream has undefined consequences.
 110    *
 111    * @return blocking, buffered output stream.
 112    */
 113   nsIOutputStream openOutputStream(in long long offset);
 114
 115   /**
 116     * Stores the Content-Length specified in the HTTP header for this
 117     * entry. Checked before we write to the cache entry, to prevent ever
 118     * taking up space in the cache for an entry that we know up front
 119     * is going to have to be evicted anyway. See bug 588507.
 120     */
 121   attribute int64_t predictedDataSize;
 122
 123   /**
 124    * Get/set security info on the cache entry for this descriptor.
 125    */
 126   attribute nsISupports securityInfo;
 127
 128   /**
 129    * Get the size of the cache entry data, as stored. This may differ
 130    * from the entry's dataSize, if the entry is compressed.
 131    */
 132   readonly attribute unsigned long storageDataSize;
 133
 134   /**
 135    * Asynchronously doom an entry. Listener will be notified about the status
 136    * of the operation. Null may be passed if caller doesn't care about the
 137    * result.
 138    */
 139   void asyncDoom(in nsICacheEntryDoomCallback listener);
 140
 141   /**
 142    * Methods for accessing meta data.  Meta data is a table of key/value
 143    * string pairs.  The strings do not have to conform to any particular
 144    * charset, but they must be null terminated.
 145    */
 146   string getMetaDataElement(in string key);
 147   void   setMetaDataElement(in string key, in string value);
 148
 149   /**
 150    * Obtain the list of metadata keys this entry keeps.
 151    *
 152    * NOTE: The callback is invoked under the CacheFile's lock.  It means
 153    * there should not be made any calls to the entry from the visitor and
 154    * if the values need to be processed somehow, it's better to cache them
 155    * and process outside the callback.
 156    */
 157   void visitMetaData(in nsICacheEntryMetaDataVisitor visitor);
 158
 159   /**
 160    * Claims that all metadata on this entry are up-to-date and this entry
 161    * now can be delivered to other waiting consumers.
 162    *
 163    * We need such method since metadata must be delivered synchronously.
 164    */
 165   void metaDataReady();
 166
 167   /**
 168    * Called by consumer upon 304/206 response from the server.  This marks
 169    * the entry content as positively revalidated.
 170    * Consumer uses this method after the consumer has returned ENTRY_NEEDS_REVALIDATION
 171    * result from onCacheEntryCheck and after successfull revalidation with the server.
 172    */
 173   void setValid();
 174
 175   /**
 176    * Doom this entry and open a new, empty, entry for write.  Consumer has
 177    * to exchange the entry this method is called on for the newly created.
 178    * Used on 200 responses to conditional requests.
 179    *
 180    * @param aMemoryOnly
 181    *    - whether the entry is to be created as memory/only regardless how
 182    *      the entry being recreated persistence is set
 183    * @returns
 184    *    - an entry that can be used to write to
 185    * @throws
 186    *    - NS_ERROR_NOT_AVAILABLE when the entry cannot be from some reason
 187    *      recreated for write
 188    */
 189   nsICacheEntry recreate([optional] in boolean aMemoryOnly);
 190
 191   /**
 192    * Returns the length of data this entry holds.
 193    * @throws
 194    *    NS_ERROR_IN_PROGRESS when the write is still in progress.
 195    */
 196   readonly attribute long long dataSize;
 197
 198   /****************************************************************************
 199    * The following methods might be added to some nsICacheEntryInternal
 200    * interface since we want to remove them as soon as the old cache backend is
 201    * completely removed.
 202    */
 203
 204   /**
 205    * @deprecated
 206    * FOR BACKWARD COMPATIBILITY ONLY
 207    * When the old cache backend is eventually removed, this method
 208    * can be removed too.
 209    *
 210    * In the new backend: this method is no-op
 211    * In the old backend: this method delegates to nsICacheEntryDescriptor.close()
 212    */
 213   void close();
 214
 215   /**
 216    * @deprecated
 217    * FOR BACKWARD COMPATIBILITY ONLY
 218    * Marks the entry as valid so that others can use it and get only readonly
 219    * access when the entry is held by the 1st writer.
 220    */
 221   void markValid();
 222
 223   /**
 224    * @deprecated
 225    * FOR BACKWARD COMPATIBILITY ONLY
 226    * Marks the entry as valid when write access is acquired.
 227    */
 228   void maybeMarkValid();
 229
 230   /**
 231    * @deprecated
 232    * FOR BACKWARD COMPATIBILITY ONLY / KINDA HACK
 233    * @param aWriteAllowed
 234    *    Consumer indicates whether write to the entry is allowed for it.
 235    *    Depends on implementation how the flag is handled.
 236    * @returns
 237    *    true when write access is acquired for this entry,
 238    *    false otherwise
 239    */
 240   boolean hasWriteAccess(in boolean aWriteAllowed);
 241 };
 242
 243 /**
 244  * Argument for nsICacheEntry.visitMetaData, provides access to all metadata
 245  * keys and values stored on the entry.
 246  */
 247 [scriptable, uuid(fea3e276-6ba5-4ceb-a581-807d1f43f6d0)]
 248 interface nsICacheEntryMetaDataVisitor : nsISupports
 249 {
 250   /**
 251    * Called over each key / value pair.
 252    */
 253   void onMetaDataElement(in string key, in string value);
 254 };