/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- * * ***** BEGIN LICENSE BLOCK ***** * Version: MPL 1.1/GPL 2.0/LGPL 2.1 * * The contents of this file are subject to the Mozilla Public License Version * 1.1 (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * http://www.mozilla.org/MPL/ * * Software distributed under the License is distributed on an "AS IS" basis, * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License * for the specific language governing rights and limitations under the * License. * * The Original Code is nsIOfflineCacheSession.idl. * * The Initial Developer of the Original Code is * Mozilla Corporation. * Portions created by the Initial Developer are Copyright (C) 2007 * the Initial Developer. All Rights Reserved. * * Contributor(s): * Dave Camp * * Alternatively, the contents of this file may be used under the terms of * either the GNU General Public License Version 2 or later (the "GPL"), or * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), * in which case the provisions of the GPL or the LGPL are applicable instead * of those above. If you wish to allow use of your version of this file only * under the terms of either the GPL or the LGPL, and not to allow others to * use your version of this file under the terms of the MPL, indicate your * decision by deleting the provisions above and replace them with the notice * and other provisions required by the GPL or the LGPL. If you do not delete * the provisions above, a recipient may use your version of this file under * the terms of any one of the MPL, the GPL or the LGPL. * * ***** END LICENSE BLOCK ***** */ #include "nsISupports.idl" #include "nsICache.idl" /** * The offline cache is meant to reliably store resources for * offline use. The expected semantics are: * * a) Once populated, the cache will not evict an application resource * unless explicitly asked. * * b) Resources no longer in use by the application should be evicted. * * c) If the cache fills up, new entries should be rejected rather * than throwing out old ones. * * The offline cache uses domains to concretely represent an * application. It maintains a list of resources to be pinned for * each domain. This list is separate from actual cache * population - the caller is still responsible for placing items * in the cache, and ownership can be declared without a * corresponding entry. * * A key can optionally be associated with a specific URI within * the domain. */ [scriptable, uuid(3a33e268-4175-4440-a933-89d461c86c5f)] interface nsIOfflineCacheSession : nsISupports { /** * Gets the list of owner domains in the cache. * * @param count * The number of domains returned * @param uris * The domains that own resources in the cache */ void getOwnerDomains(out unsigned long count, [array, size_is(count)]out string domains); /** * Gets the list of owner URIs associated with a domain. * * @param ownerAsciiDomain * The domain to query * !! IMPORTANT !! : This must be ascii encoded host - nsIURI.asciiHost * @param count * The number of uris returned * @param uris * The uris in this domain that own resources */ void getOwnerURIs(in ACString ownerAsciiDomain, out unsigned long count, [array, size_is(count)]out string uris); /** * Sets the resources owned by a given domain/URI pair. * * Setting a list will remove any resources previously owned by this * domain/URI pair. * * A key can be added while there is no associated entry. When * an entry is created with this key, it will be owned by the * domain/URI pair. * * @param ownerAsciiDomain * The domain that owns the resources * !! IMPORTANT !! : This must be ascii encoded host - nsIURI.asciiHost * @param ownerAsciiKey * The specific key that owns the resources. You may use * ascii encoded URI spec of the owner - nsIURI.asciiSpec. * This can be empty if none specifically owns the resources. * @param count * The number of keys in keys. * @param keys * The keys that the domain/URI pair own. This can be empty to * clear ownership for the domain/URI pair. */ void setOwnedKeys(in ACString ownerAsciiDomain, in ACString ownerAsciiKey, in unsigned long count, [array, size_is(count)]in string keys); /** * Gets the list of resources owned by a given domain/URI pair. * * @param ownerAsciiDomain * The domain that owns the resources * !! IMPORTANT !! : This must be ascii encoded host - nsIURI.asciiHost * @param ownerAsciiKey * The specific key that owns the resources. You may use * ascii encoded URI spec of the owner - nsIURI.asciiSpec. * This can be empty if none specifically owns the resources. * @param count * The number of keys in keys. * @param keys * The keys that the domain/URI pair own. */ void getOwnedKeys(in ACString ownerAsciiDomain, in ACString ownerAsciiKey, out unsigned long count, [array, size_is(count)]out string keys); /** * Adds an owned key to a domain/URI pair. * * A key can be added while there is no associated entry. When * an entry is created with this key, it will be owned by the * domain/URI pair. * * @param ownerAsciiDomain * The domain that owns the resources * !! IMPORTANT !! : This must be ascii encoded host - nsIURI.asciiHost * @param ownerAsciiKey * The specific key that owns the resources. You may use * ascii encoded URI spec of the owner - nsIURI.asciiSpec. * This can be empty if none specifically owns the resources. * @param key * The key to add. */ void addOwnedKey(in ACString ownerAsciiDomain, in ACString ownerAsciiKey, in ACString key); /** * Removes an owned key from a domain/URI pair. * * If the key does not exist, an NS_ERROR_NOT_AVAILABLE exception * will be thrown. * * @param ownerAsciiDomain * The domain that owns the resources * !! IMPORTANT !! : This must be ascii encoded host - nsIURI.asciiHost * @param ownerAsciiKey * The specific key that owns the resources. You may use * ascii encoded URI spec of the owner - nsIURI.asciiSpec. * This can be empty if none specifically owns the resources. * @param key The key to remove. */ void removeOwnedKey(in ACString ownerAsciiDomain, in ACString ownerAsciiKey, in ACString key); /** * Checks whether a key is owned by a given domain/URI pair. * * @param ownerAsciiDomain * The domain that owns the resources * !! IMPORTANT !! : This must be ascii encoded host - nsIURI.asciiHost * @param ownerAsciiKey * The specific key that owns the resources. You may use * ascii encoded URI spec of the owner - nsIURI.asciiSpec. * This can be empty if none specifically owns the resources. * @param key The key to check */ boolean keyIsOwned(in ACString ownerAsciiDomain, in ACString ownerAsciiKey, in ACString key); /** * Remove all keys owned by a domain, including keys owned by * a specific URI. * * @param ownerAsciiDomain * The domain for which keys should be removed * !! IMPORTANT !! : This must be ascii encoded host - nsIURI.asciiHost */ void clearKeysOwnedByDomain(in ACString ownerAsciiDomain); /** * Get the number of bytes used in the cache by a domain. * * @param domain The domain to check. */ unsigned long getDomainUsage(in ACString ownerDomain); /** * Evict all entries that are not owned by a domain. */ void evictUnownedEntries(); /** * Merge the items from a temporary clientID in to this client. This lets * offline cache updates accumulate in a temporary client and be moved * in all at once. * * Entries in the temporary client will replace any entries in this client * with the same cache key. * * Ownership lists for a given domain/URI pair from the temporary client * will replace ownership lists for the same domain/URI pair. */ void mergeTemporaryClientID(in ACString temporaryClientID); };