The Tor Browser / file comparison

comparison: uriloader/prefetch/nsIOfflineCacheUpdate.idl

uriloader/prefetch/nsIOfflineCacheUpdate.idl

branch
TOR_BUG_9701
changeset 8
97036ab72558
equal deleted inserted replaced
-1:000000000000 0:b9ce33f2cb7c
1 /* -*- mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /* This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this
4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
5
6 #include "nsISupports.idl"
7
8 interface nsIURI;
9 interface nsIDOMWindow;
10 interface nsIDOMNode;
11 interface nsIDOMDocument;
12 interface nsIOfflineCacheUpdate;
13 interface nsIPrincipal;
14 interface nsIPrefBranch;
15 interface nsIApplicationCache;
16 interface nsIFile;
17 interface nsIObserver;
18
19 [scriptable, uuid(47360d57-8ef4-4a5d-8865-1a27a739ad1a)]
20 interface nsIOfflineCacheUpdateObserver : nsISupports {
21 const unsigned long STATE_ERROR = 1;
22 const unsigned long STATE_CHECKING = 2;
23 const unsigned long STATE_NOUPDATE = 3;
24 const unsigned long STATE_OBSOLETE = 4;
25 const unsigned long STATE_DOWNLOADING = 5;
26 const unsigned long STATE_ITEMSTARTED = 6;
27 const unsigned long STATE_ITEMCOMPLETED = 7;
28 const unsigned long STATE_ITEMPROGRESS = 8;
29 const unsigned long STATE_FINISHED = 10;
30
31 /**
32 * aUpdate has changed its state.
33 *
34 * @param aUpdate
35 * The nsIOfflineCacheUpdate being processed.
36 * @param event
37 * See enumeration above
38 */
39 void updateStateChanged(in nsIOfflineCacheUpdate aUpdate, in uint32_t state);
40
41 /**
42 * Informs the observer about an application being available to associate.
43 *
44 * @param applicationCache
45 * The application cache instance that has been created or found by the
46 * update to associate with
47 */
48 void applicationCacheAvailable(in nsIApplicationCache applicationCache);
49 };
50
51 /**
52 * An nsIOfflineCacheUpdate is used to update an application's offline
53 * resources.
54 *
55 * It can be used to perform partial or complete updates.
56 *
57 * One update object will be updating at a time. The active object will
58 * load its items one by one, sending itemCompleted() to any registered
59 * observers.
60 */
61 [scriptable, uuid(a4503a53-6ab8-4b50-b01e-1c4f393fc980)]
62 interface nsIOfflineCacheUpdate : nsISupports {
63 /**
64 * Fetch the status of the running update. This will return a value
65 * defined in nsIDOMOfflineResourceList.
66 */
67 readonly attribute unsigned short status;
68
69 /**
70 * TRUE if the update is being used to add specific resources.
71 * FALSE if the complete cache update process is happening.
72 */
73 readonly attribute boolean partial;
74
75 /**
76 * TRUE if this is an upgrade attempt, FALSE if it is a new cache
77 * attempt.
78 */
79 readonly attribute boolean isUpgrade;
80
81 /**
82 * The domain being updated, and the domain that will own any URIs added
83 * with this update.
84 */
85 readonly attribute ACString updateDomain;
86
87 /**
88 * The manifest for the offline application being updated.
89 */
90 readonly attribute nsIURI manifestURI;
91
92 /**
93 * TRUE if the cache update completed successfully.
94 */
95 readonly attribute boolean succeeded;
96
97 /**
98 * Initialize the update.
99 *
100 * @param aManifestURI
101 * The manifest URI to be checked.
102 * @param aDocumentURI
103 * The page that is requesting the update.
104 */
105 void init(in nsIURI aManifestURI, in nsIURI aDocumentURI, in nsIDOMDocument aDocument,
106 [optional] in nsIFile aCustomProfileDir,
107 [optional] in unsigned long aAppId,
108 [optional] in boolean aInBrowser);
109
110 /**
111 * Initialize the update for partial processing.
112 *
113 * @param aManifestURI
114 * The manifest URI of the related cache.
115 * @param aClientID
116 * Client ID of the cache to store resource to. This ClientID
117 * must be ID of cache in the cache group identified by
118 * the manifest URI passed in the first parameter.
119 * @param aDocumentURI
120 * The page that is requesting the update. May be null
121 * when this information is unknown.
122 */
123 void initPartial(in nsIURI aManifestURI, in ACString aClientID, in nsIURI aDocumentURI);
124
125 /**
126 * Initialize the update to only check whether there is an update
127 * to the manifest available (if it has actually changed on the server).
128 *
129 * @param aManifestURI
130 * The manifest URI of the related cache.
131 * @param aAppID
132 * Local ID of an app (optional) to check the cache update for.
133 * @param aInBrowser
134 * Whether to check for a cache populated from browser element.
135 * @param aObserver
136 * nsIObserver implementation that receives the result.
137 * When aTopic == "offline-cache-update-available" there is an update to
138 * to download. Update of the app cache will lead to a new version
139 * download.
140 * When aTopic == "offline-cache-update-unavailable" then there is no
141 * update available (the manifest has not changed on the server).
142 */
143 void initForUpdateCheck(in nsIURI aManifestURI,
144 in unsigned long aAppID,
145 in boolean aInBrowser,
146 in nsIObserver aObserver);
147
148 /**
149 * Add a dynamic URI to the offline cache as part of the update.
150 *
151 * @param aURI
152 * The URI to add.
153 */
154 void addDynamicURI(in nsIURI aURI);
155
156 /**
157 * Add the update to the offline update queue. An offline-cache-update-added
158 * event will be sent to the observer service.
159 */
160 void schedule();
161
162 /**
163 * Observe loads that are added to the update.
164 *
165 * @param aObserver
166 * object that notifications will be sent to.
167 * @param aHoldWeak
168 * TRUE if you want the update to hold a weak reference to the
169 * observer, FALSE for a strong reference.
170 */
171 void addObserver(in nsIOfflineCacheUpdateObserver aObserver,
172 in boolean aHoldWeak);
173
174 /**
175 * Remove an observer from the update.
176 *
177 * @param aObserver
178 * the observer to remove.
179 */
180 void removeObserver(in nsIOfflineCacheUpdateObserver aObserver);
181
182 /**
183 * Cancel the update when still in progress. This stops all running resource
184 * downloads and discards the downloaded cache version. Throws when update
185 * has already finished and made the new cache version active.
186 */
187 void cancel();
188
189 /**
190 * Return the number of bytes downloaded so far
191 */
192 readonly attribute uint64_t byteProgress;
193 };
194
195 [scriptable, uuid(0668910d-d14f-4cee-8db5-25faebc360ab)]
196 interface nsIOfflineCacheUpdateService : nsISupports {
197 /**
198 * Constants for the offline-app permission.
199 *
200 * XXX: This isn't a great place for this, but it's really the only
201 * private offline-app-related interface
202 */
203
204 /**
205 * Allow the domain to use offline APIs, and don't warn about excessive
206 * usage.
207 */
208 const unsigned long ALLOW_NO_WARN = 3;
209
210 /**
211 * Access to the list of cache updates that have been scheduled.
212 */
213 readonly attribute unsigned long numUpdates;
214 nsIOfflineCacheUpdate getUpdate(in unsigned long index);
215
216 /**
217 * Schedule a cache update for a given offline manifest. If an
218 * existing update is scheduled or running, that update will be returned.
219 * Otherwise a new update will be scheduled.
220 */
221 nsIOfflineCacheUpdate scheduleUpdate(in nsIURI aManifestURI,
222 in nsIURI aDocumentURI,
223 in nsIDOMWindow aWindow);
224
225 /**
226 * Schedule a cache update for a given offline manifest using app cache
227 * bound to the given appID+inBrowser flag. If an existing update is
228 * scheduled or running, that update will be returned. Otherwise a new
229 * update will be scheduled.
230 */
231 nsIOfflineCacheUpdate scheduleAppUpdate(in nsIURI aManifestURI,
232 in nsIURI aDocumentURI,
233 in unsigned long aAppID,
234 in boolean aInBrowser,
235 in nsIFile aProfileDir);
236
237 /**
238 * Schedule a cache update for a manifest when the document finishes
239 * loading.
240 */
241 void scheduleOnDocumentStop(in nsIURI aManifestURI,
242 in nsIURI aDocumentURI,
243 in nsIDOMDocument aDocument);
244
245 /**
246 * Schedule a check to see if an update is available.
247 *
248 * This will not update or make any changes to the appcache.
249 * It only notifies the observer to indicate whether the manifest has
250 * changed on the server (or not): a changed manifest means that an
251 * update is available.
252 *
253 * For arguments see nsIOfflineCacheUpdate.initForUpdateCheck() method
254 * description.
255 */
256 void checkForUpdate(in nsIURI aManifestURI,
257 in unsigned long aAppID,
258 in boolean aInBrowser,
259 in nsIObserver aObserver);
260
261 /**
262 * Checks whether a principal should have access to the offline
263 * cache.
264 * @param aPrincipal
265 * The principal to check.
266 * @param aPrefBranch
267 * The pref branch to use to check the
268 * offline-apps.allow_by_default pref. If not specified,
269 * the pref service will be used.
270 */
271 boolean offlineAppAllowed(in nsIPrincipal aPrincipal,
272 in nsIPrefBranch aPrefBranch);
273
274 /**
275 * Checks whether a document at the given URI should have access
276 * to the offline cache.
277 * @param aURI
278 * The URI to check
279 * @param aPrefBranch
280 * The pref branch to use to check the
281 * offline-apps.allow_by_default pref. If not specified,
282 * the pref service will be used.
283 */
284 boolean offlineAppAllowedForURI(in nsIURI aURI,
285 in nsIPrefBranch aPrefBranch);
286
287 /**
288 * Sets the "offline-app" permission for the principal.
289 * In the single process model calls directly on permission manager.
290 * In the multi process model dispatches to the parent process.
291 */
292 void allowOfflineApp(in nsIDOMWindow aWindow, in nsIPrincipal aPrincipal);
293 };

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial