1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/dom/interfaces/storage/nsIDOMStorageManager.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,120 @@
1.4 +/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +
1.11 +interface nsIDOMStorage;
1.12 +interface nsIPrincipal;
1.13 +interface nsIURI;
1.14 +
1.15 +/**
1.16 + * General purpose interface that has two implementations, for localStorage
1.17 + * resp. sessionStorage with "@mozilla.org/dom/localStorage-manager;1" resp.
1.18 + * "@mozilla.org/dom/sessionStorage-manager;1" contract IDs.
1.19 + */
1.20 +[scriptable, uuid(96dd7614-fcc8-4745-9a1d-52f44dea8818)]
1.21 +interface nsIDOMStorageManager : nsISupports
1.22 +{
1.23 + /**
1.24 + * This starts async preloading of a storage cache for scope
1.25 + * defined by the principal.
1.26 + *
1.27 + * @param aFirstPartyIsolationURI
1.28 + * First party URI to bound storage to.
1.29 + * @param aPrincipal
1.30 + * Principal to bound storage to.
1.31 + */
1.32 + void precacheStorage(in nsIPrincipal aPrincipal);
1.33 + void precacheStorageForFirstParty(in nsIURI aFirstPartyIsolationURI,
1.34 + in nsIPrincipal aPrincipal);
1.35 +
1.36 + /**
1.37 + * Returns instance of DOM storage object for given principal.
1.38 + * A new object is always returned and it is ensured there is
1.39 + * a storage for the scope created.
1.40 + *
1.41 + * @param aFirstPartyIsolationURI
1.42 + * First party URI to bound storage to.
1.43 + * @param aPrincipal
1.44 + * Principal to bound storage to.
1.45 + * @param aDocumentURI
1.46 + * URL of the demanding document, used for DOM storage event only.
1.47 + * @param aPrivate
1.48 + * Whether the demanding document is running in Private Browsing mode or not.
1.49 + */
1.50 + nsIDOMStorage createStorage(in nsIPrincipal aPrincipal,
1.51 + in DOMString aDocumentURI,
1.52 + [optional] in bool aPrivate);
1.53 + nsIDOMStorage createStorageForFirstParty(in nsIURI aFirstPartyIsolationURI,
1.54 + in nsIPrincipal aPrincipal,
1.55 + in DOMString aDocumentURI,
1.56 + [optional] in bool aPrivate);
1.57 + /**
1.58 + * Returns instance of DOM storage object for given principal.
1.59 + * If there is no storage managed for the scope, then null is returned and
1.60 + * no object is created. Otherwise, an object (new) for the existing storage
1.61 + * scope is returned.
1.62 + *
1.63 + * @param aPrincipal
1.64 + * Principal to bound storage to.
1.65 + * @param aPrivate
1.66 + * Whether the demanding document is running in Private Browsing mode or not.
1.67 + */
1.68 + nsIDOMStorage getStorage(in nsIPrincipal aPrincipal,
1.69 + [optional] in bool aPrivate);
1.70 + nsIDOMStorage getStorageForFirstParty(in nsIURI aFirstPartyIsolationURI,
1.71 + in nsIPrincipal aPrincipal,
1.72 + [optional] in bool aPrivate);
1.73 +
1.74 + /**
1.75 + * Clones given storage into this storage manager.
1.76 + *
1.77 + * @param aStorageToCloneFrom
1.78 + * The storage to copy all items from into this manager. Manager will then
1.79 + * return a new and independent object that contains snapshot of data from
1.80 + * the moment this method was called. Modification to this new object will
1.81 + * not affect the original storage content we cloned from and vice versa.
1.82 + */
1.83 + void cloneStorage(in nsIDOMStorage aStorageToCloneFrom);
1.84 +
1.85 + /**
1.86 + * Returns true if the storage belongs to the given principal and is managed
1.87 + * (i.e. has been created and is cached) by this storage manager.
1.88 + *
1.89 + * @param aFirstPartyIsolationURI
1.90 + * First party URI to check the storage against.
1.91 + * @param aPrincipal
1.92 + * Principal to check the storage against.
1.93 + * @param aStorage
1.94 + * The storage object to examine.
1.95 + *
1.96 + * @result
1.97 + * true when the storage object is bound with the principal and is managed
1.98 + * by this storage manager.
1.99 + * false otherwise
1.100 + */
1.101 + bool checkStorage(in nsIPrincipal aPrincipal,
1.102 + in nsIDOMStorage aStorage);
1.103 + bool checkStorageForFirstParty(in nsIURI aFirstPartyIsolationURI,
1.104 + in nsIPrincipal aPrincipal,
1.105 + in nsIDOMStorage aStorage);
1.106 +
1.107 + /**
1.108 + * @deprecated
1.109 + *
1.110 + * Returns instance of localStorage object for aURI's origin.
1.111 + * This method ensures there is always only a single instance
1.112 + * for a single origin.
1.113 + *
1.114 + * Currently just forwards to the createStorage method of this
1.115 + * interface.
1.116 + *
1.117 + * Extension developers are strongly encouraged to use getStorage
1.118 + * or createStorage method instead.
1.119 + */
1.120 + nsIDOMStorage getLocalStorageForPrincipal(in nsIPrincipal aPrincipal,
1.121 + in DOMString aDocumentURI,
1.122 + [optional] in bool aPrivate);
1.123 +};
