The Tor Browser / file revision

 /* -*- 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 nsIURI;

 interface nsIDOMWindow;

 interface nsIDOMNode;

 interface nsIDOMDocument;

 interface nsIOfflineCacheUpdate;

 interface nsIPrincipal;

 interface nsIPrefBranch;

 interface nsIApplicationCache;

 interface nsIFile;

 interface nsIObserver;

 [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(a4503a53-6ab8-4b50-b01e-1c4f393fc980)]

 interface nsIOfflineCacheUpdate : nsISupports {

   /**

    * Fetch the status of the running update.  This will return a value

    * defined in nsIDOMOfflineResourceList.

    */

   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;

   /**

    * 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.

    */

   void init(in nsIURI aManifestURI, in nsIURI aDocumentURI, in nsIDOMDocument aDocument,

             [optional] in nsIFile aCustomProfileDir,

             [optional] in unsigned long aAppId,

             [optional] in boolean aInBrowser);

   /**

    * 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.

    */

   void initPartial(in nsIURI aManifestURI, in ACString aClientID, in nsIURI aDocumentURI);

   /**

    * 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 aAppID

    *        Local ID of an app (optional) to check the cache update for.

    * @param aInBrowser

    *        Whether to check for a cache populated from browser element.

    * @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 unsigned long aAppID,

                           in boolean aInBrowser,

                           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,

                    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(0668910d-d14f-4cee-8db5-25faebc360ab)]

 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 nsIDOMWindow aWindow);

     /**

      * Schedule a cache update for a given offline manifest using app cache

      * bound to the given appID+inBrowser 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 unsigned long aAppID,

                                             in boolean aInBrowser,

                                             in nsIFile aProfileDir);

     /**

      * Schedule a cache update for a manifest when the document finishes

      * loading.

      */

     void scheduleOnDocumentStop(in nsIURI aManifestURI,

                                 in nsIURI aDocumentURI,

                                 in nsIDOMDocument 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 unsigned long aAppID,

                         in boolean aInBrowser,

                         in nsIObserver aObserver);

     /**

      * Checks whether a principal should have access to the offline

      * cache.

      * @param aPrincipal

      *        The principal to check.

      * @param aPrefBranch

      *        The pref branch to use to check the

      *        offline-apps.allow_by_default pref.  If not specified,

      *        the pref service will be used.

      */

     boolean offlineAppAllowed(in nsIPrincipal aPrincipal,

                               in nsIPrefBranch aPrefBranch);

     /**

      * Checks whether a document at the given URI should have access

      * to the offline cache.

      * @param aURI

      *        The URI to check

      * @param aPrefBranch

      *        The pref branch to use to check the

      *        offline-apps.allow_by_default pref.  If not specified,

      *        the pref service will be used.

      */

     boolean offlineAppAllowedForURI(in nsIURI aURI,

                                     in nsIPrefBranch aPrefBranch);

     /**

      * 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 nsIDOMWindow aWindow, in nsIPrincipal aPrincipal);

 };