gecko/toolkit/components/downloads/nsIDownload.idl
2012-11-16 10:44:20 +00:00

176 lines
5.0 KiB
Plaintext

/* -*- 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 } }
%}