netwerk/cache2/nsICacheStorageService.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 nsICacheStorage;
   8 interface nsILoadContextInfo;
   9 interface nsIEventTarget;
  10 interface nsICacheStorageConsumptionObserver;
  11 interface nsICacheStorageVisitor;
  12 interface nsIPrincipal;
  13
  14 /**
  15  * Provides access to particual cache storages of the network URI cache.
  16  */
  17 [scriptable, uuid(ae29c44b-fbc3-4552-afaf-0a157ce771e7)]
  18 interface nsICacheStorageService : nsISupports
  19 {
  20   /**
  21    * Get storage where entries will only remain in memory, never written
  22    * to the disk.
  23    *
  24    * NOTE: Any existing disk entry for [URL|id-extension] will be doomed
  25    * prior opening an entry using this memory-only storage.  Result of
  26    * AsyncOpenURI will be a new and empty memory-only entry.  Using
  27    * OPEN_READONLY open flag has no effect on this behavior.
  28    *
  29    * @param aLoadContextInfo
  30    *    Information about the loading context, this focuses the storage JAR and
  31    *    respects separate storage for private browsing.
  32    */
  33   nsICacheStorage memoryCacheStorage(in nsILoadContextInfo aLoadContextInfo);
  34
  35   /**
  36    * Get storage where entries will be written to disk when not forbidden by
  37    * response headers.
  38    */
  39   nsICacheStorage diskCacheStorage(in nsILoadContextInfo aLoadContextInfo);
  40
  41   /**
  42    * Get storage where entries will be written to disk and marked as pinned.
  43    * These pinned entries are immune to over limit eviction and call of clear()
  44    * on this service.
  45    */
  46   nsICacheStorage pinningCacheStorage(in nsILoadContextInfo aLoadContextInfo);
  47
  48   /**
  49    * Evict any cache entry having the same origin of aPrincipal.
  50    *
  51    * @param aPrincipal
  52    *   The principal to compare the entries with.
  53    */
  54   void clearOrigin(in nsIPrincipal aPrincipal);
  55
  56   /**
  57    * Evict any cache entry which belongs to a base domain. This includes entries
  58    * partitioned under aBaseDomain and entries which belong to aBaseDomain, but
  59    * are partitioned under other top level sites.
  60    * @param aBaseDomain
  61    *   The base domain to clear cache for.
  62    */
  63   void clearBaseDomain(in AString aBaseDomain);
  64
  65   /**
  66    * Evict any cache entry having the same originAttributes.
  67    *
  68    * @param aOriginAttributes
  69    *   The origin attributes in string format to compare the entries with.
  70    */
  71   void clearOriginAttributes(in AString aOriginAttributes);
  72
  73   /**
  74    * Evict the whole cache.
  75    */
  76   void clear();
  77
  78   /**
  79    * Purge only data of disk backed entries.  Metadata are left for
  80    * performance purposes.
  81    */
  82   const uint32_t PURGE_DISK_DATA_ONLY = 1;
  83   /**
  84    * Purge whole disk backed entries from memory.  Disk files will
  85    * be left unattended.
  86    */
  87   const uint32_t PURGE_DISK_ALL = 2;
  88   /**
  89    * Purge all entries we keep in memory, including memory-storage
  90    * entries.  This may be dangerous to use.
  91    */
  92   const uint32_t PURGE_EVERYTHING = 3;
  93   /**
  94    * Purges data we keep warmed in memory.  Use for tests and for
  95    * saving memory.
  96    */
  97   void purgeFromMemory(in uint32_t aWhat);
  98
  99   /**
 100    * I/O thread target to use for any operations on disk
 101    */
 102   readonly attribute nsIEventTarget ioTarget;
 103
 104   /**
 105    * Asynchronously determine how many bytes of the disk space the cache takes.
 106    * @see nsICacheStorageConsumptionObserver
 107    * @param aObserver
 108    *    A mandatory (weak referred) observer.  Documented at
 109    *    nsICacheStorageConsumptionObserver.
 110    *    NOTE: the observer MUST implement nsISupportsWeakReference.
 111    */
 112   void asyncGetDiskConsumption(in nsICacheStorageConsumptionObserver aObserver);
 113
 114   /**
 115    * Asynchronously visits all storages of the disk cache and memory cache.
 116    * @see nsICacheStorageVisitor
 117    * @param aVisitor
 118    *   A visitor callback.
 119    * @param aVisitEntries
 120    *   A boolean indicates whether visits entries.
 121    */
 122   void asyncVisitAllStorages(in nsICacheStorageVisitor aVisitor,
 123                              in boolean aVisitEntries);
 124 };
 125
 126 [scriptable, uuid(7728ab5b-4c01-4483-a606-32bf5b8136cb)]
 127 interface nsICacheStorageConsumptionObserver : nsISupports
 128 {
 129   /**
 130    * Callback invoked to answer asyncGetDiskConsumption call. Always triggered
 131    * on the main thread.
 132    * NOTE: implementers must also implement nsISupportsWeakReference.
 133    *
 134    * @param aDiskSize
 135    *    The disk consumption in bytes.
 136    */
 137   void onNetworkCacheDiskConsumption(in int64_t aDiskSize);
 138 };