gecko-dev/toolkit/components/downloads/nsIDownload.idl

/* -*- 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 "nsITransfer.idl"

interface nsIURI;
interface nsIFile;
interface nsIObserver;
interface nsICancelable;
interface nsIWebProgressListener;
interface nsIMIMEInfo;

/**
 * Represents a download object.
 *
 * @note This object is no longer updated once it enters a completed state.
 *       Completed states are the following:  
 *       nsIDownloadManager::DOWNLOAD_FINISHED  
 *       nsIDownloadManager::DOWNLOAD_FAILED  
 *       nsIDownloadManager::DOWNLOAD_CANCELED 
 *       nsIDownloadManager::DOWNLOAD_BLOCKED_PARENTAL 
 *       nsIDownloadManager::DOWNLOAD_DIRTY 
 *       nsIDownloadManager::DOWNLOAD_BLOCKED_POLICY 
 */
[scriptable, uuid(b02be33b-d47c-4bd3-afd9-402a942426b0)]
interface nsIDownload : nsITransfer {
    
    /**
     * The target of a download is always a file on the local file system.
     */
    readonly attribute nsIFile targetFile;

    /**
     * The percentage of transfer completed.
     * If the file size is unknown it'll be -1 here.
     */
    readonly attribute long percentComplete;

    /**
     * The amount of bytes downloaded so far.
     */
    readonly attribute long long amountTransferred;

    /**
     * The size of file in bytes.
     * Unknown size is represented by -1.
     */
    readonly attribute long long size;
    
    /**
     * The source of the transfer.
     */
    readonly attribute nsIURI source;
    
    /**
     * The target of the transfer.
     */
    readonly attribute nsIURI target;
 
    /**
     * Object that can be used to cancel the download.
     * Will be null after the download is finished.
     */
    readonly attribute nsICancelable cancelable;

    /**
     * The user-readable description of the transfer.
     */
    readonly attribute AString displayName;

    /**
     * The time a transfer was started.
     */
    readonly attribute long long startTime;

    /**
     * The speed of the transfer in bytes/sec.
     */
    readonly attribute double speed;

    /**
     * Optional. If set, it will contain the target's relevant MIME information.
     * This includes its MIME Type, helper app, and whether that helper should be
     * executed.
     */
    readonly attribute nsIMIMEInfo MIMEInfo;

    /**
     * The id of the download that is stored in the database - not globally unique.
     * For example, a private download and a public one might have identical ids.
     * Can only be safely used for direct database manipulation in the database that
     * contains this download. Use the guid property instead for safe, database-agnostic
     * searching and manipulation.
     *
     * @deprecated
     */
    readonly attribute unsigned long id;

    /**
     * The guid of the download that is stored in the database.
     * Has the form of twelve alphanumeric characters.
     */
    readonly attribute ACString guid;

    /**
     * The state of the download.
     * @see nsIDownloadManager and nsIXPInstallManagerUI
     */
    readonly attribute short state;

    /**
     * The referrer uri of the download.  This is only valid for HTTP downloads,
     * and can be null.
     */
    readonly attribute nsIURI referrer;

    /**
     * Indicates if the download can be resumed after being paused or not.  This
     * is only the case if the download is over HTTP/1.1 or FTP and if the
     * server supports it.
     */
    readonly attribute boolean resumable;

    /**
     * Indicates if the download was initiated from a context marked as private,
     * controlling whether it should be stored in a permanent manner or not.
     */
    readonly attribute boolean isPrivate;

    /**
     * Cancel this download if it's currently in progress.
     */
    void cancel();

    /**
     * Pause this download if it is in progress.
     *
     * @throws NS_ERROR_UNEXPECTED if it cannot be paused.
     */
    void pause();

    /**
     * Resume this download if it is paused.
     *
     * @throws NS_ERROR_UNEXPECTED if it cannot be resumed or is not paused.
     */
    void resume();

    /**
     * Instruct the download manager to remove this download. Whereas
     * cancel simply cancels the transfer, but retains information about it,
     * remove removes all knowledge of it.
     *
     * @see nsIDownloadManager.removeDownload for more detail
     * @throws NS_ERROR_FAILURE if the download is active.
     */
    void remove();

    /**
     * Instruct the download manager to retry this failed download
     * @throws NS_ERROR_NOT_AVAILABLE if the download is not known.
     * @throws NS_ERROR_FAILURE if the download is not in the following states:
     *         nsIDownloadManager::DOWNLOAD_CANCELED
     *         nsIDownloadManager::DOWNLOAD_FAILED
     */
    void retry();
};

%{C++
// {b02be33b-d47c-4bd3-afd9-402a942426b0}
#define NS_DOWNLOAD_CID \
  { 0xb02be33b, 0xd47c, 0x4bd3, { 0xaf, 0xd9, 0x40, 0x2a, 0x94, 0x24, 0x26, 0xb0 } }
%}