122 lines
5.5 KiB
Text
122 lines
5.5 KiB
Text
/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
|
|
*
|
|
* This Source Code Form is subject to the terms of the Mozilla Public
|
|
* License, v. 2.0. If a copy of the MPL was not distributed with this
|
|
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
|
|
|
|
#include "nsISupports.idl"
|
|
|
|
interface nsIDataStorage;
|
|
interface nsIDataStorageItem;
|
|
|
|
[scriptable, uuid(71b49926-fd4e-43e2-ab8d-d9b049413c0b)]
|
|
interface nsIDataStorageManager : nsISupports {
|
|
// Because of its specialized nature, nsIDataStorage instances are limited to
|
|
// the following pre-defined set. To add a new type of data storage, add an
|
|
// entry to the enum and get review from someone on the security and privacy
|
|
// engineering team.
|
|
cenum DataStorage : 8 {
|
|
AlternateServices,
|
|
ClientAuthRememberList,
|
|
SiteSecurityServiceState,
|
|
};
|
|
|
|
nsIDataStorage get(in nsIDataStorageManager_DataStorage dataStorage);
|
|
};
|
|
|
|
/**
|
|
* nsIDataStorage is a threadsafe, generic, narrow string-based hash map that
|
|
* persists data on disk and additionally handles private (temporary) data.
|
|
* The file format is portable across architectures. If used in a context where
|
|
* there is no profile directory, data will not be persisted.
|
|
*
|
|
* Its lifecycle is as follows:
|
|
* - Use nsIDataStorageManager to obtain the nsIDataStorage of a particular
|
|
* purpose. Its backing file will be read on a background thread.
|
|
* - Should the profile directory not be available, (e.g. in xpcshell),
|
|
* nsIDataStorage will not read any persistent data.
|
|
* - When data in the nsIDataStorage changes, those changes will be written
|
|
* to the backing file on a background thread. If the program crashes or is
|
|
* closed unexpectedly before the write completes, the changes may be lost.
|
|
* If the changes were an update to previously stored data, the original data
|
|
* may be lost as well. A checksum associated with each entry helps identify
|
|
* incompletely written entries.
|
|
* - nsIDataStorage does not support transactions. Each entry is independent of
|
|
* the others.
|
|
* - When an nsIDataStorage instance observes the topic "profile-before-change"
|
|
* in anticipation of shutdown, no more changes will be written to the
|
|
* backing file. To ensure no data is lost, users of nsIDataStorage should
|
|
* not attempt to change any data after this point.
|
|
* If "profile-before-change" is not observed, this happens upon observing
|
|
* "xpcom-shutdown-threads".
|
|
* - To prevent unbounded memory and disk use, the number of entries in each
|
|
* table is limited to 2048. Evictions are handled in by a modified LRU scheme
|
|
* (see implementation comments).
|
|
* - Note that instances of nsIDataStorage have long lifetimes because they are
|
|
* strong observers of events and won't go away until the observer service
|
|
* does.
|
|
*
|
|
* For each key/value:
|
|
* - The key must have a length no more than 256.
|
|
* - The value have a length no more than 1024 (24 for the site security
|
|
* service state).
|
|
* The length limits are to prevent unbounded disk and memory usage, and
|
|
* nsIDataStorage will throw/return an error if given keys or values of
|
|
* excess length.
|
|
* Take care when storing data containing bytes that may be 0. When read
|
|
* from disk, all trailing 0 bytes from keys and values are stripped.
|
|
*/
|
|
[scriptable, uuid(fcbb5ec4-7134-4069-91c6-9378eff51e03)]
|
|
interface nsIDataStorage : nsISupports {
|
|
/**
|
|
* Data that is Persistent is saved on disk. Data that is Private is not
|
|
* saved. Private is meant to only be set and accessed from private contexts.
|
|
* It will be cleared upon observing the event "last-pb-context-exited".
|
|
* Data that is temporary is also not saved, but may be accessed from
|
|
* non-private contexts. Temporary data is dropped at shutdown.
|
|
*/
|
|
cenum DataType : 8 {
|
|
Persistent,
|
|
Private,
|
|
Temporary,
|
|
};
|
|
|
|
// Given a key and a type of data, returns a value. Returns
|
|
// NS_ERROR_NOT_AVAILABLE if the key is not present for that type of data.
|
|
// This operation may block the current thread until the background task
|
|
// reading the backing file from disk has completed.
|
|
ACString get(in ACString key, in nsIDataStorage_DataType type);
|
|
|
|
// Give a key, value, and type of data, adds an entry as appropriate.
|
|
// Updates existing entries.
|
|
// This operation may block the current thread until the background task
|
|
// reading the backing file from disk has completed.
|
|
void put(in ACString key, in ACString value, in nsIDataStorage_DataType type);
|
|
|
|
// Given a key and type of data, removes an entry if present.
|
|
// This operation may block the current thread until the background task
|
|
// reading the backing file from disk has completed.
|
|
void remove(in ACString key, in nsIDataStorage_DataType type);
|
|
|
|
// Removes all entries of all types of data.
|
|
// This operation may block the current thread until the background task
|
|
// reading the backing file from disk has completed.
|
|
void clear();
|
|
|
|
// Returns true if this data storage is ready to be used. To avoid blocking
|
|
// when calling other nsIDataStorage functions, callers may wish to first
|
|
// ensure this function returns true.
|
|
boolean isReady();
|
|
|
|
// Read all of the data items.
|
|
// This operation may block the current thread until the background task
|
|
// reading the backing file from disk has completed.
|
|
Array<nsIDataStorageItem> getAll();
|
|
};
|
|
|
|
[scriptable, uuid(4501f984-0e3a-4199-a67e-7753649e93f1)]
|
|
interface nsIDataStorageItem : nsISupports {
|
|
readonly attribute ACString key;
|
|
readonly attribute ACString value;
|
|
readonly attribute nsIDataStorage_DataType type;
|
|
};
|