path: root/netwerk/cache2/nsICacheEntry.idl

/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"
#include "nsICache.idl"

interface nsIInputStream;
interface nsIOutputStream;
interface nsICacheEntryDoomCallback;

interface nsICacheListener;
interface nsIFile;
interface nsICacheEntryMetaDataVisitor;

[scriptable, uuid(607c2a2c-0a48-40b9-a956-8cf2bb9857cf)]
interface nsICacheEntry : nsISupports
{
  /**
   * Placeholder for the initial value of expiration time.
   */
  const unsigned long NO_EXPIRATION_TIME = 0xFFFFFFFF;

  /**
   * Get the key identifying the cache entry.
   */
  readonly attribute ACString key;

  /**
   * Whether the entry is memory/only or persisted to disk.
   * Note: private browsing entries are reported as persistent for consistency
   * while are not actually persisted to disk.
   */
  readonly attribute boolean persistent;

  /**
   * Get the number of times the cache entry has been opened.
   */
  readonly attribute long  fetchCount;

  /**
   * Get the last time the cache entry was opened (in seconds since the Epoch).
   */
  readonly attribute uint32_t  lastFetched;

  /**
   * Get the last time the cache entry was modified (in seconds since the Epoch).
   */
  readonly attribute uint32_t  lastModified;

  /**
   * Get the expiration time of the cache entry (in seconds since the Epoch).
   */
  readonly attribute uint32_t  expirationTime;

  /**
   * Set the time at which the cache entry should be considered invalid (in
   * seconds since the Epoch).
   */
  void setExpirationTime(in uint32_t expirationTime);

  /**
   * This method is intended to override the per-spec cache validation
   * decisions for a duration specified in seconds. The current state can
   * be examined with isForcedValid (see below). This value is not persisted,
   * so it will not survive session restart. Cache entries that are forced valid
   * will not be evicted from the cache for the duration of forced validity.
   * This means that there is a potential problem if the number of forced valid
   * entries grows to take up more space than the cache size allows.
   *
   * NOTE: entries that have been forced valid will STILL be ignored by HTTP
   * channels if they have expired AND the resource in question requires
   * validation after expiring. This is to avoid using known-stale content.
   *
   * @param aSecondsToTheFuture
   *        the number of seconds the default cache validation behavior will be
   *        overridden before it returns to normal
   */
  void forceValidFor(in unsigned long aSecondsToTheFuture);

  /**
   * The state variable for whether this entry is currently forced valid.
   * Defaults to false for normal cache validation behavior, and will return
   * true if the number of seconds set by forceValidFor() has yet to be reached.
   */
  readonly attribute boolean isForcedValid;

  /**
   * Open blocking input stream to cache data.  Use the stream transport
   * service to asynchronously read this stream on a background thread.
   * The returned stream MAY implement nsISeekableStream.
   *
   * @param offset
   *        read starting from this offset into the cached data.  an offset
   *        beyond the end of the stream has undefined consequences.
   *
   * @return non-blocking, buffered input stream.
   */
  nsIInputStream openInputStream(in long long offset);

  /**
   * Open non-blocking output stream to cache data.  The returned stream
   * MAY implement nsISeekableStream.
   *
   * If opening an output stream to existing cached data, the data will be
   * truncated to the specified offset.
   *
   * @param offset
   *        write starting from this offset into the cached data.  an offset
   *        beyond the end of the stream has undefined consequences.
   *
   * @return blocking, buffered output stream.
   */
  nsIOutputStream openOutputStream(in long long offset);

  /**
    * Stores the Content-Length specified in the HTTP header for this
    * entry. Checked before we write to the cache entry, to prevent ever
    * taking up space in the cache for an entry that we know up front
    * is going to have to be evicted anyway. See bug 588507.
    */
  attribute int64_t predictedDataSize;

  /**
   * Get/set security info on the cache entry for this descriptor.
   */
  attribute nsISupports securityInfo;

  /**
   * Get the size of the cache entry data, as stored. This may differ
   * from the entry's dataSize, if the entry is compressed.
   */
  readonly attribute unsigned long storageDataSize;

  /**
   * Asynchronously doom an entry. Listener will be notified about the status
   * of the operation. Null may be passed if caller doesn't care about the
   * result.
   */
  void asyncDoom(in nsICacheEntryDoomCallback listener);

  /**
   * Methods for accessing meta data.  Meta data is a table of key/value
   * string pairs.  The strings do not have to conform to any particular
   * charset, but they must be null terminated.
   */
  string getMetaDataElement(in string key);
  void   setMetaDataElement(in string key, in string value);

