RetroZilla/xpfe/components/download-manager/public/nsIDownloadManager.idl

/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* vim:set ts=2 sw=2 sts=2 et: */
/* ***** BEGIN LICENSE BLOCK *****
 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
 *
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is mozilla.org code.
 *
 * The Initial Developer of the Original Code is
 * Netscape Communications Corporation.
 * Portions created by the Initial Developer are Copyright (C) 1998
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *   Blake Ross <blaker@netscape.com>
 *   Ben Goodger <ben@netscape.com>
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either of the GNU General Public License Version 2 or later (the "GPL"),
 * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the MPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the MPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */

// Keeps track of ongoing downloads, in the form of nsIDownload's. 

#include "nsISupports.idl"

interface nsIDOMWindow;
interface nsIURI;
interface nsILocalFile;
interface nsIDownload;
interface nsICancelable;
interface nsIMIMEInfo;

[scriptable, uuid(9cdfcea3-fbe4-4ba1-a0fd-fe273097ddfa)]
interface nsIDownloadManager : nsISupports {

  // Methods called by clients to carry out various managing functions

  /**
  * Creates an nsIDownload and adds it to be managed by the download manager.
  *
  * @param aSource The source URI of the transfer. Must not be null.
  *
  * @param aTarget The target URI of the transfer. Must not be null.
  *
  * @param aDisplayName The user-readable description of the transfer.
  *                     Can be empty.
  *
  * @param aMIMEInfo The MIME info associated with the target,
  *                  including MIME type and helper app when appropriate.
  *                  This parameter is optional.
  *
  * @param startTime Time when the download started (ie, when the first
  *                  response from the server was received)
  * @param aTempFile The location of a temporary file; i.e. a file in which
  *                  the received data will be stored, but which is not
  *                  equal to the target file. (will be moved to the real
  *                  target by the caller, when the download is finished)
  *                  May be null.
  *
  * @param aCancelable An object that can be used to abort the download.
  *                    Must not be null.

  * @return The newly created download item with the passed-in properties.
  */
  nsIDownload addDownload(in nsIURI aSource,
                          in nsIURI aTarget,
                          in AString aDisplayName,
                          in nsIMIMEInfo aMIMEInfo,
                          in PRTime startTime,
                          in nsILocalFile aTempFile,
                          in nsICancelable aCancelable);

  /**
  *  Retrieves an in-progress download managed by the download manager.
  *
  *  @param aTargetPath           A UTF8-encoded path to the target file.
  *
  *  @return The download with the specified path.
  */
  nsIDownload getDownload(in AUTF8String aTargetPath);

  /**
  * Cancels the download with the specified target path if it's
  * currently in progress.  If a "persist" was specified for the download,
  * nsIWebBrowserPersist::CancelSave will be called.  If an observer was set
  * on the nsIDownload, it will be notified with the "oncancel" topic.  Clients
  * that don't provide a "persist" must listen for this topic and cancel the
  * download.
  *
  * @param aTargetPath           The target path of the download to
  *                              be cancelled.
  */
  void cancelDownload(in AUTF8String aTargetPath);

  /**
   * Pause a download to allow later resumal. This may or may not close
   * the network connection. In either case, new data won't be received.
   *
   * @param aDownload Download to pause, as returned by getDownload or
   *                  addDownload.
   *
   * Trying to pause a download that is already paused will throw
   * NS_ERROR_NOT_AVAILABLE.
   * NS_ERROR_UNEXPECTED may be thrown to indicate an internal error.
   * Any exception defined by nsIRequest::Suspend may be thrown.
   * No other exceptions will be thrown.
   */
  void pauseDownload(in nsIDownload aDownload);

  /**
   * Resume a previously paused download.
   * @param aTargetPath Target path of the download to be resumed.
   *
   * @throws NS_ERROR_NOT_RESUMABLE If resuming is not supported for this
   *                                entity, or if the entity has changed since
   *                                the download was paused
   * @throws NS_ERROR_NOT_AVAILABLE If no such download exists, or if the
   *                                download was not paused, or if the
   *                                download is finished already.
   * In addition, this may throw NS_ERROR_OUT_OF_MEMORY, or any error defined by
   * nsIResumableChannel::setEntityID, nsIResumableChannel::asyncOpenAt,
   * nsIRequest::Resume, or nsIIOService::newChannel.
   * Also, NS_ERROR_UNEXPECTED may be thrown to indicate an internal error.
   */
  void resumeDownload(in AUTF8String aTargetPath);

  /**
  * Removes the download with the specified target path if it's not
  * currently in progress.  Whereas cancelDownload simply cancels the transfer
  * but retains information about it, removeDownload removes all knowledge of it.
  *
  * @param aTargetPath           The target path of the download to
  *                              be removed.
  */
  void removeDownload(in AUTF8String aTargetPath);

  // UI-related methods

  /**
  * Opens the Download Manager front end.
  *
  * @param aParent The parent, or opener, of the front end (optional).
  * @param aDownload A download to pass to the manager window.  Useful
  *                  if, for example, you want the window to select a
  *                  certain download (optional).
  */
  void open(in nsIDOMWindow aParent, in nsIDownload aDownload);

  /**
  * Opens an individual progress dialog displaying progress for the download.
  *
  * @param aDownload The download object to display progress for, as returned
  *                  by getDownload or addDownload.
  *
  * @param aParent The parent, or opener, of the front end (optional).
  *
  * @param aCancelDownloadOnClose       Whether closing the dialog
  *                                     should cancel the download.
  */

  void openProgressDialogFor(in nsIDownload aDownload,
                             in nsIDOMWindow aParent,
                             in boolean aCancelDownloadOnClose);

  /**
  * Called when the download manager front end is closed.  Useful for
  * third party managers to let us know when they've closed.
  */

  void onClose();
  
  /**
  * Indicate that a batch update (e.g. mass removal) is about to start.
  */

  void startBatchUpdate();
  
  /**
  * Indicate that a batch update is ending.
  */
  
  void endBatchUpdate();
};


%{C++
#define NS_DOWNLOADMANAGER_CONTRACTID "@mozilla.org/download-manager;1"
#define NS_DOWNLOADMANAGER_CLASSNAME "Mozilla Download Manager"
// {EDB0490E-1DD1-11B2-83B8-DBF8D85906A6}
#define NS_DOWNLOADMANAGER_CID \
    { 0xedb0490e, 0x1dd1, 0x11b2, { 0x83, 0xb8, 0xdb, 0xf8, 0xd8, 0x59, 0x06, 0xa6 } }
%}