• file
• revisions
• annotate
• diff
• comparison
• raw

toolkit/components/downloads/nsIDownload.idl@925c144e1f1f (annotated)

toolkit/components/downloads/nsIDownload.idl

Fri, 16 Jan 2015 18:13:44 +0100

author

Michael Schloh von Bennewitz <michael@schloh.com>

date

Fri, 16 Jan 2015 18:13:44 +0100

branch

TOR_BUG_9701

changeset 14

925c144e1f1f

permissions

-rw-r--r--

Integrate suggestion from review to improve consistency with existing code.

michael@0	1	/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
michael@0	2	/* This Source Code Form is subject to the terms of the Mozilla Public
michael@0	3	* License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0	4	* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0	5
michael@0	6	#include "nsITransfer.idl"
michael@0	7
michael@0	8	interface nsIURI;
michael@0	9	interface nsIFile;
michael@0	10	interface nsIObserver;
michael@0	11	interface nsICancelable;
michael@0	12	interface nsIWebProgressListener;
michael@0	13	interface nsIMIMEInfo;
michael@0	14
michael@0	15	/**
michael@0	16	* Represents a download object.
michael@0	17	*
michael@0	18	* @note This object is no longer updated once it enters a completed state.
michael@0	19	* Completed states are the following:
michael@0	20	* nsIDownloadManager::DOWNLOAD_FINISHED
michael@0	21	* nsIDownloadManager::DOWNLOAD_FAILED
michael@0	22	* nsIDownloadManager::DOWNLOAD_CANCELED
michael@0	23	* nsIDownloadManager::DOWNLOAD_BLOCKED_PARENTAL
michael@0	24	* nsIDownloadManager::DOWNLOAD_DIRTY
michael@0	25	* nsIDownloadManager::DOWNLOAD_BLOCKED_POLICY
michael@0	26	*/
michael@0	27	[scriptable, uuid(b02be33b-d47c-4bd3-afd9-402a942426b0)]
michael@0	28	interface nsIDownload : nsITransfer {
michael@0	29
michael@0	30	/**
michael@0	31	* The target of a download is always a file on the local file system.
michael@0	32	*/
michael@0	33	readonly attribute nsIFile targetFile;
michael@0	34
michael@0	35	/**
michael@0	36	* The percentage of transfer completed.
michael@0	37	* If the file size is unknown it'll be -1 here.
michael@0	38	*/
michael@0	39	readonly attribute long percentComplete;
michael@0	40
michael@0	41	/**
michael@0	42	* The amount of bytes downloaded so far.
michael@0	43	*/
michael@0	44	readonly attribute long long amountTransferred;
michael@0	45
michael@0	46	/**
michael@0	47	* The size of file in bytes.
michael@0	48	* Unknown size is represented by -1.
michael@0	49	*/
michael@0	50	readonly attribute long long size;
michael@0	51
michael@0	52	/**
michael@0	53	* The source of the transfer.
michael@0	54	*/
michael@0	55	readonly attribute nsIURI source;
michael@0	56
michael@0	57	/**
michael@0	58	* The target of the transfer.
michael@0	59	*/
michael@0	60	readonly attribute nsIURI target;
michael@0	61
michael@0	62	/**
michael@0	63	* Object that can be used to cancel the download.
michael@0	64	* Will be null after the download is finished.
michael@0	65	*/
michael@0	66	readonly attribute nsICancelable cancelable;
michael@0	67
michael@0	68	/**
michael@0	69	* The user-readable description of the transfer.
michael@0	70	*/
michael@0	71	readonly attribute AString displayName;
michael@0	72
michael@0	73	/**
michael@0	74	* The time a transfer was started.
michael@0	75	*/
michael@0	76	readonly attribute long long startTime;
michael@0	77
michael@0	78	/**
michael@0	79	* The speed of the transfer in bytes/sec.
michael@0	80	*/
michael@0	81	readonly attribute double speed;
michael@0	82
michael@0	83	/**
michael@0	84	* Optional. If set, it will contain the target's relevant MIME information.
michael@0	85	* This includes its MIME Type, helper app, and whether that helper should be
michael@0	86	* executed.
michael@0	87	*/
michael@0	88	readonly attribute nsIMIMEInfo MIMEInfo;
michael@0	89
michael@0	90	/**
michael@0	91	* The id of the download that is stored in the database - not globally unique.
michael@0	92	* For example, a private download and a public one might have identical ids.
michael@0	93	* Can only be safely used for direct database manipulation in the database that
michael@0	94	* contains this download. Use the guid property instead for safe, database-agnostic
michael@0	95	* searching and manipulation.
michael@0	96	*
michael@0	97	* @deprecated
michael@0	98	*/
michael@0	99	readonly attribute unsigned long id;
michael@0	100
michael@0	101	/**
michael@0	102	* The guid of the download that is stored in the database.
michael@0	103	* Has the form of twelve alphanumeric characters.
michael@0	104	*/
michael@0	105	readonly attribute ACString guid;
michael@0	106
michael@0	107	/**
michael@0	108	* The state of the download.
michael@0	109	* @see nsIDownloadManager and nsIXPInstallManagerUI
michael@0	110	*/
michael@0	111	readonly attribute short state;
michael@0	112
michael@0	113	/**
michael@0	114	* The referrer uri of the download. This is only valid for HTTP downloads,
michael@0	115	* and can be null.
michael@0	116	*/
michael@0	117	readonly attribute nsIURI referrer;
michael@0	118
michael@0	119	/**
michael@0	120	* Indicates if the download can be resumed after being paused or not. This
michael@0	121	* is only the case if the download is over HTTP/1.1 or FTP and if the
michael@0	122	* server supports it.
michael@0	123	*/
michael@0	124	readonly attribute boolean resumable;
michael@0	125
michael@0	126	/**
michael@0	127	* Indicates if the download was initiated from a context marked as private,
michael@0	128	* controlling whether it should be stored in a permanent manner or not.
michael@0	129	*/
michael@0	130	readonly attribute boolean isPrivate;
michael@0	131
michael@0	132	/**
michael@0	133	* Cancel this download if it's currently in progress.
michael@0	134	*/
michael@0	135	void cancel();
michael@0	136
michael@0	137	/**
michael@0	138	* Pause this download if it is in progress.
michael@0	139	*
michael@0	140	* @throws NS_ERROR_UNEXPECTED if it cannot be paused.
michael@0	141	*/
michael@0	142	void pause();
michael@0	143
michael@0	144	/**
michael@0	145	* Resume this download if it is paused.
michael@0	146	*
michael@0	147	* @throws NS_ERROR_UNEXPECTED if it cannot be resumed or is not paused.
michael@0	148	*/
michael@0	149	void resume();
michael@0	150
michael@0	151	/**
michael@0	152	* Instruct the download manager to remove this download. Whereas
michael@0	153	* cancel simply cancels the transfer, but retains information about it,
michael@0	154	* remove removes all knowledge of it.
michael@0	155	*
michael@0	156	* @see nsIDownloadManager.removeDownload for more detail
michael@0	157	* @throws NS_ERROR_FAILURE if the download is active.
michael@0	158	*/
michael@0	159	void remove();
michael@0	160
michael@0	161	/**
michael@0	162	* Instruct the download manager to retry this failed download
michael@0	163	* @throws NS_ERROR_NOT_AVAILABLE if the download is not known.
michael@0	164	* @throws NS_ERROR_FAILURE if the download is not in the following states:
michael@0	165	* nsIDownloadManager::DOWNLOAD_CANCELED
michael@0	166	* nsIDownloadManager::DOWNLOAD_FAILED
michael@0	167	*/
michael@0	168	void retry();
michael@0	169	};
michael@0	170
michael@0	171	%{C++
michael@0	172	// {b02be33b-d47c-4bd3-afd9-402a942426b0}
michael@0	173	#define NS_DOWNLOAD_CID \
michael@0	174	{ 0xb02be33b, 0xd47c, 0x4bd3, { 0xaf, 0xd9, 0x40, 0x2a, 0x94, 0x24, 0x26, 0xb0 } }
michael@0	175	%}