  /**
   * Obtain the list of metadata keys this entry keeps.
   *
   * NOTE: The callback is invoked under the CacheFile's lock.  It means
   * there should not be made any calls to the entry from the visitor and
   * if the values need to be processed somehow, it's better to cache them
   * and process outside the callback.
   */
  void visitMetaData(in nsICacheEntryMetaDataVisitor visitor);

  /**
   * Claims that all metadata on this entry are up-to-date and this entry
   * now can be delivered to other waiting consumers.
   *
   * We need such method since metadata must be delivered synchronously.
   */
  void metaDataReady();

  /**
   * Called by consumer upon 304/206 response from the server.  This marks
   * the entry content as positively revalidated.
   * Consumer uses this method after the consumer has returned ENTRY_NEEDS_REVALIDATION
   * result from onCacheEntryCheck and after successfull revalidation with the server.
   */
  void setValid();

  /**
   * Returns the size in kilobytes used to store the cache entry on disk.
   */
   readonly attribute uint32_t diskStorageSizeInKB;

  /**
   * Doom this entry and open a new, empty, entry for write.  Consumer has
   * to exchange the entry this method is called on for the newly created.
   * Used on 200 responses to conditional requests.
   *
   * @param aMemoryOnly
   *    - whether the entry is to be created as memory/only regardless how
   *      the entry being recreated persistence is set
   * @returns
   *    - an entry that can be used to write to
   * @throws
   *    - NS_ERROR_NOT_AVAILABLE when the entry cannot be from some reason
   *      recreated for write
   */
  nsICacheEntry recreate([optional] in boolean aMemoryOnly);

  /**
   * Returns the length of data this entry holds.
   * @throws
   *    NS_ERROR_IN_PROGRESS when the write is still in progress.
   */
  readonly attribute long long dataSize;

  /**
  * Returns the length of data this entry holds.
  * @throws
  *    - NS_ERROR_IN_PROGRESS when a write is still in progress (either real
                              content or alt data).
  *    - NS_ERROR_NOT_AVAILABLE if alt data does not exist.
  */
  readonly attribute long long altDataSize;

  /**
   * Opens and returns an output stream that a consumer may use to save an
   * alternate representation of the data.
   * @throws
   *    - NS_ERROR_NOT_AVAILABLE if the real data hasn't been written.
   *    - NS_ERROR_IN_PROGRESS when the writing regular content or alt-data to
   *      the cache entry is still in progress.
   *
   * If there is alt-data already saved, it will be overwritten.
   */
  nsIOutputStream openAlternativeOutputStream(in ACString type);

  /**
   * Opens and returns an input stream that can be used to read the alternative
   * representation previously saved in the cache.
   * If this call is made while writing alt-data is still in progress, it is
   * still possible to read content from the input stream as it's being written.
   * @throws
   *    - NS_ERROR_NOT_AVAILABLE if the alt-data representation doesn't exist at
   *      all or if alt-data of the given type doesn't exist.
   */
  nsIInputStream openAlternativeInputStream(in ACString type);

  /****************************************************************************
   * The following methods might be added to some nsICacheEntryInternal
   * interface since we want to remove them as soon as the old cache backend is
   * completely removed.
   */

  /**
   * @deprecated
   * FOR BACKWARD COMPATIBILITY ONLY
   * When the old cache backend is eventually removed, this method
   * can be removed too.
   *
   * In the new backend: this method is no-op
   * In the old backend: this method delegates to nsICacheEntryDescriptor.close()
   */
  void close();

  /**
   * @deprecated
   * FOR BACKWARD COMPATIBILITY ONLY
   * Marks the entry as valid so that others can use it and get only readonly
   * access when the entry is held by the 1st writer.
   */
  void markValid();

  /**
   * @deprecated
   * FOR BACKWARD COMPATIBILITY ONLY
   * Marks the entry as valid when write access is acquired.
   */
  void maybeMarkValid();

  /**
   * @deprecated
   * FOR BACKWARD COMPATIBILITY ONLY / KINDA HACK
   * @param aWriteAllowed
   *    Consumer indicates whether write to the entry is allowed for it.
   *    Depends on implementation how the flag is handled.
   * @returns
   *    true when write access is acquired for this entry,
   *    false otherwise
   */
  boolean hasWriteAccess(in boolean aWriteAllowed);
};

/**
 * Argument for nsICacheEntry.visitMetaData, provides access to all metadata
 * keys and values stored on the entry.
 */
[scriptable, uuid(fea3e276-6ba5-4ceb-a581-807d1f43f6d0)]
interface nsICacheEntryMetaDataVisitor : nsISupports
{
  /**
   * Called over each key / value pair.
   */
  void onMetaDataElement(in string key, in string value);
};