nsIDataStorage.idl (5603B)
1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- 2 * 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 nsIDataStorage; 10 interface nsIDataStorageItem; 11 12 [scriptable, uuid(71b49926-fd4e-43e2-ab8d-d9b049413c0b)] 13 interface nsIDataStorageManager : nsISupports { 14 // Because of its specialized nature, nsIDataStorage instances are limited to 15 // the following pre-defined set. To add a new type of data storage, add an 16 // entry to the enum and get review from someone on the security and privacy 17 // engineering team. 18 cenum DataStorage : 8 { 19 AlternateServices, 20 ClientAuthRememberList, 21 SiteSecurityServiceState, 22 }; 23 24 nsIDataStorage get(in nsIDataStorageManager_DataStorage dataStorage); 25 }; 26 27 /** 28 * nsIDataStorage is a threadsafe, generic, narrow string-based hash map that 29 * persists data on disk and additionally handles private (temporary) data. 30 * The file format is portable across architectures. If used in a context where 31 * there is no profile directory, data will not be persisted. 32 * 33 * Its lifecycle is as follows: 34 * - Use nsIDataStorageManager to obtain the nsIDataStorage of a particular 35 * purpose. Its backing file will be read on a background thread. 36 * - Should the profile directory not be available, (e.g. in xpcshell), 37 * nsIDataStorage will not read any persistent data. 38 * - When data in the nsIDataStorage changes, those changes will be written 39 * to the backing file on a background thread. If the program crashes or is 40 * closed unexpectedly before the write completes, the changes may be lost. 41 * If the changes were an update to previously stored data, the original data 42 * may be lost as well. A checksum associated with each entry helps identify 43 * incompletely written entries. 44 * - nsIDataStorage does not support transactions. Each entry is independent of 45 * the others. 46 * - When an nsIDataStorage instance observes the topic "profile-before-change" 47 * in anticipation of shutdown, no more changes will be written to the 48 * backing file. To ensure no data is lost, users of nsIDataStorage should 49 * not attempt to change any data after this point. 50 * If "profile-before-change" is not observed, this happens upon observing 51 * "xpcom-shutdown-threads". 52 * - To prevent unbounded memory and disk use, the number of entries in each 53 * table is limited to 2048. Evictions are handled in by a modified LRU scheme 54 * (see implementation comments). 55 * - Note that instances of nsIDataStorage have long lifetimes because they are 56 * strong observers of events and won't go away until the observer service 57 * does. 58 * 59 * For each key/value: 60 * - The key must have a length no more than 256. 61 * - The value have a length no more than 1024 (24 for the site security 62 * service state). 63 * The length limits are to prevent unbounded disk and memory usage, and 64 * nsIDataStorage will throw/return an error if given keys or values of 65 * excess length. 66 * Take care when storing data containing bytes that may be 0. When read 67 * from disk, all trailing 0 bytes from keys and values are stripped. 68 */ 69 [scriptable, uuid(fcbb5ec4-7134-4069-91c6-9378eff51e03)] 70 interface nsIDataStorage : nsISupports { 71 /** 72 * Data that is Persistent is saved on disk. Data that is Private is not 73 * saved. Private is meant to only be set and accessed from private contexts. 74 * It will be cleared upon observing the event "last-pb-context-exited". 75 * Data that is temporary is also not saved, but may be accessed from 76 * non-private contexts. Temporary data is dropped at shutdown. 77 */ 78 cenum DataType : 8 { 79 Persistent, 80 Private, 81 Temporary, 82 }; 83 84 // Given a key and a type of data, returns a value. Returns 85 // NS_ERROR_NOT_AVAILABLE if the key is not present for that type of data. 86 // This operation may block the current thread until the background task 87 // reading the backing file from disk has completed. 88 ACString get(in ACString key, in nsIDataStorage_DataType type); 89 90 // Give a key, value, and type of data, adds an entry as appropriate. 91 // Updates existing entries. 92 // This operation may block the current thread until the background task 93 // reading the backing file from disk has completed. 94 void put(in ACString key, in ACString value, in nsIDataStorage_DataType type); 95 96 // Given a key and type of data, removes an entry if present. 97 // This operation may block the current thread until the background task 98 // reading the backing file from disk has completed. 99 void remove(in ACString key, in nsIDataStorage_DataType type); 100 101 // Removes all entries of all types of data. 102 // This operation may block the current thread until the background task 103 // reading the backing file from disk has completed. 104 void clear(); 105 106 // Returns true if this data storage is ready to be used. To avoid blocking 107 // when calling other nsIDataStorage functions, callers may wish to first 108 // ensure this function returns true. 109 boolean isReady(); 110 111 // Read all of the data items. 112 // This operation may block the current thread until the background task 113 // reading the backing file from disk has completed. 114 Array<nsIDataStorageItem> getAll(); 115 }; 116 117 [scriptable, uuid(4501f984-0e3a-4199-a67e-7753649e93f1)] 118 interface nsIDataStorageItem : nsISupports { 119 readonly attribute ACString key; 120 readonly attribute ACString value; 121 readonly attribute nsIDataStorage_DataType type; 122 };