1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/uriloader/prefetch/nsIOfflineCacheUpdate.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,293 @@
1.4 +/* -*- mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +
1.11 +interface nsIURI;
1.12 +interface nsIDOMWindow;
1.13 +interface nsIDOMNode;
1.14 +interface nsIDOMDocument;
1.15 +interface nsIOfflineCacheUpdate;
1.16 +interface nsIPrincipal;
1.17 +interface nsIPrefBranch;
1.18 +interface nsIApplicationCache;
1.19 +interface nsIFile;
1.20 +interface nsIObserver;
1.21 +
1.22 +[scriptable, uuid(47360d57-8ef4-4a5d-8865-1a27a739ad1a)]
1.23 +interface nsIOfflineCacheUpdateObserver : nsISupports {
1.24 + const unsigned long STATE_ERROR = 1;
1.25 + const unsigned long STATE_CHECKING = 2;
1.26 + const unsigned long STATE_NOUPDATE = 3;
1.27 + const unsigned long STATE_OBSOLETE = 4;
1.28 + const unsigned long STATE_DOWNLOADING = 5;
1.29 + const unsigned long STATE_ITEMSTARTED = 6;
1.30 + const unsigned long STATE_ITEMCOMPLETED = 7;
1.31 + const unsigned long STATE_ITEMPROGRESS = 8;
1.32 + const unsigned long STATE_FINISHED = 10;
1.33 +
1.34 + /**
1.35 + * aUpdate has changed its state.
1.36 + *
1.37 + * @param aUpdate
1.38 + * The nsIOfflineCacheUpdate being processed.
1.39 + * @param event
1.40 + * See enumeration above
1.41 + */
1.42 + void updateStateChanged(in nsIOfflineCacheUpdate aUpdate, in uint32_t state);
1.43 +
1.44 + /**
1.45 + * Informs the observer about an application being available to associate.
1.46 + *
1.47 + * @param applicationCache
1.48 + * The application cache instance that has been created or found by the
1.49 + * update to associate with
1.50 + */
1.51 + void applicationCacheAvailable(in nsIApplicationCache applicationCache);
1.52 +};
1.53 +
1.54 +/**
1.55 + * An nsIOfflineCacheUpdate is used to update an application's offline
1.56 + * resources.
1.57 + *
1.58 + * It can be used to perform partial or complete updates.
1.59 + *
1.60 + * One update object will be updating at a time. The active object will
1.61 + * load its items one by one, sending itemCompleted() to any registered
1.62 + * observers.
1.63 + */
1.64 +[scriptable, uuid(a4503a53-6ab8-4b50-b01e-1c4f393fc980)]
1.65 +interface nsIOfflineCacheUpdate : nsISupports {
1.66 + /**
1.67 + * Fetch the status of the running update. This will return a value
1.68 + * defined in nsIDOMOfflineResourceList.
1.69 + */
1.70 + readonly attribute unsigned short status;
1.71 +
1.72 + /**
1.73 + * TRUE if the update is being used to add specific resources.
1.74 + * FALSE if the complete cache update process is happening.
1.75 + */
1.76 + readonly attribute boolean partial;
1.77 +
1.78 + /**
1.79 + * TRUE if this is an upgrade attempt, FALSE if it is a new cache
1.80 + * attempt.
1.81 + */
1.82 + readonly attribute boolean isUpgrade;
1.83 +
1.84 + /**
1.85 + * The domain being updated, and the domain that will own any URIs added
1.86 + * with this update.
1.87 + */
1.88 + readonly attribute ACString updateDomain;
1.89 +
1.90 + /**
1.91 + * The manifest for the offline application being updated.
1.92 + */
1.93 + readonly attribute nsIURI manifestURI;
1.94 +
1.95 + /**
1.96 + * TRUE if the cache update completed successfully.
1.97 + */
1.98 + readonly attribute boolean succeeded;
1.99 +
1.100 + /**
1.101 + * Initialize the update.
1.102 + *
1.103 + * @param aManifestURI
1.104 + * The manifest URI to be checked.
1.105 + * @param aDocumentURI
1.106 + * The page that is requesting the update.
1.107 + */
1.108 + void init(in nsIURI aManifestURI, in nsIURI aDocumentURI, in nsIDOMDocument aDocument,
1.109 + [optional] in nsIFile aCustomProfileDir,
1.110 + [optional] in unsigned long aAppId,
1.111 + [optional] in boolean aInBrowser);
1.112 +
1.113 + /**
1.114 + * Initialize the update for partial processing.
1.115 + *
1.116 + * @param aManifestURI
1.117 + * The manifest URI of the related cache.
1.118 + * @param aClientID
1.119 + * Client ID of the cache to store resource to. This ClientID
1.120 + * must be ID of cache in the cache group identified by
1.121 + * the manifest URI passed in the first parameter.
1.122 + * @param aDocumentURI
1.123 + * The page that is requesting the update. May be null
1.124 + * when this information is unknown.
1.125 + */
1.126 + void initPartial(in nsIURI aManifestURI, in ACString aClientID, in nsIURI aDocumentURI);
1.127 +
1.128 + /**
1.129 + * Initialize the update to only check whether there is an update
1.130 + * to the manifest available (if it has actually changed on the server).
1.131 + *
1.132 + * @param aManifestURI
1.133 + * The manifest URI of the related cache.
1.134 + * @param aAppID
1.135 + * Local ID of an app (optional) to check the cache update for.
1.136 + * @param aInBrowser
1.137 + * Whether to check for a cache populated from browser element.
1.138 + * @param aObserver
1.139 + * nsIObserver implementation that receives the result.
1.140 + * When aTopic == "offline-cache-update-available" there is an update to
1.141 + * to download. Update of the app cache will lead to a new version
1.142 + * download.
1.143 + * When aTopic == "offline-cache-update-unavailable" then there is no
1.144 + * update available (the manifest has not changed on the server).
1.145 + */
1.146 + void initForUpdateCheck(in nsIURI aManifestURI,
1.147 + in unsigned long aAppID,
1.148 + in boolean aInBrowser,
1.149 + in nsIObserver aObserver);
1.150 +
1.151 + /**
1.152 + * Add a dynamic URI to the offline cache as part of the update.
1.153 + *
1.154 + * @param aURI
1.155 + * The URI to add.
1.156 + */
1.157 + void addDynamicURI(in nsIURI aURI);
1.158 +
1.159 + /**
1.160 + * Add the update to the offline update queue. An offline-cache-update-added
1.161 + * event will be sent to the observer service.
1.162 + */
1.163 + void schedule();
1.164 +
1.165 + /**
1.166 + * Observe loads that are added to the update.
1.167 + *
1.168 + * @param aObserver
1.169 + * object that notifications will be sent to.
1.170 + * @param aHoldWeak
1.171 + * TRUE if you want the update to hold a weak reference to the
1.172 + * observer, FALSE for a strong reference.
1.173 + */
1.174 + void addObserver(in nsIOfflineCacheUpdateObserver aObserver,
1.175 + in boolean aHoldWeak);
1.176 +
1.177 + /**
1.178 + * Remove an observer from the update.
1.179 + *
1.180 + * @param aObserver
1.181 + * the observer to remove.
1.182 + */
1.183 + void removeObserver(in nsIOfflineCacheUpdateObserver aObserver);
1.184 +
1.185 + /**
1.186 + * Cancel the update when still in progress. This stops all running resource
1.187 + * downloads and discards the downloaded cache version. Throws when update
1.188 + * has already finished and made the new cache version active.
1.189 + */
1.190 + void cancel();
1.191 +
1.192 + /**
1.193 + * Return the number of bytes downloaded so far
1.194 + */
1.195 + readonly attribute uint64_t byteProgress;
1.196 +};
1.197 +
1.198 +[scriptable, uuid(0668910d-d14f-4cee-8db5-25faebc360ab)]
1.199 +interface nsIOfflineCacheUpdateService : nsISupports {
1.200 + /**
1.201 + * Constants for the offline-app permission.
1.202 + *
1.203 + * XXX: This isn't a great place for this, but it's really the only
1.204 + * private offline-app-related interface
1.205 + */
1.206 +
1.207 + /**
1.208 + * Allow the domain to use offline APIs, and don't warn about excessive
1.209 + * usage.
1.210 + */
1.211 + const unsigned long ALLOW_NO_WARN = 3;
1.212 +
1.213 + /**
1.214 + * Access to the list of cache updates that have been scheduled.
1.215 + */
1.216 + readonly attribute unsigned long numUpdates;
1.217 + nsIOfflineCacheUpdate getUpdate(in unsigned long index);
1.218 +
1.219 + /**
1.220 + * Schedule a cache update for a given offline manifest. If an
1.221 + * existing update is scheduled or running, that update will be returned.
1.222 + * Otherwise a new update will be scheduled.
1.223 + */
1.224 + nsIOfflineCacheUpdate scheduleUpdate(in nsIURI aManifestURI,
1.225 + in nsIURI aDocumentURI,
1.226 + in nsIDOMWindow aWindow);
1.227 +
1.228 + /**
1.229 + * Schedule a cache update for a given offline manifest using app cache
1.230 + * bound to the given appID+inBrowser flag. If an existing update is
1.231 + * scheduled or running, that update will be returned. Otherwise a new
1.232 + * update will be scheduled.
1.233 + */
1.234 + nsIOfflineCacheUpdate scheduleAppUpdate(in nsIURI aManifestURI,
1.235 + in nsIURI aDocumentURI,
1.236 + in unsigned long aAppID,
1.237 + in boolean aInBrowser,
1.238 + in nsIFile aProfileDir);
1.239 +
1.240 + /**
1.241 + * Schedule a cache update for a manifest when the document finishes
1.242 + * loading.
1.243 + */
1.244 + void scheduleOnDocumentStop(in nsIURI aManifestURI,
1.245 + in nsIURI aDocumentURI,
1.246 + in nsIDOMDocument aDocument);
1.247 +
1.248 + /**
1.249 + * Schedule a check to see if an update is available.
1.250 + *
1.251 + * This will not update or make any changes to the appcache.
1.252 + * It only notifies the observer to indicate whether the manifest has
1.253 + * changed on the server (or not): a changed manifest means that an
1.254 + * update is available.
1.255 + *
1.256 + * For arguments see nsIOfflineCacheUpdate.initForUpdateCheck() method
1.257 + * description.
1.258 + */
1.259 + void checkForUpdate(in nsIURI aManifestURI,
1.260 + in unsigned long aAppID,
1.261 + in boolean aInBrowser,
1.262 + in nsIObserver aObserver);
1.263 +
1.264 + /**
1.265 + * Checks whether a principal should have access to the offline
1.266 + * cache.
1.267 + * @param aPrincipal
1.268 + * The principal to check.
1.269 + * @param aPrefBranch
1.270 + * The pref branch to use to check the
1.271 + * offline-apps.allow_by_default pref. If not specified,
1.272 + * the pref service will be used.
1.273 + */
1.274 + boolean offlineAppAllowed(in nsIPrincipal aPrincipal,
1.275 + in nsIPrefBranch aPrefBranch);
1.276 +
1.277 + /**
1.278 + * Checks whether a document at the given URI should have access
1.279 + * to the offline cache.
1.280 + * @param aURI
1.281 + * The URI to check
1.282 + * @param aPrefBranch
1.283 + * The pref branch to use to check the
1.284 + * offline-apps.allow_by_default pref. If not specified,
1.285 + * the pref service will be used.
1.286 + */
1.287 + boolean offlineAppAllowedForURI(in nsIURI aURI,
1.288 + in nsIPrefBranch aPrefBranch);
1.289 +
1.290 + /**
1.291 + * Sets the "offline-app" permission for the principal.
1.292 + * In the single process model calls directly on permission manager.
1.293 + * In the multi process model dispatches to the parent process.
1.294 + */
1.295 + void allowOfflineApp(in nsIDOMWindow aWindow, in nsIPrincipal aPrincipal);
1.296 +};
