Source code

Revision control

Line Code
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
 *
 * 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 nsIArray;
interface nsIFile;
interface nsIURI;

/**
 * Application caches can store a set of namespace entries that affect
 * loads from the application cache.  If a load from the cache fails
 * to match an exact cache entry, namespaces entries will be searched
 * for a substring match, and should be applied appropriately.
 */
[scriptable, uuid(96e4c264-2065-4ce9-93bb-43734c62c4eb)]
interface nsIApplicationCacheNamespace : nsISupports
{
    /**
     * Items matching this namespace can be fetched from the network
     * when loading from this cache.  The "data" attribute is unused.
     */
    const unsigned long NAMESPACE_BYPASS = 1 << 0;

    /**
     * Items matching this namespace can be fetched from the network
     * when loading from this cache.  If the load fails, the cache entry
     * specified by the "data" attribute should be loaded instead.
     */
    const unsigned long NAMESPACE_FALLBACK = 1 << 1;

    /**
     * Items matching this namespace should be cached
     * opportunistically.  Successful toplevel loads of documents
     * in this namespace should be placed in the application cache.
     * Namespaces specifying NAMESPACE_OPPORTUNISTIC may also specify
     * NAMESPACE_FALLBACK to supply a fallback entry.
     */
    const unsigned long NAMESPACE_OPPORTUNISTIC = 1 << 2;

    /**
     * Initialize the namespace.
     */
    void init(in unsigned long itemType,
              in ACString namespaceSpec,
              in ACString data);

    /**
     * The namespace type.
     */
    readonly attribute unsigned long itemType;

    /**
     * The prefix of this namespace.  This should be the asciiSpec of the
     * URI prefix.
     */
    readonly attribute ACString namespaceSpec;

    /**
     * Data associated with this namespace, such as a fallback.  URI data should
     * use the asciiSpec of the URI.
     */
    readonly attribute ACString data;
};

/**
 * Application caches store resources for offline use.  Each
 * application cache has a unique client ID for use with
 * nsICacheService::openSession() to access the cache's entries.
 *
 * Each entry in the application cache can be marked with a set of
 * types, as discussed in the WHAT-WG offline applications
 * specification.
 *
 * All application caches with the same group ID belong to a cache
 * group.  Each group has one "active" cache that will service future
 * loads.  Inactive caches will be removed from the cache when they are
 * no longer referenced.
 */
[scriptable, uuid(06568DAE-C374-4383-A122-0CC96C7177F2)]
interface nsIApplicationCache : nsISupports
{
    /**
     * Init this application cache instance to just hold the group ID and
     * the client ID to work just as a handle to the real cache. Used on
     * content process to simplify the application cache code.
     */
    void initAsHandle(in ACString groupId, in ACString clientId);

    /**
     * Entries in an application cache can be marked as one or more of
     * the following types.
     */

    /* This item is the application manifest. */
    const unsigned long ITEM_MANIFEST =      1 << 0;

    /* This item was explicitly listed in the application manifest. */
    const unsigned long ITEM_EXPLICIT =      1 << 1;

    /* This item was navigated in a toplevel browsing context, and
     * named this cache's group as its manifest. */
    const unsigned long ITEM_IMPLICIT =      1 << 2;

    /* This item was added by the dynamic scripting API */
    const unsigned long ITEM_DYNAMIC =       1 << 3;

    /* This item was listed in the application manifest, but named a
     * different cache group as its manifest. */
    const unsigned long ITEM_FOREIGN = 1 << 4;

    /* This item was listed as a fallback entry. */
    const unsigned long ITEM_FALLBACK = 1 << 5;

    /* This item matched an opportunistic cache namespace and was
     * cached accordingly. */
    const unsigned long ITEM_OPPORTUNISTIC = 1 << 6;

    /**
     * URI of the manfiest specifying this application cache.
     **/
    readonly attribute nsIURI manifestURI;

    /**
     * The group ID for this cache group.  It is an internally generated string
     * and cannot be used as manifest URL spec.
     **/
    readonly attribute ACString groupID;

    /**
     * The client ID for this application cache.  Clients can open a
     * session with nsICacheService::createSession() using this client
     * ID and a storage policy of STORE_OFFLINE to access this cache.
     */
    readonly attribute ACString clientID;

    /**
     * TRUE if the cache is the active cache for this group.
     */
    readonly attribute boolean active;

    /**
     * The disk usage of the application cache, in bytes.
     */
    readonly attribute unsigned long usage;

    /**
     * Makes this cache the active application cache for this group.
     * Future loads associated with this group will come from this
     * cache.  Other caches from this cache group will be deactivated.
     */
    void activate();

    /**
     * Discard this application cache.  Removes all cached resources
     * for this cache.  If this is the active application cache for the
     * group, the group will be removed.
     */
    void discard();

    /**
     * Adds item types to a given entry.
     */
    void markEntry(in ACString key, in unsigned long typeBits);

    /**
     * Removes types from a given entry.  If the resulting entry has
     * no types left, the entry is removed.
     */
    void unmarkEntry(in ACString key, in unsigned long typeBits);

    /**
     * Gets the types for a given entry.
     */
    unsigned long getTypes(in ACString key);

    /**
     * Returns any entries in the application cache whose type matches
     * one or more of the bits in typeBits.
     */
    void gatherEntries(in uint32_t typeBits,
                       out unsigned long count,
                       [array, size_is(count)] out string keys);

    /**
     * Add a set of namespace entries to the application cache.
     * @param namespaces
     *        An nsIArray of nsIApplicationCacheNamespace entries.
     */
    void addNamespaces(in nsIArray namespaces);

    /**
     * Get the most specific namespace matching a given key.
     */
    nsIApplicationCacheNamespace getMatchingNamespace(in ACString key);

    /**
     * If set, this offline cache is placed in a different directory
     * than the current application profile.
     */
    readonly attribute nsIFile profileDirectory;
};