netwerk/cache2/nsICacheStorage.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 nsIURI;
   8 interface nsICacheEntry;
   9 interface nsICacheEntryOpenCallback;
  10 interface nsICacheEntryDoomCallback;
  11 interface nsICacheStorageVisitor;
  12
  13 /**
  14  * Representation of a cache storage. There can be just-in-mem,
  15  * in-mem+on-disk, in-mem+on-disk+app-cache or just a specific
  16  * app-cache storage.
  17  */
  18 [scriptable, uuid(35d104a6-d252-4fd4-8a56-3c14657cad3b)]
  19 interface nsICacheStorage : nsISupports
  20 {
  21   /**
  22    * Placeholder for specifying "no special flags" during open.
  23    */
  24   const uint32_t OPEN_NORMALLY = 0;
  25
  26   /**
  27    * Rewrite any existing data when opening a URL.
  28    */
  29   const uint32_t OPEN_TRUNCATE = 1 << 0;
  30
  31   /**
  32    * Only open an existing entry.  Don't create a new one.
  33    */
  34   const uint32_t OPEN_READONLY = 1 << 1;
  35
  36   /**
  37    * Use for first-paint blocking loads.
  38    */
  39   const uint32_t OPEN_PRIORITY = 1 << 2;
  40
  41   /**
  42    * Bypass the cache load when write is still in progress.
  43    */
  44   const uint32_t OPEN_BYPASS_IF_BUSY = 1 << 3;
  45
  46   /**
  47    * Perform the cache entry check (onCacheEntryCheck invocation) on any thread
  48    * for optimal perfomance optimization.  If this flag is not specified it is
  49    * ensured that onCacheEntryCheck is called on the same thread as respective
  50    * asyncOpen has been called.
  51    */
  52   const uint32_t CHECK_MULTITHREADED = 1 << 4;
  53
  54   /**
  55    * Don't automatically update any 'last used' metadata of the entry.
  56    */
  57   const uint32_t OPEN_SECRETLY = 1 << 5;
  58
  59   /**
  60    * Entry is being opened as part of a service worker interception.  Do not
  61    * allow the cache to be disabled in this case.
  62    */
  63   const uint32_t OPEN_INTERCEPTED = 1 << 6;
  64
  65   /**
  66    * Asynchronously opens a cache entry for the specified URI.
  67    * Result is fetched asynchronously via the callback.
  68    *
  69    * @param aURI
  70    *    The URI to search in cache or to open for writting.
  71    * @param aIdExtension
  72    *    Any string that will extend (distinguish) the entry.  Two entries
  73    *    with the same aURI but different aIdExtension will be comletely
  74    *    different entries.  If you don't know what aIdExtension should be
  75    *    leave it empty.
  76    * @param aFlags
  77    *    OPEN_NORMALLY - open cache entry normally for read and write
  78    *    OPEN_TRUNCATE - delete any existing entry before opening it
  79    *    OPEN_READONLY - don't create an entry if there is none
  80    *    OPEN_PRIORITY - give this request a priority over others
  81    *    OPEN_BYPASS_IF_BUSY - backward compatibility only, LOAD_BYPASS_LOCAL_CACHE_IF_BUSY
  82    *    CHECK_MULTITHREADED - onCacheEntryCheck may be called on any thread, consumer
  83    *                          implementation is thread-safe
  84    * @param aCallback
  85    *    The consumer that receives the result.
  86    *    IMPORTANT: The callback may be called sooner the method returns.
  87    */
  88   void asyncOpenURI(in nsIURI aURI, in ACString aIdExtension,
  89                     in uint32_t aFlags,
  90                     in nsICacheEntryOpenCallback aCallback);
  91
  92   /**
  93    * Immediately opens a new and empty cache entry in the storage, any existing
  94    * entries are immediately doomed.  This is similar to the recreate() method
  95    * on nsICacheEntry.
  96    *
  97    * Storage may not implement this method and throw NS_ERROR_NOT_IMPLEMENTED.
  98    * In that case consumer must use asyncOpen with OPEN_TRUNCATE flag and get
  99    * the new entry via a callback.
 100    *
 101    * @param aURI @see asyncOpenURI
 102    * @param aIdExtension @see asyncOpenURI
 103    */
 104   nsICacheEntry openTruncate(in nsIURI aURI,
 105                              in ACString aIdExtension);
 106
 107   /**
 108    * Synchronously check on existance of an entry.  In case of disk entries
 109    * this uses information from the cache index.  When the index data are not
 110    * up to date or index is still building, NS_ERROR_NOT_AVAILABLE is thrown.
 111    * The same error may throw any storage implementation that cannot determine
 112    * entry state without blocking the caller.
 113    */
 114   boolean exists(in nsIURI aURI, in ACString aIdExtension);
 115
 116   /**
 117    * Synchronously check on existance of alternative data and size of the
 118    * content. When the index data are not up to date or index is still building,
 119    * NS_ERROR_NOT_AVAILABLE is thrown. The same error may throw any storage
 120    * implementation that cannot determine entry state without blocking the caller.
 121    */
 122   void getCacheIndexEntryAttrs(in nsIURI aURI,
 123                                in ACString aIdExtension,
 124                                out bool aHasAltData,
 125                                out uint32_t aSizeInKB);
 126   /**
 127    * Asynchronously removes an entry belonging to the URI from the cache.
 128    */
 129   void asyncDoomURI(in nsIURI aURI, in ACString aIdExtension,
 130                     in nsICacheEntryDoomCallback aCallback);
 131
 132   /**
 133    * Asynchronously removes all cached entries under this storage.
 134    * NOTE: Disk storage also evicts memory storage.
 135    */
 136   void asyncEvictStorage(in nsICacheEntryDoomCallback aCallback);
 137
 138   /**
 139    * Visits the storage and its entries.
 140    * NOTE: Disk storage also visits memory storage.
 141    */
 142   void asyncVisitStorage(in nsICacheStorageVisitor aVisitor,
 143                          in boolean aVisitEntries);
 144
 145 };