1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/toolkit/components/downloads/nsIDownload.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,175 @@
1.4 +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsITransfer.idl"
1.10 +
1.11 +interface nsIURI;
1.12 +interface nsIFile;
1.13 +interface nsIObserver;
1.14 +interface nsICancelable;
1.15 +interface nsIWebProgressListener;
1.16 +interface nsIMIMEInfo;
1.17 +
1.18 +/**
1.19 + * Represents a download object.
1.20 + *
1.21 + * @note This object is no longer updated once it enters a completed state.
1.22 + * Completed states are the following:
1.23 + * nsIDownloadManager::DOWNLOAD_FINISHED
1.24 + * nsIDownloadManager::DOWNLOAD_FAILED
1.25 + * nsIDownloadManager::DOWNLOAD_CANCELED
1.26 + * nsIDownloadManager::DOWNLOAD_BLOCKED_PARENTAL
1.27 + * nsIDownloadManager::DOWNLOAD_DIRTY
1.28 + * nsIDownloadManager::DOWNLOAD_BLOCKED_POLICY
1.29 + */
1.30 +[scriptable, uuid(b02be33b-d47c-4bd3-afd9-402a942426b0)]
1.31 +interface nsIDownload : nsITransfer {
1.32 +
1.33 + /**
1.34 + * The target of a download is always a file on the local file system.
1.35 + */
1.36 + readonly attribute nsIFile targetFile;
1.37 +
1.38 + /**
1.39 + * The percentage of transfer completed.
1.40 + * If the file size is unknown it'll be -1 here.
1.41 + */
1.42 + readonly attribute long percentComplete;
1.43 +
1.44 + /**
1.45 + * The amount of bytes downloaded so far.
1.46 + */
1.47 + readonly attribute long long amountTransferred;
1.48 +
1.49 + /**
1.50 + * The size of file in bytes.
1.51 + * Unknown size is represented by -1.
1.52 + */
1.53 + readonly attribute long long size;
1.54 +
1.55 + /**
1.56 + * The source of the transfer.
1.57 + */
1.58 + readonly attribute nsIURI source;
1.59 +
1.60 + /**
1.61 + * The target of the transfer.
1.62 + */
1.63 + readonly attribute nsIURI target;
1.64 +
1.65 + /**
1.66 + * Object that can be used to cancel the download.
1.67 + * Will be null after the download is finished.
1.68 + */
1.69 + readonly attribute nsICancelable cancelable;
1.70 +
1.71 + /**
1.72 + * The user-readable description of the transfer.
1.73 + */
1.74 + readonly attribute AString displayName;
1.75 +
1.76 + /**
1.77 + * The time a transfer was started.
1.78 + */
1.79 + readonly attribute long long startTime;
1.80 +
1.81 + /**
1.82 + * The speed of the transfer in bytes/sec.
1.83 + */
1.84 + readonly attribute double speed;
1.85 +
1.86 + /**
1.87 + * Optional. If set, it will contain the target's relevant MIME information.
1.88 + * This includes its MIME Type, helper app, and whether that helper should be
1.89 + * executed.
1.90 + */
1.91 + readonly attribute nsIMIMEInfo MIMEInfo;
1.92 +
1.93 + /**
1.94 + * The id of the download that is stored in the database - not globally unique.
1.95 + * For example, a private download and a public one might have identical ids.
1.96 + * Can only be safely used for direct database manipulation in the database that
1.97 + * contains this download. Use the guid property instead for safe, database-agnostic
1.98 + * searching and manipulation.
1.99 + *
1.100 + * @deprecated
1.101 + */
1.102 + readonly attribute unsigned long id;
1.103 +
1.104 + /**
1.105 + * The guid of the download that is stored in the database.
1.106 + * Has the form of twelve alphanumeric characters.
1.107 + */
1.108 + readonly attribute ACString guid;
1.109 +
1.110 + /**
1.111 + * The state of the download.
1.112 + * @see nsIDownloadManager and nsIXPInstallManagerUI
1.113 + */
1.114 + readonly attribute short state;
1.115 +
1.116 + /**
1.117 + * The referrer uri of the download. This is only valid for HTTP downloads,
1.118 + * and can be null.
1.119 + */
1.120 + readonly attribute nsIURI referrer;
1.121 +
1.122 + /**
1.123 + * Indicates if the download can be resumed after being paused or not. This
1.124 + * is only the case if the download is over HTTP/1.1 or FTP and if the
1.125 + * server supports it.
1.126 + */
1.127 + readonly attribute boolean resumable;
1.128 +
1.129 + /**
1.130 + * Indicates if the download was initiated from a context marked as private,
1.131 + * controlling whether it should be stored in a permanent manner or not.
1.132 + */
1.133 + readonly attribute boolean isPrivate;
1.134 +
1.135 + /**
1.136 + * Cancel this download if it's currently in progress.
1.137 + */
1.138 + void cancel();
1.139 +
1.140 + /**
1.141 + * Pause this download if it is in progress.
1.142 + *
1.143 + * @throws NS_ERROR_UNEXPECTED if it cannot be paused.
1.144 + */
1.145 + void pause();
1.146 +
1.147 + /**
1.148 + * Resume this download if it is paused.
1.149 + *
1.150 + * @throws NS_ERROR_UNEXPECTED if it cannot be resumed or is not paused.
1.151 + */
1.152 + void resume();
1.153 +
1.154 + /**
1.155 + * Instruct the download manager to remove this download. Whereas
1.156 + * cancel simply cancels the transfer, but retains information about it,
1.157 + * remove removes all knowledge of it.
1.158 + *
1.159 + * @see nsIDownloadManager.removeDownload for more detail
1.160 + * @throws NS_ERROR_FAILURE if the download is active.
1.161 + */
1.162 + void remove();
1.163 +
1.164 + /**
1.165 + * Instruct the download manager to retry this failed download
1.166 + * @throws NS_ERROR_NOT_AVAILABLE if the download is not known.
1.167 + * @throws NS_ERROR_FAILURE if the download is not in the following states:
1.168 + * nsIDownloadManager::DOWNLOAD_CANCELED
1.169 + * nsIDownloadManager::DOWNLOAD_FAILED
1.170 + */
1.171 + void retry();
1.172 +};
1.173 +
1.174 +%{C++
1.175 +// {b02be33b-d47c-4bd3-afd9-402a942426b0}
1.176 +#define NS_DOWNLOAD_CID \
1.177 + { 0xb02be33b, 0xd47c, 0x4bd3, { 0xaf, 0xd9, 0x40, 0x2a, 0x94, 0x24, 0x26, 0xb0 } }
1.178 +%}
