1 /* -*- mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /* ***** BEGIN LICENSE BLOCK *****
3 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
4 *
5 * The contents of this file are subject to the Mozilla Public License Version
6 * 1.1 (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 * http://www.mozilla.org/MPL/
9 *
10 * Software distributed under the License is distributed on an "AS IS" basis,
11 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
12 * for the specific language governing rights and limitations under the
13 * License.
14 *
15 * The Original Code is mozilla.org code.
16 *
17 * The Initial Developer of the Original Code is
18 * Mozilla Corporation
19 * Portions created by the Initial Developer are Copyright (C) 2007
20 * the Initial Developer. All Rights Reserved.
21 *
22 * Contributor(s):
23 * Dave Camp <dcamp@mozilla.com>
24 *
25 * Alternatively, the contents of this file may be used under the terms of
26 * either the GNU General Public License Version 2 or later (the "GPL"), or
27 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
28 * in which case the provisions of the GPL or the LGPL are applicable instead
29 * of those above. If you wish to allow use of your version of this file only
30 * under the terms of either the GPL or the LGPL, and not to allow others to
31 * use your version of this file under the terms of the MPL, indicate your
32 * decision by deleting the provisions above and replace them with the notice
33 * and other provisions required by the GPL or the LGPL. If you do not delete
34 * the provisions above, a recipient may use your version of this file under
35 * the terms of any one of the MPL, the GPL or the LGPL.
36 *
37 * ***** END LICENSE BLOCK ***** */
38
39 #include "nsISupports.idl"
40
41 interface nsIURI;
42 interface nsIDOMNode;
43 interface nsIDOMDocument;
44 interface nsIDOMLoadStatus;
45 interface nsIOfflineCacheUpdate;
46
47 [scriptable, uuid(0aa38757-999c-44d6-bdb4-7dd32634fa83)]
48 interface nsIOfflineCacheUpdateObserver : nsISupports {
49 /**
50 * There was an error updating the cache.
51 *
52 * @param aUpdate
53 * The nsIOfflineCacheUpdate being processed.
54 */
55 void error(in nsIOfflineCacheUpdate aUpdate);
56
57 /**
58 * The manifest is being checked for updates
59 *
60 * @param aUpdate
61 * The nsIOfflineCacheUpdate being processed.
62 */
63 void checking(in nsIOfflineCacheUpdate aUpdate);
64
65 /**
66 * No update was necessary.
67 *
68 * @param aUpdate
69 * The nsIOfflineCacheUpdate being processed.
70 */
71 void noUpdate(in nsIOfflineCacheUpdate aUpdate);
72
73 /**
74 * Starting to download resources
75 *
76 * @param aUpdate
77 * The nsIOfflineCacheUpdate being processed.
78 */
79 void downloading(in nsIOfflineCacheUpdate aUpdate);
80
81 /**
82 * An item has started downloading.
83 *
84 * @param aUpdate
85 * The nsIOfflineCacheUpdate being processed.
86 * @param aItem
87 * load status for the item that is being downloaded.
88 */
89 void itemStarted(in nsIOfflineCacheUpdate aUpdate,
90 in nsIDOMLoadStatus aItem);
91
92 /**
93 * An item has finished loading.
94 *
95 * @param aUpdate
96 * The nsIOfflineCacheUpdate being processed.
97 * @param aItem
98 * load status for the item that completed.
99 */
100 void itemCompleted(in nsIOfflineCacheUpdate aUpdate,
101 in nsIDOMLoadStatus aItem);
102 };
103
104 /**
105 * An nsIOfflineCacheUpdate is used to update an application's offline
106 * resources.
107 *
108 * It can be used to perform partial or complete updates.
109 *
110 * Each update object maintains a list of nsIDOMLoadStatus items for the
111 * resources it is updating. The list of these items will be available
112 * after the object is scheduled.
113 *
114 * One update object will be updating at a time. The active object will
115 * load its items one by one, sending itemCompleted() to any registered
116 * observers.
117 */
118 [scriptable, uuid(7dc06ede-1098-4384-b95e-65525ab254c9)]
119 interface nsIOfflineCacheUpdate : nsISupports {
120 /**
121 * Fetch the status of the running update. This will return a value
122 * defined in nsIDOMOfflineResourceList.
123 */
124 readonly attribute unsigned short status;
125
126 /**
127 * TRUE if the update is being used to add specific resources.
128 * FALSE if the complete cache update process is happening.
129 */
130 readonly attribute boolean partial;
131
132 /**
133 * The domain being updated, and the domain that will own any URIs added
134 * with this update.
135 */
136 readonly attribute ACString updateDomain;
137
138 /**
139 * The manifest for the offline application being updated.
140 */
141 readonly attribute nsIURI manifestURI;
142
143 /**
144 * TRUE if the cache update completed successfully.
145 */
146 readonly attribute boolean succeeded;
147
148 /**
149 * Initialize the update.
150 *
151 * @param aPartialUpdate
152 * TRUE if the update should just update the URIs given to it,
153 * FALSE if all URLs for the owner domain should be added.
154 * @param aManifestURI
155 * The manifest URI to be checked, or for partial updates the
156 * manifest that should own resources that are added.
157 * @param aDocumentURI
158 * The page that is requesting the update.
159 */
160 void init(in boolean aPartialUpdate,
161 in nsIURI aManifestURI,
162 in nsIURI aDocumentURI);
163
164 /**
165 * Add a URI to the offline cache as part of the update.
166 *
167 * @param aURI
168 * The URI to add.
169 */
170 void addDynamicURI(in nsIURI aURI);
171
172 /**
173 * Add the update to the offline update queue. An offline-cache-update-added
174 * event will be sent to the observer service.
175 */
176 void schedule();
177
178 /**
179 * Access to the list of items in the update.
180 */
181 readonly attribute unsigned long count;
182 nsIDOMLoadStatus item(in unsigned long index);
183
184 /**
185 * Observe loads that are added to the update.
186 *
187 * @param aObserver
188 * object that notifications will be sent to.
189 * @param aHoldWeak
190 * TRUE if you want the update to hold a weak reference to the
191 * observer, FALSE for a strong reference.
192 */
193 void addObserver(in nsIOfflineCacheUpdateObserver aObserver,
194 in boolean aHoldWeak);
195
196 /**
197 * Remove an observer from the update.
198 *
199 * @param aObserver
200 * the observer to remove.
201 */
202 void removeObserver(in nsIOfflineCacheUpdateObserver aObserver);
203 };
204
205 [scriptable, uuid(3abee04b-5bbb-4405-b659-35f780e38da0)]
206 interface nsIOfflineCacheUpdateService : nsISupports {
207 /**
208 * Constants for the offline-app permission.
209 *
210 * XXX: This isn't a great place for this, but it's really the only
211 * private offline-app-related interface
212 */
213
214 /**
215 * Allow the domain to use offline APIs, and don't warn about excessive
216 * usage.
217 */
218 const unsigned long ALLOW_NO_WARN = 3;
219
220 /**
221 * Access to the list of cache updates that have been scheduled.
222 */
223 readonly attribute unsigned long numUpdates;
224 nsIOfflineCacheUpdate getUpdate(in unsigned long index);
225
226 /**
227 * Schedule a cache update for a given offline manifest. If an
228 * existing update is scheduled or running, that update will be returned.
229 * Otherwise a new update will be scheduled.
230 */
231 nsIOfflineCacheUpdate scheduleUpdate(in nsIURI aManifestURI,
232 in nsIURI aDocumentURI);
233
234 /**
235 * Schedule a cache update for a manifest when the document finishes
236 * loading.
237 */
238 void scheduleOnDocumentStop(in nsIURI aManifestURI,
239 in nsIURI aDocumentURI,
240 in nsIDOMDocument aDocument);
241 };