/* -*- 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".
*/
cenum DataType : 8 {
Persistent,
Private,
};
// 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;
};
