netwerk/base/public/nsIIncrementalDownload.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim:set ts=2 sw=2 sts=2 et cindent: */
   3 /* ***** BEGIN LICENSE BLOCK *****
   4  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   5  *
   6  * The contents of this file are subject to the Mozilla Public License Version
   7  * 1.1 (the "License"); you may not use this file except in compliance with
   8  * the License. You may obtain a copy of the License at
   9  * http://www.mozilla.org/MPL/
  10  *
  11  * Software distributed under the License is distributed on an "AS IS" basis,
  12  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  13  * for the specific language governing rights and limitations under the
  14  * License.
  15  *
  16  * The Original Code is mozilla.org code.
  17  *
  18  * The Initial Developer of the Original Code is Google Inc.
  19  * Portions created by the Initial Developer are Copyright (C) 2005
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *  Darin Fisher <darin@meer.net>
  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 "nsIRequest.idl"
  40
  41 interface nsIURI;
  42 interface nsIFile;
  43 interface nsIRequestObserver;
  44
  45 /**
  46  * An incremental download object attempts to fetch a file piecemeal over time
  47  * in an effort to minimize network bandwidth usage.
  48  *
  49  * Canceling a background download does not cause the file on disk to be
  50  * deleted.
  51  */
  52 [scriptable, uuid(6687823f-56c4-461d-93a1-7f6cb7dfbfba)]
  53 interface nsIIncrementalDownload : nsIRequest
  54 {
  55   /**
  56    * Initialize the incremental download object.  If the destination file
  57    * already exists, then only the remaining portion of the file will be
  58    * fetched.
  59    *
  60    * NOTE: The downloader will create the destination file if it does not
  61    * already exist.  It will create the file with the permissions 0600 if
  62    * needed.  To affect the permissions of the file, consumers of this
  63    * interface may create an empty file at the specified destination prior to
  64    * starting the incremental download.
  65    *
  66    * NOTE: Since this class may create a temporary file at the specified
  67    * destination, it is advisable for the consumer of this interface to specify
  68    * a file name for the destination that would not tempt the user into
  69    * double-clicking it.  For example, it might be wise to append a file
  70    * extension like ".part" to the end of the destination to protect users from
  71    * accidentally running "blah.exe" before it is a complete file.
  72    *
  73    * @param uri
  74    *        The URI to fetch.
  75    * @param destination
  76    *        The location where the file is to be stored.
  77    * @param chunkSize
  78    *        The size of the chunks to fetch.  A non-positive value results in
  79    *        the default chunk size being used.
  80    * @param intervalInSeconds
  81    *        The amount of time to wait between fetching chunks.  Pass a
  82    *        negative to use the default interval, or 0 to fetch the remaining
  83    *        part of the file in one chunk.
  84    */
  85   void init(in nsIURI uri, in nsIFile destination, in long chunkSize,
  86             in long intervalInSeconds);
  87
  88   /**
  89    * The URI being fetched.
  90    */
  91   readonly attribute nsIURI URI;
  92
  93   /**
  94    * The URI being fetched after any redirects have been followed.  This
  95    * attribute is set just prior to calling OnStartRequest on the observer
  96    * passed to the start method.
  97    */
  98   readonly attribute nsIURI finalURI;
  99
 100   /**
 101    * The file where the download is being written.
 102    */
 103   readonly attribute nsIFile destination;
 104
 105   /**
 106    * The total number of bytes for the requested file.  This attribute is set
 107    * just prior to calling OnStartRequest on the observer passed to the start
 108    * method.
 109    *
 110    * This attribute has a value of -1 if the total size is unknown.
 111    */
 112   readonly attribute long long totalSize;
 113
 114   /**
 115    * The current number of bytes downloaded so far.  This attribute is set just
 116    * prior to calling OnStartRequest on the observer passed to the start
 117    * method.
 118    *
 119    * This attribute has a value of -1 if the current size is unknown.
 120    */
 121   readonly attribute long long currentSize;
 122
 123   /**
 124    * Start the incremental download.
 125    *
 126    * @param observer
 127    *        An observer to be notified of various events.  OnStartRequest is
 128    *        called when finalURI and totalSize have been determined or when an
 129    *        error occurs.  OnStopRequest is called when the file is completely
 130    *        downloaded or when an error occurs.  If this object implements
 131    *        nsIProgressEventSink, then its OnProgress method will be called as
 132    *        data is written to the destination file.  If this object implements
 133    *        nsIInterfaceRequestor, then it will be assigned as the underlying
 134    *        channel's notification callbacks, which allows it to provide a
 135    *        nsIAuthPrompt implementation if needed by the channel, for example.
 136    * @param ctxt
 137    *        User defined object forwarded to the observer's methods.
 138    */
 139   void start(in nsIRequestObserver observer,
 140              in nsISupports ctxt);
 141 };