/* -*- mode: C++; 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 mozIDOMWindow; interface nsIURI; interface nsIOfflineCacheUpdate; interface nsIPrincipal; interface nsIPrefBranch; interface nsIApplicationCache; interface nsIFile; interface nsIObserver; interface nsICookieJarSettings; webidl Document; [scriptable, uuid(47360d57-8ef4-4a5d-8865-1a27a739ad1a)] interface nsIOfflineCacheUpdateObserver : nsISupports { const unsigned long STATE_ERROR = 1; const unsigned long STATE_CHECKING = 2; const unsigned long STATE_NOUPDATE = 3; const unsigned long STATE_OBSOLETE = 4; const unsigned long STATE_DOWNLOADING = 5; const unsigned long STATE_ITEMSTARTED = 6; const unsigned long STATE_ITEMCOMPLETED = 7; const unsigned long STATE_ITEMPROGRESS = 8; const unsigned long STATE_FINISHED = 10; /** * aUpdate has changed its state. * * @param aUpdate * The nsIOfflineCacheUpdate being processed. * @param event * See enumeration above */ void updateStateChanged(in nsIOfflineCacheUpdate aUpdate, in uint32_t state); /** * Informs the observer about an application being available to associate. * * @param applicationCache * The application cache instance that has been created or found by the * update to associate with */ void applicationCacheAvailable(in nsIApplicationCache applicationCache); }; /** * An nsIOfflineCacheUpdate is used to update an application's offline * resources. * * It can be used to perform partial or complete updates. * * One update object will be updating at a time. The active object will * load its items one by one, sending itemCompleted() to any registered * observers. */ [scriptable, uuid(6e3e26ea-45b2-4db7-9e4a-93b965679298)] interface nsIOfflineCacheUpdate : nsISupports { /** * Fetch the status of the running update. This will return a value * defined in OfflineResourceList.webidl. */ readonly attribute unsigned short status; /** * TRUE if the update is being used to add specific resources. * FALSE if the complete cache update process is happening. */ readonly attribute boolean partial; /** * TRUE if this is an upgrade attempt, FALSE if it is a new cache * attempt. */ readonly attribute boolean isUpgrade; /** * The domain being updated, and the domain that will own any URIs added * with this update. */ readonly attribute ACString updateDomain; /** * The manifest for the offline application being updated. */ readonly attribute nsIURI manifestURI; /** * The principal of the page that is requesting the update. */ readonly attribute nsIPrincipal loadingPrincipal; /** * TRUE if the cache update completed successfully. */ readonly attribute boolean succeeded; /** * Initialize the update. * * @param aManifestURI * The manifest URI to be checked. * @param aDocumentURI * The page that is requesting the update. * @param aLoadingPrincipal * The principal of the page that is requesting the update. */ void init(in nsIURI aManifestURI, in nsIURI aDocumentURI, in nsIPrincipal aLoadingPrincipal, in Document aDocument, [optional] in nsIFile aCustomProfileDir); /** * Initialize the update for partial processing. * * @param aManifestURI * The manifest URI of the related cache. * @param aClientID * Client ID of the cache to store resource to. This ClientID * must be ID of cache in the cache group identified by * the manifest URI passed in the first parameter. * @param aDocumentURI * The page that is requesting the update. May be null * when this information is unknown. * @param aCookieJarSettings * The cookie jar settings belonging to the page that is requesting * the update. */ void initPartial(in nsIURI aManifestURI, in ACString aClientID, in nsIURI aDocumentURI, in nsIPrincipal aPrincipal, in nsICookieJarSettings aCookieJarSettings); /** * Initialize the update to only check whether there is an update * to the manifest available (if it has actually changed on the server). * * @param aManifestURI * The manifest URI of the related cache. * @param aObserver * nsIObserver implementation that receives the result. * When aTopic == "offline-cache-update-available" there is an update to * to download. Update of the app cache will lead to a new version * download. * When aTopic == "offline-cache-update-unavailable" then there is no * update available (the manifest has not changed on the server). */ void initForUpdateCheck(in nsIURI aManifestURI, in nsIPrincipal aLoadingPrincipal, in nsIObserver aObserver); /** * Add a dynamic URI to the offline cache as part of the update. * * @param aURI * The URI to add. */ void addDynamicURI(in nsIURI aURI); /** * Add the update to the offline update queue. An offline-cache-update-added * event will be sent to the observer service. */ void schedule(); /** * Observe loads that are added to the update. * * @param aObserver * object that notifications will be sent to. * @param aHoldWeak * TRUE if you want the update to hold a weak reference to the * observer, FALSE for a strong reference. */ void addObserver(in nsIOfflineCacheUpdateObserver aObserver, [optional] in boolean aHoldWeak); /** * Remove an observer from the update. * * @param aObserver * the observer to remove. */ void removeObserver(in nsIOfflineCacheUpdateObserver aObserver); /** * Cancel the update when still in progress. This stops all running resource * downloads and discards the downloaded cache version. Throws when update * has already finished and made the new cache version active. */ void cancel(); /** * Return the number of bytes downloaded so far */ readonly attribute uint64_t byteProgress; }; [scriptable, uuid(44971e74-37e4-4140-8677-a4cf213a3f4b)] interface nsIOfflineCacheUpdateService : nsISupports { /** * Constants for the offline-app permission. * * XXX: This isn't a great place for this, but it's really the only * private offline-app-related interface */ /** * Allow the domain to use offline APIs, and don't warn about excessive * usage. */ const unsigned long ALLOW_NO_WARN = 3; /** * Access to the list of cache updates that have been scheduled. */ readonly attribute unsigned long numUpdates; nsIOfflineCacheUpdate getUpdate(in unsigned long index); /** * Schedule a cache update for a given offline manifest. If an * existing update is scheduled or running, that update will be returned. * Otherwise a new update will be scheduled. */ nsIOfflineCacheUpdate scheduleUpdate(in nsIURI aManifestURI, in nsIURI aDocumentURI, in nsIPrincipal aLoadingPrincipal, in mozIDOMWindow aWindow); /** * Schedule a cache update for a given offline manifest using app cache * bound to the given appID flag. If an existing update is scheduled or * running, that update will be returned. Otherwise a new update will be * scheduled. */ nsIOfflineCacheUpdate scheduleAppUpdate(in nsIURI aManifestURI, in nsIURI aDocumentURI, in nsIPrincipal aLoadingPrincipal, in nsIFile aProfileDir); /** * Schedule a cache update for a manifest when the document finishes * loading. */ void scheduleOnDocumentStop(in nsIURI aManifestURI, in nsIURI aDocumentURI, in nsIPrincipal aLoadingPrincipal, in Document aDocument); /** * Schedule a check to see if an update is available. * * This will not update or make any changes to the appcache. * It only notifies the observer to indicate whether the manifest has * changed on the server (or not): a changed manifest means that an * update is available. * * For arguments see nsIOfflineCacheUpdate.initForUpdateCheck() method * description. */ void checkForUpdate(in nsIURI aManifestURI, in nsIPrincipal aLoadingPrincipal, in nsIObserver aObserver); /** * Checks whether a principal should have access to the offline * cache. * @param aPrincipal * The principal to check. */ boolean offlineAppAllowed(in nsIPrincipal aPrincipal); /** * Checks whether a document at the given URI should have access * to the offline cache. * @param aURI * The URI to check */ boolean offlineAppAllowedForURI(in nsIURI aURI); /** * Sets the "offline-app" permission for the principal. * In the single process model calls directly on permission manager. * In the multi process model dispatches to the parent process. */ void allowOfflineApp(in nsIPrincipal aPrincipal); };