security/manager/ssl/nsIDataStorage.idl

   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    */
  76   cenum DataType : 8 {
  77     Persistent,
  78     Private,
  79   };
  80
  81   // Given a key and a type of data, returns a value. Returns
  82   // NS_ERROR_NOT_AVAILABLE if the key is not present for that type of data.
  83   // This operation may block the current thread until the background task
  84   // reading the backing file from disk has completed.
  85   ACString get(in ACString key, in nsIDataStorage_DataType type);
  86
  87   // Give a key, value, and type of data, adds an entry as appropriate.
  88   // Updates existing entries.
  89   // This operation may block the current thread until the background task
  90   // reading the backing file from disk has completed.
  91   void put(in ACString key, in ACString value, in nsIDataStorage_DataType type);
  92
  93   // Given a key and type of data, removes an entry if present.
  94   // This operation may block the current thread until the background task
  95   // reading the backing file from disk has completed.
  96   void remove(in ACString key, in nsIDataStorage_DataType type);
  97
  98   // Removes all entries of all types of data.
  99   // This operation may block the current thread until the background task
 100   // reading the backing file from disk has completed.
 101   void clear();
 102
 103   // Returns true if this data storage is ready to be used. To avoid blocking
 104   // when calling other nsIDataStorage functions, callers may wish to first
 105   // ensure this function returns true.
 106   boolean isReady();
 107
 108   // Read all of the data items.
 109   // This operation may block the current thread until the background task
 110   // reading the backing file from disk has completed.
 111   Array<nsIDataStorageItem> getAll();
 112 };
 113
 114 [scriptable, uuid(4501f984-0e3a-4199-a67e-7753649e93f1)]
 115 interface nsIDataStorageItem : nsISupports {
 116   readonly attribute ACString key;
 117   readonly attribute ACString value;
 118   readonly attribute nsIDataStorage_DataType type;
 119 };