dom/quota/nsIQuotaManagerService.idl

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=2 et sw=2 tw=80: */
   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 "nsISupports.idl"
   8
   9 interface nsIPrincipal;
  10 interface nsIQuotaRequest;
  11 interface nsIQuotaCallback;
  12 interface nsIQuotaUsageCallback;
  13 interface nsIQuotaUsageRequest;
  14
  15 [scriptable, builtinclass, uuid(1b3d0a38-8151-4cf9-89fa-4f92c2ef0e7e)]
  16 interface nsIQuotaManagerService : nsISupports
  17 {
  18   /**
  19    * Asynchronously retrieves storage name and returns it as a plain string.
  20    *
  21    * If the dom.quotaManager.testing preference is not true the call will be
  22    * a no-op.
  23    */
  24   [must_use] nsIQuotaRequest
  25   storageName();
  26
  27   /**
  28    * Check if storage is initialized.
  29    *
  30    * If the dom.quotaManager.testing preference is not true the call will be
  31    * a no-op.
  32    */
  33   [must_use] nsIQuotaRequest
  34   storageInitialized();
  35
  36   /**
  37    * Check if temporary storage is initialized.
  38    *
  39    * If the dom.quotaManager.testing preference is not true the call will be
  40    * a no-op.
  41    */
  42   [must_use] nsIQuotaRequest
  43   temporaryStorageInitialized();
  44
  45   /**
  46    * Initializes storage directory. This can be used in tests to verify
  47    * upgrade methods.
  48    *
  49    * If the dom.quotaManager.testing preference is not true the call will be
  50    * a no-op.
  51    */
  52   [must_use] nsIQuotaRequest
  53   init();
  54
  55   /**
  56    * Initializes temporary storage. This can be used in tests to verify
  57    * temporary storage initialization.
  58    *
  59    * If the dom.quotaManager.testing preference is not true the call will be
  60    * a no-op.
  61    */
  62   [must_use] nsIQuotaRequest
  63   initTemporaryStorage();
  64
  65   /**
  66    * Initializes persistent origin directory for the given origin. This can be
  67    * used in tests to verify origin initialization.
  68    *
  69    * If the dom.quotaManager.testing preference is not true the call will be
  70    * a no-op.
  71    *
  72    * @param aPrincipal
  73    *        A principal for the origin whose directory is to be initialized.
  74    */
  75   [must_use] nsIQuotaRequest
  76   initializePersistentOrigin(in nsIPrincipal aPrincipal);
  77
  78   /**
  79    * Initializes temporary origin directory for the given origin. This can be
  80    * used in tests to verify origin initialization.
  81    *
  82    * If the dom.quotaManager.testing preference is not true the call will be
  83    * a no-op.
  84    *
  85    * @param aPersistenceType
  86    *        A string that tells what persistence type of origin will be
  87    *        initialized (temporary or default).
  88    *
  89    * @param aPrincipal
  90    *        A principal for the origin whose directory is to be initialized.
  91    */
  92   [must_use] nsIQuotaRequest
  93   initializeTemporaryOrigin(in ACString aPersistenceType,
  94                             in nsIPrincipal aPrincipal);
  95
  96   /**
  97    * Schedules an asynchronous callback that will inspect all origins and
  98    * return the total amount of disk space being used by storages for each
  99    * origin separately.
 100    *
 101    * @param aCallback
 102    *        The callback that will be called when the usage is available.
 103    * @param aGetAll
 104    *        An optional boolean to indicate inspection of all origins,
 105    *        including internal ones.
 106    */
 107   [must_use] nsIQuotaUsageRequest
 108   getUsage(in nsIQuotaUsageCallback aCallback,
 109            [optional] in boolean aGetAll);
 110
 111   /**
 112    * Schedules an asynchronous callback that will return the total amount of
 113    * disk space being used by storages for the given origin.
 114    *
 115    * @param aPrincipal
 116    *        A principal for the origin whose usage is being queried.
 117    * @param aCallback
 118    *        The callback that will be called when the usage is available.
 119    * @param aFromMemory
 120    *        An optional flag to indicate whether the cached usage should be
 121    *        obtained. The default value is false.  Note that this operation may
 122    *        still be delayed by other operations on the QM I/O thread that are
 123    *        peforming I/O.
 124    * Note:  Origin usage here represents total usage of an origin. However,
 125    *        cached usage here represents only non-persistent usage of an origin.
 126    */
 127   [must_use] nsIQuotaUsageRequest
 128   getUsageForPrincipal(in nsIPrincipal aPrincipal,
 129                        in nsIQuotaUsageCallback aCallback,
 130                        [optional] in boolean aFromMemory);
 131
 132   /**
 133    * Asynchronously lists all origins and returns them as plain strings.
 134    */
 135   [must_use] nsIQuotaRequest
 136   listOrigins();
 137
 138   /**
 139    * Removes all storages. The files may not be deleted immediately depending
 140    * on prohibitive concurrent operations.
 141    * Be careful, this removes *all* the data that has ever been stored!
 142    *
 143    * If the dom.quotaManager.testing preference is not true the call will be
 144    * a no-op.
 145    */
 146   [must_use] nsIQuotaRequest
 147   clear();
 148
 149   /**
 150    * Removes all storages stored for the given pattern. The files may not be
 151    * deleted immediately depending on prohibitive concurrent operations.  In
 152    * terms of locks, it will get an exclusive multi directory lock for given
 153    * pattern.  For example, given pattern {"userContextId":1007} and set of 3
 154    * origins ["http://www.mozilla.org^userContextId=1007",
 155    * "http://www.example.org^userContextId=1007",
 156    * "http://www.example.org^userContextId=1008"], the method will only lock 2
 157    * origins ["http://www.mozilla.org^userContextId=1007",
 158    * "http://www.example.org^userContextId=1007"].
 159    *
 160    * @param aPattern
 161    *        A pattern for the origins whose storages are to be cleared.
 162    *        Currently this is expected to be a JSON representation of the
 163    *        OriginAttributesPatternDictionary defined in ChromeUtils.webidl.
 164    */
 165   [must_use] nsIQuotaRequest
 166   clearStoragesForOriginAttributesPattern(in AString aPattern);
 167
 168   /**
 169    * Removes all storages stored for the given principal. The files may not be
 170    * deleted immediately depending on prohibitive concurrent operations.
 171    *
 172    * @param aPrincipal
 173    *        A principal for the origin whose storages are to be cleared.
 174    * @param aPersistenceType
 175    *        An optional string that tells what persistence type of storages
 176    *        will be cleared.  If omitted (or void), all persistence types will
 177    *        be cleared for the principal.  If a single persistence type
 178    *        ("persistent", "temporary", or "default") is provided, then only
 179    *        that persistence directory will be considered.  Note that
 180    *        "persistent" is different than being "persisted" via persist() and
 181    *        is only for chrome principals.  See bug 1354500 for more info.
 182    *        In general, null is the right thing to pass here.
 183    * @param aClientType
 184    *        An optional string that tells what client type of storages
 185    *        will be cleared.  If omitted (or void), all client types will be
 186    *        cleared for the principal.  If a single client type is provided
 187    *        from Client.h, then only that client's storage will be cleared.
 188    *        If you want to clear multiple client types (but not all), then you
 189    *        must call this method multiple times.
 190    * @param aClearAll
 191    *        An optional boolean to indicate clearing all storages under the
 192    *        given origin.
 193    */
 194   [must_use] nsIQuotaRequest
 195   clearStoragesForPrincipal(in nsIPrincipal aPrincipal,
 196                             [optional] in ACString aPersistenceType,
 197                             [optional] in AString aClientType,
 198                             [optional] in boolean aClearAll);
 199
 200   /**
 201    * Resets quota and storage management. This can be used to force
 202    * reinitialization of the temp storage, for example when the pref for
 203    * overriding the temp storage limit has changed.
 204    * Be carefull, this invalidates all live storages!
 205    *
 206    * If the dom.quotaManager.testing preference is not true the call will be
 207    * a no-op.
 208    */
 209   [must_use] nsIQuotaRequest
 210   reset();
 211
 212   /**
 213    * Resets all storages stored for the given principal.
 214    *
 215    * If the dom.quotaManager.testing preference is not true the call will be
 216    * a no-op.
 217    *
 218    * @param aPrincipal
 219    *        A principal for the origin whose storages are to be reset.
 220    * @param aPersistenceType
 221    *        An optional string that tells what persistence type of storages
 222    *        will be reset.  If omitted (or void), all persistence types will
 223    *        be cleared for the principal.  If a single persistence type
 224    *        ("persistent", "temporary", or "default") is provided, then only
 225    *        that persistence directory will be considered.  Note that
 226    *        "persistent" is different than being "persisted" via persist() and
 227    *        is only for chrome principals.  See bug 1354500 for more info.
 228    *        In general, null is the right thing to pass here.
 229    * @param aClientType
 230    *        An optional string that tells what client type of storages
 231    *        will be reset.  If omitted (or void), all client types will be
 232    *        cleared for the principal.  If a single client type is provided
 233    *        from Client.h, then only that client's storage will be cleared.
 234    *        If you want to clear multiple client types (but not all), then you
 235    *        must call this method multiple times.
 236    */
 237   [must_use] nsIQuotaRequest
 238   resetStoragesForPrincipal(in nsIPrincipal aPrincipal,
 239                             [optional] in ACString aPersistenceType,
 240                             [optional] in AString aClientType);
 241
 242   /**
 243    * Check if given origin is persisted.
 244    *
 245    * @param aPrincipal
 246    *        A principal for the origin which we want to check.
 247    */
 248   [must_use] nsIQuotaRequest
 249   persisted(in nsIPrincipal aPrincipal);
 250
 251   /**
 252    * Persist given origin.
 253    *
 254    * @param aPrincipal
 255    *        A principal for the origin which we want to persist.
 256    */
 257   [must_use] nsIQuotaRequest
 258   persist(in nsIPrincipal aPrincipal);
 259
 260   /**
 261    * Given an origin, asynchronously calculate its group quota usage and quota
 262    * limit. An origin's group is the set of all origins that share the same
 263    * eTLD+1. This method is intended to be used for our implementation of the
 264    * StorageManager.estimate() method. When we fix bug 1305665 and stop tracking
 265    * quota limits on a group basis, this method will switch to operating on
 266    * origins. Callers should strongly consider whether they want to be using
 267    * getUsageForPrincipal() instead.
 268    *
 269    * This mechanism uses cached quota values and does not perform any I/O on its
 270    * own, but it may be delayed by QuotaManager operations that do need to
 271    * perform I/O on the QuotaManager I/O thread.
 272    *
 273    * @param aPrincipal
 274    *        A principal for the origin (group) which we want to estimate.
 275    */
 276   [must_use] nsIQuotaRequest
 277   estimate(in nsIPrincipal aPrincipal);
 278 };