netwerk/cache/nsICacheEntryDescriptor.idl

   1 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
   2  *
   3  * This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #include "nsICacheVisitor.idl"
   8 #include "nsICache.idl"
   9
  10 interface nsISimpleEnumerator;
  11 interface nsICacheListener;
  12 interface nsIInputStream;
  13 interface nsIOutputStream;
  14 interface nsIFile;
  15 interface nsICacheMetaDataVisitor;
  16
  17
  18 [scriptable, uuid(90b17d31-46aa-4fb1-a206-473c966cbc18)]
  19 interface nsICacheEntryDescriptor : nsICacheEntryInfo
  20 {
  21     /**
  22      * Set the time at which the cache entry should be considered invalid (in
  23      * seconds since the Epoch).
  24      */
  25     void setExpirationTime(in uint32_t expirationTime);
  26
  27     /**
  28      * Set the cache entry data size.  This will fail if the cache entry
  29      * IS stream based.
  30      */
  31     void setDataSize(in unsigned long size);
  32
  33     /**
  34      * Open blocking input stream to cache data.  This will fail if the cache
  35      * entry IS NOT stream based.  Use the stream transport service to
  36      * asynchronously read this stream on a background thread.  The returned
  37      * stream MAY implement nsISeekableStream.
  38      *
  39      * @param offset
  40      *        read starting from this offset into the cached data.  an offset
  41      *        beyond the end of the stream has undefined consequences.
  42      *
  43      * @return blocking, unbuffered input stream.
  44      */
  45     nsIInputStream openInputStream(in unsigned long offset);
  46
  47     /**
  48      * Open blocking output stream to cache data.  This will fail if the cache
  49      * entry IS NOT stream based.  Use the stream transport service to
  50      * asynchronously write to this stream on a background thread.  The returned
  51      * stream MAY implement nsISeekableStream.
  52      *
  53      * If opening an output stream to existing cached data, the data will be
  54      * truncated to the specified offset.
  55      *
  56      * @param offset
  57      *        write starting from this offset into the cached data.  an offset
  58      *        beyond the end of the stream has undefined consequences.
  59      *
  60      * @return blocking, unbuffered output stream.
  61      */
  62     nsIOutputStream openOutputStream(in unsigned long offset);
  63
  64     /**
  65      * Get/set the cache data element.  This will fail if the cache entry
  66      * IS stream based.  The cache entry holds a strong reference to this
  67      * object.  The object will be released when the cache entry is destroyed.
  68      */
  69     attribute nsISupports cacheElement;
  70
  71     /**
  72       * Stores the Content-Length specified in the HTTP header for this
  73       * entry. Checked before we write to the cache entry, to prevent ever
  74       * taking up space in the cache for an entry that we know up front
  75       * is going to have to be evicted anyway. See bug 588507.
  76       */
  77     attribute int64_t    predictedDataSize;
  78
  79     /**
  80      * Get the access granted to this descriptor.  See nsICache.idl for the
  81      * definitions of the access modes and a thorough description of their
  82      * corresponding meanings.
  83      */
  84     readonly attribute nsCacheAccessMode accessGranted;
  85
  86     /**
  87      * Get/set the storage policy of the cache entry.  See nsICache.idl for
  88      * the definitions of the storage policies.
  89      */
  90     attribute nsCacheStoragePolicy storagePolicy;
  91
  92     /**
  93      * Get the disk file associated with the cache entry.
  94      */
  95     readonly attribute nsIFile file;
  96
  97     /**
  98      * Get/set security info on the cache entry for this descriptor.  This fails
  99      * if the storage policy is not STORE_IN_MEMORY.
 100      */
 101     attribute nsISupports securityInfo;
 102
 103     /**
 104      * Get the size of the cache entry data, as stored. This may differ
 105      * from the entry's dataSize, if the entry is compressed.
 106      */
 107     readonly attribute unsigned long storageDataSize;
 108
 109     /**
 110      * Doom the cache entry this descriptor references in order to slate it for
 111      * removal.  Once doomed a cache entry cannot be undoomed.
 112      *
 113      * A descriptor with WRITE access can doom the cache entry and choose to
 114      * fail pending requests.  This means that pending requests will not get
 115      * a cache descriptor.  This is meant as a tool for clients that wish to
 116      * instruct pending requests to skip the cache.
 117      */
 118     void doom();
 119     void doomAndFailPendingRequests(in nsresult status);
 120
 121     /**
 122      * Asynchronously doom an entry. Listener will be notified about the status
 123      * of the operation. Null may be passed if caller doesn't care about the
 124      * result.
 125      */
 126     void asyncDoom(in nsICacheListener listener);
 127
 128     /**
 129      * A writer must validate this cache object before any readers are given
 130      * a descriptor to the object.
 131      */
 132     void markValid();
 133
 134     /**
 135      *  Explicitly close the descriptor (optional).
 136      */
 137
 138     void close();
 139
 140     /**
 141      * Methods for accessing meta data.  Meta data is a table of key/value
 142      * string pairs.  The strings do not have to conform to any particular
 143      * charset, but they must be null terminated.
 144      */
 145     string getMetaDataElement(in string key);
 146     void   setMetaDataElement(in string key, in string value);
 147
 148     /**
 149      * Visitor will be called with key/value pair for each meta data element.
 150      */
 151     void   visitMetaData(in nsICacheMetaDataVisitor  visitor);
 152 };
 153
 154
 155
 156 [scriptable, uuid(22f9a49c-3cf8-4c23-8006-54efb11ac562)]
 157 interface nsICacheMetaDataVisitor : nsISupports
 158 {
 159     /**
 160      * Called for each key/value pair in the meta data for a cache entry
 161      */
 162     boolean visitMetaDataElement(in string  key,
 163                                  in string  value);
 164 };