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