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    * Initializes persistent client directory for the given origin and client.
  98    * This can be used in tests to verify client initialization.
  99    *
 100    * If the dom.quotaManager.testing preference is not true the call will be
 101    * a no-op.
 102    *
 103    * @param aPrincipal
 104    *        A principal for the origin whose client directory is to be
 105    *        initialized.
 106    * @param aClientType
 107    *        A string that tells what client type will be initialized.
 108    */
 109   [must_use] nsIQuotaRequest
 110   initializePersistentClient(in nsIPrincipal aPrincipal,
 111                              in AString aClientType);
 112
 113   /**
 114    * Initializes temporary client directory for the given origin and client.
 115    * This can be used in tests to verify client initialization.
 116    *
 117    * If the dom.quotaManager.testing preference is not true the call will be
 118    * a no-op.
 119    *
 120    * @param aPersistenceType
 121    *        A string that tells what persistence type will be initialized
 122    *        (either "temporary" or "default").
 123    * @param aPrincipal
 124    *        A principal for the origin whose client directory is to be
 125    *        initialized.
 126    * @param aClientType
 127    *        A string that tells what client type will be initialized.
 128    */
 129   [must_use] nsIQuotaRequest
 130   initializeTemporaryClient(in ACString aPersistenceType,
 131                             in nsIPrincipal aPrincipal,
 132                             in AString aClientType);
 133
 134   /**
 135    * Gets full origin metadata cached in memory for the given persistence type
 136    * and origin.
 137    *
 138    * NOTE: This operation may still be delayed by other operations on the QM
 139    *       I/O thread that are peforming I/O.
 140    *
 141    * @param aPersistenceType
 142    *        A string that tells what persistence type will be used for getting
 143    *        the metadata (either "temporary" or "default").
 144    * @param aPrincipal
 145    *        A principal that tells which origin will be used for getting the
 146    *        metadata.
 147    */
 148   [must_use] nsIQuotaRequest
 149   getFullOriginMetadata(in ACString aPersistenceType,
 150                         in nsIPrincipal aPrincipal);
 151
 152   /**
 153    * Schedules an asynchronous callback that will inspect all origins and
 154    * return the total amount of disk space being used by storages for each
 155    * origin separately.
 156    *
 157    * @param aCallback
 158    *        The callback that will be called when the usage is available.
 159    * @param aGetAll
 160    *        An optional boolean to indicate inspection of all origins,
 161    *        including internal ones.
 162    */
 163   [must_use] nsIQuotaUsageRequest
 164   getUsage(in nsIQuotaUsageCallback aCallback,
 165            [optional] in boolean aGetAll);
 166
 167   /**
 168    * Schedules an asynchronous callback that will return the total amount of
 169    * disk space being used by storages for the given origin.
 170    *
 171    * @param aPrincipal
 172    *        A principal for the origin whose usage is being queried.
 173    * @param aCallback
 174    *        The callback that will be called when the usage is available.
 175    * @param aFromMemory
 176    *        An optional flag to indicate whether the cached usage should be
 177    *        obtained. The default value is false.  Note that this operation may
 178    *        still be delayed by other operations on the QM I/O thread that are
 179    *        peforming I/O.
 180    * Note:  Origin usage here represents total usage of an origin. However,
 181    *        cached usage here represents only non-persistent usage of an origin.
 182    */
 183   [must_use] nsIQuotaUsageRequest
 184   getUsageForPrincipal(in nsIPrincipal aPrincipal,
 185                        in nsIQuotaUsageCallback aCallback,
 186                        [optional] in boolean aFromMemory);
 187
 188   /**
 189    * Asynchronously lists all origins and returns them as plain strings.
 190    */
 191   [must_use] nsIQuotaRequest
 192   listOrigins();
 193
 194   /**
 195    * Removes all storages. The files may not be deleted immediately depending
 196    * on prohibitive concurrent operations.
 197    * Be careful, this removes *all* the data that has ever been stored!
 198    *
 199    * If the dom.quotaManager.testing preference is not true the call will be
 200    * a no-op.
 201    */
 202   [must_use] nsIQuotaRequest
 203   clear();
 204
 205   /**
 206    * Removes all storages stored for private browsing. The files may not be
 207    * deleted immediately depending on prohibitive concurrent operations.  In
 208    * terms of locks, it will get an exclusive multi directory lock for entire
 209    * private repository.
 210    */
 211   [must_use] nsIQuotaRequest
 212   clearStoragesForPrivateBrowsing();
 213
 214   /**
 215    * Removes all storages stored for the given pattern. The files may not be
 216    * deleted immediately depending on prohibitive concurrent operations.  In
 217    * terms of locks, it will get an exclusive multi directory lock for given
 218    * pattern.  For example, given pattern {"userContextId":1007} and set of 3
 219    * origins ["http://www.mozilla.org^userContextId=1007",
 220    * "http://www.example.org^userContextId=1007",
 221    * "http://www.example.org^userContextId=1008"], the method will only lock 2
 222    * origins ["http://www.mozilla.org^userContextId=1007",
 223    * "http://www.example.org^userContextId=1007"].
 224    *
 225    * @param aPattern
 226    *        A pattern for the origins whose storages are to be cleared.
 227    *        Currently this is expected to be a JSON representation of the
 228    *        OriginAttributesPatternDictionary defined in ChromeUtils.webidl.
 229    */
 230   [must_use] nsIQuotaRequest
 231   clearStoragesForOriginAttributesPattern(in AString aPattern);
 232
 233   /**
 234    * Removes all storages stored for the given principal. The files may not be
 235    * deleted immediately depending on prohibitive concurrent operations.
 236    *
 237    * @param aPrincipal
 238    *        A principal for the origin whose storages are to be cleared.
 239    * @param aPersistenceType
 240    *        An optional string that tells what persistence type of storages
 241    *        will be cleared.  If omitted (or void), all persistence types will
 242    *        be cleared for the principal.  If a single persistence type
 243    *        ("persistent", "temporary", or "default") is provided, then only
 244    *        that persistence directory will be considered.  Note that
 245    *        "persistent" is different than being "persisted" via persist() and
 246    *        is only for chrome principals.  See bug 1354500 for more info.
 247    *        In general, null is the right thing to pass here.
 248    * @param aClientType
 249    *        An optional string that tells what client type of storages
 250    *        will be cleared.  If omitted (or void), all client types will be
 251    *        cleared for the principal.  If a single client type is provided
 252    *        from Client.h, then only that client's storage will be cleared.
 253    *        If you want to clear multiple client types (but not all), then you
 254    *        must call this method multiple times.
 255    */
 256   [must_use] nsIQuotaRequest
 257   clearStoragesForPrincipal(in nsIPrincipal aPrincipal,
 258                             [optional] in ACString aPersistenceType,
 259                             [optional] in AString aClientType);
 260
 261   /**
 262    * Removes all storages stored for the given prefix. The files may not be
 263    * deleted immediately depending on prohibitive concurrent operations.
 264    *
 265    * Effectively, this clears all possible OriginAttribute suffixes that
 266    * could exist.  So this clears the given origin across all userContextIds,
 267    * in private browsing, all third-party partitioned uses of the origin (by
 268    * way of partitionKey), etc.
 269    *
 270    * @param aPrincipal
 271    *        A prefix for the origins whose storages are to be cleared.
 272    * @param aPersistenceType
 273    *        An optional string that tells what persistence type of storages
 274    *        will be cleared.  If omitted (or void), all persistence types will
 275    *        be cleared for the prefix.  If a single persistence type
 276    *        ("persistent", "temporary", or "default") is provided, then only
 277    *        that persistence directory will be considered.  Note that
 278    *        "persistent" is different than being "persisted" via persist() and
 279    *        is only for chrome principals.  See bug 1354500 for more info.
 280    *        In general, null is the right thing to pass here.
 281    */
 282   [must_use] nsIQuotaRequest
 283   clearStoragesForOriginPrefix(in nsIPrincipal aPrincipal,
 284                             [optional] in ACString aPersistenceType);
 285
 286   /**
 287    * Resets quota and storage management. This can be used to force
 288    * reinitialization of the temp storage, for example when the pref for
 289    * overriding the temp storage limit has changed.
 290    * Be carefull, this invalidates all live storages!
 291    *
 292    * If the dom.quotaManager.testing preference is not true the call will be
 293    * a no-op.
 294    */
 295   [must_use] nsIQuotaRequest
 296   reset();
 297
 298   /**
 299    * Resets all storages stored for the given principal.
 300    *
 301    * If the dom.quotaManager.testing preference is not true the call will be
 302    * a no-op.
 303    *
 304    * @param aPrincipal
 305    *        A principal for the origin whose storages are to be reset.
 306    * @param aPersistenceType
 307    *        An optional string that tells what persistence type of storages
 308    *        will be reset.  If omitted (or void), all persistence types will
 309    *        be cleared for the principal.  If a single persistence type
 310    *        ("persistent", "temporary", or "default") is provided, then only
 311    *        that persistence directory will be considered.  Note that
 312    *        "persistent" is different than being "persisted" via persist() and
 313    *        is only for chrome principals.  See bug 1354500 for more info.
 314    *        In general, null is the right thing to pass here.
 315    * @param aClientType
 316    *        An optional string that tells what client type of storages
 317    *        will be reset.  If omitted (or void), all client types will be
 318    *        cleared for the principal.  If a single client type is provided
 319    *        from Client.h, then only that client's storage will be cleared.
 320    *        If you want to clear multiple client types (but not all), then you
 321    *        must call this method multiple times.
 322    */
 323   [must_use] nsIQuotaRequest
 324   resetStoragesForPrincipal(in nsIPrincipal aPrincipal,
 325                             [optional] in ACString aPersistenceType,
 326                             [optional] in AString aClientType);
 327
 328   /**
 329    * Check if given origin is persisted.
 330    *
 331    * @param aPrincipal
 332    *        A principal for the origin which we want to check.
 333    */
 334   [must_use] nsIQuotaRequest
 335   persisted(in nsIPrincipal aPrincipal);
 336
 337   /**
 338    * Persist given origin.
 339    *
 340    * @param aPrincipal
 341    *        A principal for the origin which we want to persist.
 342    */
 343   [must_use] nsIQuotaRequest
 344   persist(in nsIPrincipal aPrincipal);
 345
 346   /**
 347    * Given an origin, asynchronously calculate its group quota usage and quota
 348    * limit. An origin's group is the set of all origins that share the same
 349    * eTLD+1. This method is intended to be used for our implementation of the
 350    * StorageManager.estimate() method. When we fix bug 1305665 and stop tracking
 351    * quota limits on a group basis, this method will switch to operating on
 352    * origins. Callers should strongly consider whether they want to be using
 353    * getUsageForPrincipal() instead.
 354    *
 355    * This mechanism uses cached quota values and does not perform any I/O on its
 356    * own, but it may be delayed by QuotaManager operations that do need to
 357    * perform I/O on the QuotaManager I/O thread.
 358    *
 359    * @param aPrincipal
 360    *        A principal for the origin (group) which we want to estimate.
 361    */
 362   [must_use] nsIQuotaRequest
 363   estimate(in nsIPrincipal aPrincipal);
 364 };