uriloader/prefetch/nsIOfflineCacheUpdate.idl

   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 interface nsIPrincipal;
  47 interface nsIPrefBranch;
  48
  49 [scriptable, uuid(a28abeaf-a0b4-4440-b2fe-bc78249710ea)]
  50 interface nsIOfflineCacheUpdateObserver : nsISupports {
  51   /**
  52    * There was an error updating the cache.
  53    *
  54    * @param aUpdate
  55    *        The nsIOfflineCacheUpdate being processed.
  56    */
  57   void error(in nsIOfflineCacheUpdate aUpdate);
  58
  59   /**
  60    * The manifest is being checked for updates
  61    *
  62    * @param aUpdate
  63    *        The nsIOfflineCacheUpdate being processed.
  64    */
  65   void checking(in nsIOfflineCacheUpdate aUpdate);
  66
  67   /**
  68    * No update was necessary.
  69    *
  70    * @param aUpdate
  71    *        The nsIOfflineCacheUpdate being processed.
  72    */
  73   void noUpdate(in nsIOfflineCacheUpdate aUpdate);
  74
  75   /**
  76    * The cache group is now obsolete.
  77    *
  78    * @param aUpdate
  79    *        The nsIOfflineCacheUpdate being processed.
  80    */
  81   void obsolete(in nsIOfflineCacheUpdate aUpdate);
  82
  83   /**
  84    * Starting to download resources
  85    *
  86    * @param aUpdate
  87    *        The nsIOfflineCacheUpdate being processed.
  88    */
  89   void downloading(in nsIOfflineCacheUpdate aUpdate);
  90
  91   /**
  92    * An item has started downloading.
  93    *
  94    * @param aUpdate
  95    *        The nsIOfflineCacheUpdate being processed.
  96    * @param aItem
  97    *        load status for the item that is being downloaded.
  98    */
  99   void itemStarted(in nsIOfflineCacheUpdate aUpdate,
 100                    in nsIDOMLoadStatus aItem);
 101
 102   /**
 103    * An item has finished loading.
 104    *
 105    * @param aUpdate
 106    *        The nsIOfflineCacheUpdate being processed.
 107    * @param aItem
 108    *         load status for the item that completed.
 109    */
 110   void itemCompleted(in nsIOfflineCacheUpdate aUpdate,
 111                      in nsIDOMLoadStatus aItem);
 112 };
 113
 114 /**
 115  * An nsIOfflineCacheUpdate is used to update an application's offline
 116  * resources.
 117  *
 118  * It can be used to perform partial or complete updates.
 119  *
 120  * Each update object maintains a list of nsIDOMLoadStatus items for the
 121  * resources it is updating.  The list of these items will be available
 122  * after the object is scheduled.
 123  *
 124  * One update object will be updating at a time.  The active object will
 125  * load its items one by one, sending itemCompleted() to any registered
 126  * observers.
 127  */
 128 [scriptable, uuid(877261bb-b952-4d27-847e-859bdd47c0ec)]
 129 interface nsIOfflineCacheUpdate : nsISupports {
 130   /**
 131    * Fetch the status of the running update.  This will return a value
 132    * defined in nsIDOMOfflineResourceList.
 133    */
 134   readonly attribute unsigned short status;
 135
 136   /**
 137    * TRUE if the update is being used to add specific resources.
 138    * FALSE if the complete cache update process is happening.
 139    */
 140   readonly attribute boolean partial;
 141
 142   /**
 143    * TRUE if this is an upgrade attempt, FALSE if it is a new cache
 144    * attempt.
 145    */
 146   readonly attribute boolean isUpgrade;
 147
 148   /**
 149    * The domain being updated, and the domain that will own any URIs added
 150    * with this update.
 151    */
 152   readonly attribute ACString updateDomain;
 153
 154   /**
 155    * The manifest for the offline application being updated.
 156    */
 157   readonly attribute nsIURI manifestURI;
 158
 159   /**
 160    * TRUE if the cache update completed successfully.
 161    */
 162   readonly attribute boolean succeeded;
 163
 164   /**
 165    * Initialize the update.
 166    *
 167    * @param aManifestURI
 168    *        The manifest URI to be checked.
 169    * @param aDocumentURI
 170    *        The page that is requesting the update.
 171    */
 172   void init(in nsIURI aManifestURI, in nsIURI aDocumentURI);
 173
 174   /**
 175    * Initialize the update for partial processing.
 176    *
 177    * @param aManifestURI
 178    *        The manifest URI of the related cache.
 179    * @param aClientID
 180    *        Client  ID of the cache to store resource to. This ClientID
 181    *        must be ID of cache in the cache group identified by
 182    *        the manifest URI passed in the first parameter.
 183    * @param aDocumentURI
 184    *        The page that is requesting the update. May be null
 185    *        when this information is unknown.
 186    */
 187   void initPartial(in nsIURI aManifestURI, in ACString aClientID, in nsIURI aDocumentURI);
 188
 189   /**
 190    * Add a dynamic URI to the offline cache as part of the update.
 191    *
 192    * @param aURI
 193    *        The URI to add.
 194    */
 195   void addDynamicURI(in nsIURI aURI);
 196
 197   /**
 198    * Add the update to the offline update queue.  An offline-cache-update-added
 199    * event will be sent to the observer service.
 200    */
 201   void schedule();
 202
 203   /**
 204    * Access to the list of items in the update.
 205    */
 206   readonly attribute unsigned long count;
 207   nsIDOMLoadStatus item(in unsigned long index);
 208
 209   /**
 210    * Observe loads that are added to the update.
 211    *
 212    * @param aObserver
 213    *        object that notifications will be sent to.
 214    * @param aHoldWeak
 215    *        TRUE if you want the update to hold a weak reference to the
 216    *        observer, FALSE for a strong reference.
 217    */
 218   void addObserver(in nsIOfflineCacheUpdateObserver aObserver,
 219                    in boolean aHoldWeak);
 220
 221   /**
 222    * Remove an observer from the update.
 223    *
 224    * @param aObserver
 225    *        the observer to remove.
 226    */
 227   void removeObserver(in nsIOfflineCacheUpdateObserver aObserver);
 228 };
 229
 230 [scriptable, uuid(6fd2030f-7b00-4102-a0e3-d73078821eb1)]
 231 interface nsIOfflineCacheUpdateService : nsISupports {
 232     /**
 233      * Constants for the offline-app permission.
 234      *
 235      * XXX: This isn't a great place for this, but it's really the only
 236      * private offline-app-related interface
 237      */
 238
 239     /**
 240      * Allow the domain to use offline APIs, and don't warn about excessive
 241      * usage.
 242      */
 243     const unsigned long ALLOW_NO_WARN = 3;
 244
 245     /**
 246      * Access to the list of cache updates that have been scheduled.
 247      */
 248     readonly attribute unsigned long numUpdates;
 249     nsIOfflineCacheUpdate getUpdate(in unsigned long index);
 250
 251     /**
 252      * Schedule a cache update for a given offline manifest.  If an
 253      * existing update is scheduled or running, that update will be returned.
 254      * Otherwise a new update will be scheduled.
 255      */
 256     nsIOfflineCacheUpdate scheduleUpdate(in nsIURI aManifestURI,
 257                                          in nsIURI aDocumentURI);
 258
 259     /**
 260      * Schedule a cache update for a manifest when the document finishes
 261      * loading.
 262      */
 263     void scheduleOnDocumentStop(in nsIURI aManifestURI,
 264                                 in nsIURI aDocumentURI,
 265                                 in nsIDOMDocument aDocument);
 266
 267     /**
 268      * Checks whether a principal should have access to the offline
 269      * cache.
 270      * @param aPrincipal
 271      *        The principal to check.
 272      * @param aPrefBranch
 273      *        The pref branch to use to check the
 274      *        offline-apps.allow_by_default pref.  If not specified,
 275      *        the pref service will be used.
 276      */
 277     boolean offlineAppAllowed(in nsIPrincipal aPrincipal,
 278                               in nsIPrefBranch aPrefBranch);
 279
 280     /**
 281      * Checks whether a document at the given URI should have access
 282      * to the offline cache.
 283      * @param aURI
 284      *        The URI to check
 285      * @param aPrefBranch
 286      *        The pref branch to use to check the
 287      *        offline-apps.allow_by_default pref.  If not specified,
 288      *        the pref service will be used.
 289      */
 290     boolean offlineAppAllowedForURI(in nsIURI aURI,
 291                                     in nsIPrefBranch aPrefBranch);
 292 };
 293
 294