Source code
Revision control
Copy as Markdown
Other Tools
/* 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
#include "nsISupports.idl"
interface mozIExtensionStorageCallback;
interface nsIFile;
interface nsIVariant;
// Implements the operations needed to support the `StorageArea` WebExtension
// API.
[scriptable, uuid(d8eb3ff1-9b4b-435a-99ca-5b8cbaba2420)]
interface mozIExtensionStorageArea : nsISupports {
// These constants are exposed by the rust crate, but it's not worth the
// effort of jumping through the hoops to get them exposed to the JS
// code in a sane way - so we just duplicate them here. We should consider a
// test that checks they match the rust code.
// This interface is agnostic WRT the area, so we prefix the constants with
// the area - it's the consumer of this interface which knows what to use.
const unsigned long SYNC_QUOTA_BYTES = 102400;
const unsigned long SYNC_QUOTA_BYTES_PER_ITEM = 8192;
const unsigned long SYNC_MAX_ITEMS = 512;
// Sets one or more key-value pairs specified in `json` for the
// `extensionId`. If the `callback` implements
// `mozIExtensionStorageListener`, its `onChange`
// method will be called with the new and old values.
void set(in AUTF8String extensionId,
in AUTF8String json,
in mozIExtensionStorageCallback callback);
// Returns the value for the `key` in the storage area for the
// `extensionId`. `key` must be a JSON string containing either `null`,
// an array of string key names, a single string key name, or an object
// where the properties are the key names, and the values are the defaults
// if the key name doesn't exist in the storage area.
//
// If `get()` fails due to the quota being exceeded, the exception will
// have a result code of NS_ERROR_DOM_QUOTA_EXCEEDED_ERR (==0x80530016)
void get(in AUTF8String extensionId,
in AUTF8String key,
in mozIExtensionStorageCallback callback);
// Removes the `key` from the storage area for the `extensionId`. If `key`
// exists and the `callback` implements `mozIExtensionStorageListener`, its
// `onChanged` method will be called with the removed key-value pair.
void remove(in AUTF8String extensionId,
in AUTF8String key,
in mozIExtensionStorageCallback callback);
// Removes all keys from the storage area for the `extensionId`. If
// `callback` implements `mozIExtensionStorageListener`, its `onChange`
// method will be called with all removed key-value pairs.
void clear(in AUTF8String extensionId,
in mozIExtensionStorageCallback callback);
// Gets the number of bytes in use for the specified keys.
void getBytesInUse(in AUTF8String extensionId,
in AUTF8String keys,
in mozIExtensionStorageCallback callback);
// Gets and clears the information about the migration from the kinto
// database into the rust one. As "and clears" indicates, this will
// only produce a non-empty the first time it's called after a
// migration (which, hopefully, should only happen once).
void takeMigrationInfo(in mozIExtensionStorageCallback callback);
};
// Implements additional methods for setting up and tearing down the underlying
// database connection for a storage area. This is a separate interface because
// these methods are not part of the `StorageArea` API, and have restrictions on
// when they can be called.
[scriptable, uuid(2b008295-1bcc-4610-84f1-ad4cab2fa9ee)]
interface mozIConfigurableExtensionStorageArea : nsISupports {
// Sets up the storage area. An area can only be configured once; calling
// `configure` multiple times will throw. `configure` must also be called
// before any of the `mozIExtensionStorageArea` methods, or they'll fail
// with errors.
// The second param is the path to the kinto database file from which we
// should migrate. This should always be specified even when there's a
// chance the file doesn't exist.
void configure(in nsIFile databaseFile, in nsIFile kintoFile);
// Tears down the storage area, closing the backing database connection.
// This is called automatically when Firefox shuts down. Once a storage area
// has been shut down, all its methods will fail with errors. If `configure`
// hasn't been called for this area yet, `teardown` is a no-op.
void teardown(in mozIExtensionStorageCallback callback);
};
// Implements additional methods for syncing a storage area. This is a separate
// interface because these methods are not part of the `StorageArea` API, and
// have restrictions on when they can be called.
[scriptable, uuid(6dac82c9-1d8a-4893-8c0f-6e626aef802c)]
interface mozISyncedExtensionStorageArea : nsISupports {
// If a sync is in progress, this method fetches pending change
// notifications for all extensions whose storage areas were updated.
// `callback` should implement `mozIExtensionStorageListener` to forward
// the records to `storage.onChanged` listeners. This method should only
// be called by Sync, after `mozIBridgedSyncEngine.apply` and before
// `syncFinished`. It fetches nothing if called at any other time.
void fetchPendingSyncChanges(in mozIExtensionStorageCallback callback);
};
// A listener for storage area notifications.
[scriptable, uuid(8cb3c7e4-d0ca-4353-bccd-2673b4e11510)]
interface mozIExtensionStorageListener : nsISupports {
// Notifies that an operation has data to pass to `storage.onChanged`
// listeners for the given `extensionId`. `json` is a JSON array of listener
// infos. If an operation affects multiple extensions, this method will be
// called multiple times, once per extension.
void onChanged(in AUTF8String extensionId, in AUTF8String json);
};
// A generic callback for a storage operation. Either `handleSuccess` or
// `handleError` is guaranteed to be called once.
[scriptable, uuid(870dca40-6602-4748-8493-c4253eb7f322)]
interface mozIExtensionStorageCallback : nsISupports {
// Called when the operation completes. Operations that return a result,
// like `get`, will pass a `UTF8String` variant. Those that don't return
// anything, like `set` or `remove`, will pass a `null` variant.
void handleSuccess(in nsIVariant result);
// Called when the operation fails.
void handleError(in nsresult code, in AUTF8String message);
};