netwerk/base/public/nsIApplicationCache.idl

   1 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
   2  *
   3  * ***** BEGIN LICENSE BLOCK *****
   4  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   5  *
   6  * The contents of this file are subject to the Mozilla Public License Version
   7  * 1.1 (the "License"); you may not use this file except in compliance with
   8  * the License. You may obtain a copy of the License at
   9  * http://www.mozilla.org/MPL/
  10  *
  11  * Software distributed under the License is distributed on an "AS IS" basis,
  12  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  13  * for the specific language governing rights and limitations under the
  14  * License.
  15  *
  16  * The Original Code is nsIApplicationCache.idl.
  17  *
  18  * The Initial Developer of the Original Code is
  19  * Mozilla Corporation.
  20  * Portions created by the Initial Developer are Copyright (C) 2008
  21  * the Initial Developer. All Rights Reserved.
  22  *
  23  * Contributor(s):
  24  *   Dave Camp <dcamp@mozilla.com>
  25  *
  26  * Alternatively, the contents of this file may be used under the terms of
  27  * either the GNU General Public License Version 2 or later (the "GPL"), or
  28  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  29  * in which case the provisions of the GPL or the LGPL are applicable instead
  30  * of those above. If you wish to allow use of your version of this file only
  31  * under the terms of either the GPL or the LGPL, and not to allow others to
  32  * use your version of this file under the terms of the MPL, indicate your
  33  * decision by deleting the provisions above and replace them with the notice
  34  * and other provisions required by the GPL or the LGPL. If you do not delete
  35  * the provisions above, a recipient may use your version of this file under
  36  * the terms of any one of the MPL, the GPL or the LGPL.
  37  *
  38  * ***** END LICENSE BLOCK ***** */
  39
  40 #include "nsISupports.idl"
  41
  42 interface nsIArray;
  43
  44 /**
  45  * Application caches can store a set of namespace entries that affect
  46  * loads from the application cache.  If a load from the cache fails
  47  * to match an exact cache entry, namespaces entries will be searched
  48  * for a substring match, and should be applied appropriately.
  49  */
  50 [scriptable, uuid(96e4c264-2065-4ce9-93bb-43734c62c4eb)]
  51 interface nsIApplicationCacheNamespace : nsISupports
  52 {
  53     /**
  54      * Items matching this namespace can be fetched from the network
  55      * when loading from this cache.  The "data" attribute is unused.
  56      */
  57     const unsigned long NAMESPACE_BYPASS = 1 << 0;
  58
  59     /**
  60      * Items matching this namespace can be fetched from the network
  61      * when loading from this cache.  If the load fails, the cache entry
  62      * specified by the "data" attribute should be loaded instead.
  63      */
  64     const unsigned long NAMESPACE_FALLBACK = 1 << 1;
  65
  66     /**
  67      * Items matching this namespace should be cached
  68      * opportunistically.  Successful toplevel loads of documents
  69      * in this namespace should be placed in the application cache.
  70      * Namespaces specifying NAMESPACE_OPPORTUNISTIC may also specify
  71      * NAMESPACE_FALLBACK to supply a fallback entry.
  72      */
  73     const unsigned long NAMESPACE_OPPORTUNISTIC = 1 << 2;
  74
  75     /**
  76      * Initialize the namespace.
  77      */
  78     void init(in unsigned long itemType,
  79               in ACString namespaceSpec,
  80               in ACString data);
  81
  82     /**
  83      * The namespace type.
  84      */
  85     readonly attribute unsigned long itemType;
  86
  87     /**
  88      * The prefix of this namespace.  This should be the asciiSpec of the
  89      * URI prefix.
  90      */
  91     readonly attribute ACString namespaceSpec;
  92
  93     /**
  94      * Data associated with this namespace, such as a fallback.  URI data should
  95      * use the asciiSpec of the URI.
  96      */
  97     readonly attribute ACString data;
  98 };
  99
 100 /**
 101  * Application caches store resources for offline use.  Each
 102  * application cache has a unique client ID for use with
 103  * nsICacheService::openSession() to access the cache's entries.
 104  *
 105  * Each entry in the application cache can be marked with a set of
 106  * types, as discussed in the WHAT-WG offline applications
 107  * specification.
 108  *
 109  * All application caches with the same group ID belong to a cache
 110  * group.  Each group has one "active" cache that will service future
 111  * loads.  Inactive caches will be removed from the cache when they are
 112  * no longer referenced.
 113  */
 114 [scriptable, uuid(1e1a2371-875b-4e57-98ff-a81af1750ca2)]
 115 interface nsIApplicationCache : nsISupports
 116 {
 117     /**
 118      * Entries in an application cache can be marked as one or more of
 119      * the following types.
 120      */
 121
 122     /* This item is the application manifest. */
 123     const unsigned long ITEM_MANIFEST =      1 << 0;
 124
 125     /* This item was explicitly listed in the application manifest. */
 126     const unsigned long ITEM_EXPLICIT =      1 << 1;
 127
 128     /* This item was navigated in a toplevel browsing context, and
 129      * named this cache's group as its manifest. */
 130     const unsigned long ITEM_IMPLICIT =      1 << 2;
 131
 132     /* This item was added by the dynamic scripting API */
 133     const unsigned long ITEM_DYNAMIC =       1 << 3;
 134
 135     /* This item was listed in the application manifest, but named a
 136      * different cache group as its manifest. */
 137     const unsigned long ITEM_FOREIGN = 1 << 4;
 138
 139     /* This item was listed as a fallback entry. */
 140     const unsigned long ITEM_FALLBACK = 1 << 5;
 141
 142     /* This item matched an opportunistic cache namespace and was
 143      * cached accordingly. */
 144     const unsigned long ITEM_OPPORTUNISTIC = 1 << 6;
 145
 146     /**
 147      * The group ID for this cache group.  This is the URI of the
 148      * manifest file.
 149      **/
 150     readonly attribute ACString groupID;
 151
 152     /**
 153      * The client ID for this application cache.  Clients can open a
 154      * session with nsICacheService::createSession() using this client
 155      * ID and a storage policy of STORE_OFFLINE to access this cache.
 156      */
 157     readonly attribute ACString clientID;
 158
 159     /**
 160      * TRUE if the cache is the active cache for this group.
 161      */
 162     readonly attribute boolean active;
 163
 164     /**
 165      * Makes this cache the active application cache for this group.
 166      * Future loads associated with this group will come from this
 167      * cache.  Other caches from this cache group will be deactivated.
 168      */
 169     void activate();
 170
 171     /**
 172      * Discard this application cache.  Removes all cached resources
 173      * for this cache.  If this is the active application cache for the
 174      * group, the group will be removed.
 175      */
 176     void discard();
 177
 178     /**
 179      * Adds item types to a given entry.
 180      */
 181     void markEntry(in ACString key, in unsigned long typeBits);
 182
 183     /**
 184      * Removes types from a given entry.  If the resulting entry has
 185      * no types left, the entry is removed.
 186      */
 187     void unmarkEntry(in ACString key, in unsigned long typeBits);
 188
 189     /**
 190      * Gets the types for a given entry.
 191      */
 192     unsigned long getTypes(in ACString key);
 193
 194     /**
 195      * Returns any entries in the application cache whose type matches
 196      * one or more of the bits in typeBits.
 197      */
 198     void gatherEntries(in PRUint32 typeBits,
 199                        out unsigned long count,
 200                        [array, size_is(count)] out string keys);
 201
 202     /**
 203      * Add a set of namespace entries to the application cache.
 204      * @param namespaces
 205      *        An nsIArray of nsIApplicationCacheNamespace entries.
 206      */
 207     void addNamespaces(in nsIArray namespaces);
 208
 209     /**
 210      * Get the most specific namespace matching a given key.
 211      */
 212     nsIApplicationCacheNamespace getMatchingNamespace(in ACString key);
 213 };