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 persistent 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   persistentStorageInitialized();
  44
  45   /**
  46    * Check if temporary storage is initialized.
  47    *
  48    * If the dom.quotaManager.testing preference is not true the call will be
  49    * a no-op.
  50    */
  51   [must_use] nsIQuotaRequest
  52   temporaryStorageInitialized();
  53
  54   /**
  55    * Check if temporary group is initialized.
  56    *
  57    * If the dom.quotaManager.testing preference is not true the call will be
  58    * a no-op.
  59    */
  60   [must_use] nsIQuotaRequest
  61   temporaryGroupInitialized(in nsIPrincipal aPrincipal);
  62
  63   /**
  64    * Check if persistent origin is initialized.
  65    *
  66    * If the dom.quotaManager.testing preference is not true the call will be
  67    * a no-op.
  68    *
  69    * @param aPrincipal
  70    *        A principal for the persistent origin whose state is to be checked.
  71    */
  72   [must_use] nsIQuotaRequest
  73   persistentOriginInitialized(in nsIPrincipal aPrincipal);
  74
  75   /**
  76    * Check if temporary origin is initialized.
  77    *
  78    * If the dom.quotaManager.testing preference is not true the call will be
  79    * a no-op.
  80    *
  81    * @param aPersistenceType
  82    *        A string that tells what persistence type will be checked (either
  83    *        "temporary" or "default").
  84    * @param aPrincipal
  85    *        A principal for the temporary origin whose state is to be checked.
  86    */
  87   [must_use] nsIQuotaRequest
  88   temporaryOriginInitialized(in ACString aPersistenceType,
  89                              in nsIPrincipal aPrincipal);
  90
  91   /**
  92    * Initializes storage directory. This can be used in tests to verify
  93    * upgrade methods.
  94    *
  95    * If the dom.quotaManager.testing preference is not true the call will be
  96    * a no-op.
  97    */
  98   [must_use] nsIQuotaRequest
  99   init();
 100
 101   /**
 102    * Initializes persistent storage. This can be used in tests to verify
 103    * persistent storage initialization.
 104    *
 105    * If the dom.quotaManager.testing preference is not true the call will be
 106    * a no-op.
 107    */
 108   [must_use] nsIQuotaRequest
 109   initializePersistentStorage();
 110
 111   /**
 112    * Initializes temporary storage. This can be used in tests to verify
 113    * temporary storage initialization.
 114    *
 115    * If the dom.quotaManager.testing preference is not true the call will be
 116    * a no-op.
 117    */
 118   [must_use] nsIQuotaRequest
 119   initTemporaryStorage();
 120
 121   /**
 122    * Initializes temporary origin directories for the given group. This can be
 123    * used in tests to verify group initialization.
 124    *
 125    * If the dom.quotaManager.testing preference is not true the call will be
 126    * a no-op.
 127    *
 128    * @param aPrincipal
 129    *        A principal for the group whose origin directories are to be
 130    *        initialized.
 131    */
 132   [must_use] nsIQuotaRequest
 133   initializeTemporaryGroup(in nsIPrincipal aPrincipal);
 134
 135   /**
 136    * Initializes persistent origin directory for the given origin. This can be
 137    * used in tests to verify origin initialization.
 138    *
 139    * If the dom.quotaManager.testing preference is not true the call will be
 140    * a no-op.
 141    *
 142    * @param aPrincipal
 143    *        A principal for the origin whose directory is to be initialized.
 144    */
 145   [must_use] nsIQuotaRequest
 146   initializePersistentOrigin(in nsIPrincipal aPrincipal);
 147
 148   /**
 149    * Initializes temporary origin directory for the given origin. This can be
 150    * used in tests to verify origin initialization.
 151    *
 152    * If the dom.quotaManager.testing preference is not true the call will be
 153    * a no-op.
 154    *
 155    * @param aPersistenceType
 156    *        A string that tells what persistence type of origin will be
 157    *        initialized (temporary or default).
 158    *
 159    * @param aPrincipal
 160    *        A principal for the origin whose directory is to be initialized.
 161    *
 162    * @param aCreateIfNonExistent
 163    *        An optional boolean to indicate creation of origin directory if it
 164    *        doesn't exist yet.
 165    */
 166   [must_use] nsIQuotaRequest
 167   initializeTemporaryOrigin(in ACString aPersistenceType,
 168                             in nsIPrincipal aPrincipal,
 169                             [optional] in boolean aCreateIfNonExistent);
 170
 171   /**
 172    * Initializes persistent client directory for the given origin and client.
 173    * This can be used in tests to verify client initialization.
 174    *
 175    * If the dom.quotaManager.testing preference is not true the call will be
 176    * a no-op.
 177    *
 178    * @param aPrincipal
 179    *        A principal for the origin whose client directory is to be
 180    *        initialized.
 181    * @param aClientType
 182    *        A string that tells what client type will be initialized.
 183    */
 184   [must_use] nsIQuotaRequest
 185   initializePersistentClient(in nsIPrincipal aPrincipal,
 186                              in AString aClientType);
 187
 188   /**
 189    * Initializes temporary client directory for the given origin and client.
 190    * This can be used in tests to verify client initialization.
 191    *
 192    * If the dom.quotaManager.testing preference is not true the call will be
 193    * a no-op.
 194    *
 195    * @param aPersistenceType
 196    *        A string that tells what persistence type will be initialized
 197    *        (either "temporary" or "default").
 198    * @param aPrincipal
 199    *        A principal for the origin whose client directory is to be
 200    *        initialized.
 201    * @param aClientType
 202    *        A string that tells what client type will be initialized.
 203    */
 204   [must_use] nsIQuotaRequest
 205   initializeTemporaryClient(in ACString aPersistenceType,
 206                             in nsIPrincipal aPrincipal,
 207                             in AString aClientType);
 208
 209   /**
 210    * Gets full origin metadata cached in memory for the given persistence type
 211    * and origin.
 212    *
 213    * NOTE: This operation may still be delayed by other operations on the QM
 214    *       I/O thread that are peforming I/O.
 215    *
 216    * @param aPersistenceType
 217    *        A string that tells what persistence type will be used for getting
 218    *        the metadata (either "temporary" or "default").
 219    * @param aPrincipal
 220    *        A principal that tells which origin will be used for getting the
 221    *        metadata.
 222    */
 223   [must_use] nsIQuotaRequest
 224   getFullOriginMetadata(in ACString aPersistenceType,
 225                         in nsIPrincipal aPrincipal);
 226
 227   /**
 228    * Schedules an asynchronous callback that will inspect all origins and
 229    * return the total amount of disk space being used by storages for each
 230    * origin separately.
 231    *
 232    * @param aCallback
 233    *        The callback that will be called when the usage is available.
 234    * @param aGetAll
 235    *        An optional boolean to indicate inspection of all origins,
 236    *        including internal ones.
 237    */
 238   [must_use] nsIQuotaUsageRequest
 239   getUsage(in nsIQuotaUsageCallback aCallback,
 240            [optional] in boolean aGetAll);
 241
 242   /**
 243    * Schedules an asynchronous callback that will return the total amount of
 244    * disk space being used by storages for the given origin.
 245    *
 246    * @param aPrincipal
 247    *        A principal for the origin whose usage is being queried.
 248    * @param aCallback
 249    *        The callback that will be called when the usage is available.
 250    * Note:  Origin usage here represents total usage of an origin.
 251    */
 252   [must_use] nsIQuotaUsageRequest
 253   getUsageForPrincipal(in nsIPrincipal aPrincipal,
 254                        in nsIQuotaUsageCallback aCallback);
 255
 256   /**
 257    * Gets usage cached in memory for the given origin.
 258    *
 259    * This mechanism uses cached quota usage and does not perform any I/O on its
 260    * own, but it may be delayed by QuotaManager operations that do need to
 261    * perform I/O on the QuotaManager I/O thread.
 262    *
 263    * @param aPrincipal
 264    *        A principal for the origin whose cached usage is being queried.
 265    * Note:  Origin usage here represents only non-persistent usage of an origin.
 266    */
 267   [must_use] nsIQuotaRequest
 268   getCachedUsageForPrincipal(in nsIPrincipal aPrincipal);
 269
 270   /**
 271    * Asynchronously lists all origins and returns them as plain strings.
 272    */
 273   [must_use] nsIQuotaRequest
 274   listOrigins();
 275
 276   /**
 277    * Removes all storages. The files may not be deleted immediately depending
 278    * on prohibitive concurrent operations.
 279    * Be careful, this removes *all* the data that has ever been stored!
 280    *
 281    * If the dom.quotaManager.testing preference is not true the call will be
 282    * a no-op.
 283    */
 284   [must_use] nsIQuotaRequest
 285   clear();
 286
 287   /**
 288    * Removes all storages stored for private browsing. The files may not be
 289    * deleted immediately depending on prohibitive concurrent operations.  In
 290    * terms of locks, it will get an exclusive multi directory lock for entire
 291    * private repository.
 292    */
 293   [must_use] nsIQuotaRequest
 294   clearStoragesForPrivateBrowsing();
 295
 296   /**
 297    * Removes all storages stored for the given pattern. The files may not be
 298    * deleted immediately depending on prohibitive concurrent operations.  In
 299    * terms of locks, it will get an exclusive multi directory lock for given
 300    * pattern.  For example, given pattern {"userContextId":1007} and set of 3
 301    * origins ["http://www.mozilla.org^userContextId=1007",
 302    * "http://www.example.org^userContextId=1007",
 303    * "http://www.example.org^userContextId=1008"], the method will only lock 2
 304    * origins ["http://www.mozilla.org^userContextId=1007",
 305    * "http://www.example.org^userContextId=1007"].
 306    *
 307    * @param aPattern
 308    *        A pattern for the origins whose storages are to be cleared.
 309    *        Currently this is expected to be a JSON representation of the
 310    *        OriginAttributesPatternDictionary defined in ChromeUtils.webidl.
 311    */
 312   [must_use] nsIQuotaRequest
 313   clearStoragesForOriginAttributesPattern(in AString aPattern);
 314
 315   /**
 316    * Removes all storages stored for the given principal. The files may not be
 317    * deleted immediately depending on prohibitive concurrent operations.
 318    *
 319    * @param aPrincipal
 320    *        A principal for the origin whose storages are to be cleared.
 321    * @param aPersistenceType
 322    *        An optional string that tells what persistence type of storages
 323    *        will be cleared.  If omitted (or void), all persistence types will
 324    *        be cleared for the principal.  If a single persistence type
 325    *        ("persistent", "temporary", or "default") is provided, then only
 326    *        that persistence directory will be considered.  Note that
 327    *        "persistent" is different than being "persisted" via persist() and
 328    *        is only for chrome principals.  See bug 1354500 for more info.
 329    *        In general, null is the right thing to pass here.
 330    */
 331   [must_use] nsIQuotaRequest
 332   clearStoragesForPrincipal(in nsIPrincipal aPrincipal,
 333                             [optional] in ACString aPersistenceType);
 334
 335   /**
 336    * Removes all storages stored for the given client. The files may not be
 337    * deleted immediately depending on prohibitive concurrent operations.
 338    *
 339    * @param aPrincipal
 340    *        A principal for the origin whose storages are to be cleared.
 341    * @param aClientType
 342    *        A string that tells what client type of storages will be cleared.
 343    * @param aPersistenceType
 344    *        An optional string that tells what persistence type of storages
 345    *        will be cleared.  If omitted (or void), all persistence types will
 346    *        be cleared for the principal and client type.  If a single
 347    *        persistence type ("persistent", "temporary", or "default") is
 348    *        provided, then only that persistence directory will be considered.
 349    *        Note that "persistent" is different than being "persisted" via
 350    *        persist() and is only for chrome principals.  See bug 1354500 for
 351    *        more info.  In general, null is the right thing to pass here.
 352    */
 353   [must_use] nsIQuotaRequest
 354   clearStoragesForClient(in nsIPrincipal aPrincipal,
 355                          in AString aClientType,
 356                          [optional] in ACString aPersistenceType);
 357
 358   /**
 359    * Removes all storages stored for the given prefix. The files may not be
 360    * deleted immediately depending on prohibitive concurrent operations.
 361    *
 362    * Effectively, this clears all possible OriginAttribute suffixes that
 363    * could exist.  So this clears the given origin across all userContextIds,
 364    * in private browsing, all third-party partitioned uses of the origin (by
 365    * way of partitionKey), etc.
 366    *
 367    * @param aPrincipal
 368    *        A prefix for the origins whose storages are to be cleared.
 369    * @param aPersistenceType
 370    *        An optional string that tells what persistence type of storages
 371    *        will be cleared.  If omitted (or void), all persistence types will
 372    *        be cleared for the prefix.  If a single persistence type
 373    *        ("persistent", "temporary", or "default") is provided, then only
 374    *        that persistence directory will be considered.  Note that
 375    *        "persistent" is different than being "persisted" via persist() and
 376    *        is only for chrome principals.  See bug 1354500 for more info.
 377    *        In general, null is the right thing to pass here.
 378    */
 379   [must_use] nsIQuotaRequest
 380   clearStoragesForOriginPrefix(in nsIPrincipal aPrincipal,
 381                             [optional] in ACString aPersistenceType);
 382
 383   /**
 384    * Resets quota and storage management. This can be used to force
 385    * reinitialization of the temp storage, for example when the pref for
 386    * overriding the temp storage limit has changed.
 387    * Be carefull, this invalidates all live storages!
 388    *
 389    * If the dom.quotaManager.testing preference is not true the call will be
 390    * a no-op.
 391    */
 392   [must_use] nsIQuotaRequest
 393   reset();
 394
 395   /**
 396    * Resets all storages stored for the given principal.
 397    *
 398    * If the dom.quotaManager.testing preference is not true the call will be
 399    * a no-op.
 400    *
 401    * @param aPrincipal
 402    *        A principal for the origin whose storages are to be reset.
 403    * @param aPersistenceType
 404    *        An optional string that tells what persistence type of storages
 405    *        will be reset.  If omitted (or void), all persistence types will
 406    *        be cleared for the principal.  If a single persistence type
 407    *        ("persistent", "temporary", or "default") is provided, then only
 408    *        that persistence directory will be considered.  Note that
 409    *        "persistent" is different than being "persisted" via persist() and
 410    *        is only for chrome principals.  See bug 1354500 for more info.
 411    *        In general, null is the right thing to pass here.
 412    */
 413   [must_use] nsIQuotaRequest
 414   resetStoragesForPrincipal(in nsIPrincipal aPrincipal,
 415                             [optional] in ACString aPersistenceType);
 416
 417   /**
 418    * Resets all storages stored for the given client.
 419    *
 420    * If the dom.quotaManager.testing preference is not true the call will be
 421    * a no-op.
 422    *
 423    * @param aPrincipal
 424    *        A principal for the origin whose storages are to be reset.
 425    * @param aClientType
 426    *        A string that tells what client type of storages will be reset.
 427    * @param aPersistenceType
 428    *        An optional string that tells what persistence type of storages
 429    *        will be reset.  If omitted (or void), all persistence types will
 430    *        be cleared for the principal and client type.  If a single
 431    *        persistence type ("persistent", "temporary", or "default") is
 432    *        provided, then only that persistence directory will be considered.
 433    *        Note that "persistent" is different than being "persisted" via
 434    *        persist() and is only for chrome principals.  See bug 1354500 for
 435    *        more info.  In general, null is the right thing to pass here.
 436    */
 437   [must_use] nsIQuotaRequest
 438   resetStoragesForClient(in nsIPrincipal aPrincipal,
 439                          in AString aClientType,
 440                          [optional] in ACString aPersistenceType);
 441
 442   /**
 443    * Check if given origin is persisted.
 444    *
 445    * @param aPrincipal
 446    *        A principal for the origin which we want to check.
 447    */
 448   [must_use] nsIQuotaRequest
 449   persisted(in nsIPrincipal aPrincipal);
 450
 451   /**
 452    * Persist given origin.
 453    *
 454    * @param aPrincipal
 455    *        A principal for the origin which we want to persist.
 456    */
 457   [must_use] nsIQuotaRequest
 458   persist(in nsIPrincipal aPrincipal);
 459
 460   /**
 461    * Given an origin, asynchronously calculate its group quota usage and quota
 462    * limit. An origin's group is the set of all origins that share the same
 463    * eTLD+1. This method is intended to be used for our implementation of the
 464    * StorageManager.estimate() method. When we fix bug 1305665 and stop tracking
 465    * quota limits on a group basis, this method will switch to operating on
 466    * origins. Callers should strongly consider whether they want to be using
 467    * getUsageForPrincipal() instead.
 468    *
 469    * This mechanism uses cached quota values and does not perform any I/O on its
 470    * own, but it may be delayed by QuotaManager operations that do need to
 471    * perform I/O on the QuotaManager I/O thread.
 472    *
 473    * @param aPrincipal
 474    *        A principal for the origin (group) which we want to estimate.
 475    */
 476   [must_use] nsIQuotaRequest
 477   estimate(in nsIPrincipal aPrincipal);
 478 };