/**
* Namespace: browser.downloads
* Generated from Mozilla sources. Do not manually edit!
*
* Permissions: "downloads"
*/
import { ExtensionTypes } from "./extensionTypes";
import { Events } from "./events";
export namespace Downloads {
type FilenameConflictAction = "uniquify" | "overwrite" | "prompt";
type InterruptReason =
| "FILE_FAILED"
| "FILE_ACCESS_DENIED"
| "FILE_NO_SPACE"
| "FILE_NAME_TOO_LONG"
| "FILE_TOO_LARGE"
| "FILE_VIRUS_INFECTED"
| "FILE_TRANSIENT_ERROR"
| "FILE_BLOCKED"
| "FILE_SECURITY_CHECK_FAILED"
| "FILE_TOO_SHORT"
| "NETWORK_FAILED"
| "NETWORK_TIMEOUT"
| "NETWORK_DISCONNECTED"
| "NETWORK_SERVER_DOWN"
| "NETWORK_INVALID_REQUEST"
| "SERVER_FAILED"
| "SERVER_NO_RANGE"
| "SERVER_BAD_CONTENT"
| "SERVER_UNAUTHORIZED"
| "SERVER_CERT_PROBLEM"
| "SERVER_FORBIDDEN"
| "USER_CANCELED"
| "USER_SHUTDOWN"
| "CRASH";
/**
* - file
- The download's filename is suspicious.
- url
- The download's URL is known to be
* malicious.
- content
- The downloaded file is known to be malicious.
- uncommon
-
* The download's URL is not commonly downloaded and could be dangerous.
- safe
-
* The download presents no known danger to the user's computer.
These string constants will never change,
* however the set of DangerTypes may change.
*/
type DangerType = "file" | "url" | "content" | "uncommon" | "host" | "unwanted" | "safe" | "accepted";
/**
* - in_progress
- The download is currently receiving data from the server.
- interrupted
-
* An error broke the connection with the file host.
- complete
- The download completed successfully.
* These string constants will never change, however the set of States may change.
*/
type State = "in_progress" | "interrupted" | "complete";
interface DownloadItem {
/**
* An identifier that is persistent across browser sessions.
*/
id: number;
/**
* Absolute URL.
*/
url: string;
/**
* Optional.
*/
referrer?: string;
/**
* Absolute local path.
*/
filename: string;
/**
* False if this download is recorded in the history, true if it is not recorded.
*/
incognito: boolean;
/**
* The cookie store ID of the contextual identity.
* Optional.
*/
cookieStoreId?: string;
/**
* Indication of whether this download is thought to be safe or known to be suspicious.
*/
danger: DangerType;
/**
* The file's MIME type.
* Optional.
*/
mime?: string;
/**
* Number of milliseconds between the unix epoch and when this download began.
*/
startTime: string;
/**
* Number of milliseconds between the unix epoch and when this download ended.
* Optional.
*/
endTime?: string;
/**
* Optional.
*/
estimatedEndTime?: string;
/**
* Indicates whether the download is progressing, interrupted, or complete.
*/
state: State;
/**
* True if the download has stopped reading data from the host, but kept the connection open.
*/
paused: boolean;
canResume: boolean;
/**
* Number indicating why a download was interrupted.
* Optional.
*/
error?: InterruptReason;
/**
* Number of bytes received so far from the host, without considering file compression.
*/
bytesReceived: number;
/**
* Number of bytes in the whole file, without considering file compression, or -1 if unknown.
*/
totalBytes: number;
/**
* Number of bytes in the whole file post-decompression, or -1 if unknown.
*/
fileSize: number;
exists: boolean;
/**
* Optional.
*/
byExtensionId?: string;
/**
* Optional.
*/
byExtensionName?: string;
}
interface StringDelta {
/**
* Optional.
*/
current?: string;
/**
* Optional.
*/
previous?: string;
}
interface DoubleDelta {
/**
* Optional.
*/
current?: number;
/**
* Optional.
*/
previous?: number;
}
interface BooleanDelta {
/**
* Optional.
*/
current?: boolean;
/**
* Optional.
*/
previous?: boolean;
}
/**
* A time specified as a Date object, a number or string representing milliseconds since the epoch, or an ISO 8601 string
*/
type DownloadTime = string | ExtensionTypes.DateType;
/**
* Parameters that combine to specify a predicate that can be used to select a set of downloads.
* Used for example in search() and erase()
*/
interface DownloadQuery {
/**
* This array of search terms limits results to DownloadItems whose filename
* or url contain all of the search terms that do not begin with a dash '-' and none of the search terms that
* do begin with a dash.
* Optional.
*/
query?: string[];
/**
* Limits results to downloads that started before the given ms since the epoch.
* Optional.
*/
startedBefore?: DownloadTime;
/**
* Limits results to downloads that started after the given ms since the epoch.
* Optional.
*/
startedAfter?: DownloadTime;
/**
* Limits results to downloads that ended before the given ms since the epoch.
* Optional.
*/
endedBefore?: DownloadTime;
/**
* Limits results to downloads that ended after the given ms since the epoch.
* Optional.
*/
endedAfter?: DownloadTime;
/**
* Limits results to downloads whose totalBytes is greater than the given integer.
* Optional.
*/
totalBytesGreater?: number;
/**
* Limits results to downloads whose totalBytes is less than the given integer.
* Optional.
*/
totalBytesLess?: number;
/**
* Limits results to DownloadItems whose filename
* matches the given regular expression.
* Optional.
*/
filenameRegex?: string;
/**
* Limits results to DownloadItems whose url
* matches the given regular expression.
* Optional.
*/
urlRegex?: string;
/**
* Setting this integer limits the number of results. Otherwise, all matching DownloadItems
* will be returned.
* Optional.
*/
limit?: number;
/**
* Setting elements of this array to DownloadItem properties in order to sort the search
* results. For example, setting orderBy='startTime' sorts the DownloadItems
* by their start time in ascending order. To specify descending order, prefix orderBy
* with a hyphen: '-startTime'.
* Optional.
*/
orderBy?: string[];
/**
* Optional.
*/
id?: number;
/**
* Absolute URL.
* Optional.
*/
url?: string;
/**
* Absolute local path.
* Optional.
*/
filename?: string;
/**
* The cookie store ID of the contextual identity.
* Optional.
*/
cookieStoreId?: string;
/**
* Indication of whether this download is thought to be safe or known to be suspicious.
* Optional.
*/
danger?: DangerType;
/**
* The file's MIME type.
* Optional.
*/
mime?: string;
/**
* Optional.
*/
startTime?: string;
/**
* Optional.
*/
endTime?: string;
/**
* Indicates whether the download is progressing, interrupted, or complete.
* Optional.
*/
state?: State;
/**
* True if the download has stopped reading data from the host, but kept the connection open.
* Optional.
*/
paused?: boolean;
/**
* Why a download was interrupted.
* Optional.
*/
error?: InterruptReason;
/**
* Number of bytes received so far from the host, without considering file compression.
* Optional.
*/
bytesReceived?: number;
/**
* Number of bytes in the whole file, without considering file compression, or -1 if unknown.
* Optional.
*/
totalBytes?: number;
/**
* Number of bytes in the whole file post-decompression, or -1 if unknown.
* Optional.
*/
fileSize?: number;
/**
* Optional.
*/
exists?: boolean;
}
/**
* What to download and how.
*/
interface DownloadOptionsType {
/**
* The URL to download.
*/
url: string;
/**
* A file path relative to the Downloads directory to contain the downloaded file.
* Optional.
*/
filename?: string;
/**
* Whether to associate the download with a private browsing session.
* Optional.
*/
incognito?: boolean;
/**
* The cookie store ID of the contextual identity; requires "cookies" permission.
* Optional.
*/
cookieStoreId?: string;
/**
* Optional.
*/
conflictAction?: FilenameConflictAction;
/**
* Use a file-chooser to allow the user to select a filename. If the option is not specified,
* the file chooser will be shown only if the Firefox "Always ask you where to save files" option is enabled (i.e.
* the pref browser.download.useDownloadDir is set to false).
* Optional.
*/
saveAs?: boolean;
/**
* The HTTP method to use if the URL uses the HTTP[S] protocol.
* Optional.
*/
method?: DownloadOptionsTypeMethodEnum;
/**
* Extra HTTP headers to send with the request if the URL uses the HTTP[s] protocol. Each header is represented as a
* dictionary containing the keys name and either value or binaryValue,
* restricted to those allowed by XMLHttpRequest.
* Optional.
*/
headers?: DownloadOptionsTypeHeadersItemType[];
/**
* Post body.
* Optional.
*/
body?: string;
/**
* When this flag is set to true, then the browser will allow downloads to proceed after encountering HTTP
* errors such as 404 Not Found.
* Optional.
*/
allowHttpErrors?: boolean;
}
interface GetFileIconOptionsType {
/**
* The size of the icon. The returned icon will be square with dimensions size * size pixels.
* The default size for the icon is 32x32 pixels.
* Optional.
*/
size?: number;
}
interface OnChangedDownloadDeltaType {
/**
* The id of the DownloadItem that changed.
*/
id: number;
/**
* Describes a change in a DownloadItem's url.
* Optional.
*/
url?: StringDelta;
/**
* Describes a change in a DownloadItem's filename.
* Optional.
*/
filename?: StringDelta;
/**
* Describes a change in a DownloadItem's danger.
* Optional.
*/
danger?: StringDelta;
/**
* Describes a change in a DownloadItem's mime.
* Optional.
*/
mime?: StringDelta;
/**
* Describes a change in a DownloadItem's startTime.
* Optional.
*/
startTime?: StringDelta;
/**
* Describes a change in a DownloadItem's endTime.
* Optional.
*/
endTime?: StringDelta;
/**
* Describes a change in a DownloadItem's state.
* Optional.
*/
state?: StringDelta;
/**
* Optional.
*/
canResume?: BooleanDelta;
/**
* Describes a change in a DownloadItem's paused.
* Optional.
*/
paused?: BooleanDelta;
/**
* Describes a change in a DownloadItem's error.
* Optional.
*/
error?: StringDelta;
/**
* Describes a change in a DownloadItem's totalBytes.
* Optional.
*/
totalBytes?: DoubleDelta;
/**
* Describes a change in a DownloadItem's fileSize.
* Optional.
*/
fileSize?: DoubleDelta;
/**
* Optional.
*/
exists?: BooleanDelta;
}
/**
* The HTTP method to use if the URL uses the HTTP[S] protocol.
*/
type DownloadOptionsTypeMethodEnum = "GET" | "POST";
interface DownloadOptionsTypeHeadersItemType {
/**
* Name of the HTTP header.
*/
name: string;
/**
* Value of the HTTP header.
*/
value: string;
}
interface Static {
/**
* Download a URL. If the URL uses the HTTP[S] protocol, then the request will include all cookies currently set for its
* hostname. If both filename and saveAs are specified, then the Save As dialog will be displayed,
* pre-populated with the specified filename. If the download started successfully, callback
* will be called with the new DownloadItem's downloadId.
* If there was an error starting the download, then callback will be called with
* downloadId=undefined and chrome.extension.lastError
* will contain a descriptive string. The error strings are not guaranteed to remain backwards compatible between releases.
* You must not parse it.
*
* @param options What to download and how.
*/
download(options: DownloadOptionsType): Promise;
/**
* Find DownloadItems. Set query to the empty object to get all DownloadItems. To get a specific DownloadItem,
* set only the id field.
*
* @param query
*/
search(query: DownloadQuery): Promise;
/**
* Pause the download. If the request was successful the download is in a paused state. Otherwise chrome.extension.lastError contains an error message.
* The request will fail if the download is not active.
*
* @param downloadId The id of the download to pause.
*/
pause(downloadId: number): Promise;
/**
* Resume a paused download. If the request was successful the download is in progress and unpaused.
* Otherwise chrome.extension.lastError contains an error message.
* The request will fail if the download is not active.
*
* @param downloadId The id of the download to resume.
*/
resume(downloadId: number): Promise;
/**
* Cancel a download. When callback is run, the download is cancelled, completed,
* interrupted or doesn't exist anymore.
*
* @param downloadId The id of the download to cancel.
*/
cancel(downloadId: number): Promise;
/**
* Retrieve an icon for the specified download. For new downloads, file icons are available after the onCreated event has been received. The image returned by this function while a download is
* in progress may be different from the image returned after the download is complete.
* Icon retrieval is done by querying the underlying operating system or toolkit depending on the platform.
* The icon that is returned will therefore depend on a number of factors including state of the download, platform,
* registered file types and visual theme. If a file icon cannot be determined, chrome.extension.lastError will contain an error message.
*
* @param downloadId The identifier for the download.
* @param options Optional.
*/
getFileIcon(downloadId: number, options?: GetFileIconOptionsType): Promise;
/**
* Open the downloaded file.
*
* @param downloadId
*/
open(downloadId: number): Promise;
/**
* Show the downloaded file in its folder in a file manager.
*
* @param downloadId
*/
show(downloadId: number): Promise;
showDefaultFolder(): void;
/**
* Erase matching DownloadItems from history
*
* @param query
*/
erase(query: DownloadQuery): Promise;
/**
* @param downloadId
*/
removeFile(downloadId: number): Promise;
/**
* This event fires with the DownloadItem object when a download begins.
*
* @param downloadItem
*/
onCreated: Events.Event<(downloadItem: DownloadItem) => void>;
/**
* Fires with the downloadId when a download is erased from history.
*
* @param downloadId The id of the DownloadItem that was erased.
*/
onErased: Events.Event<(downloadId: number) => void>;
/**
* When any of a DownloadItem's properties except bytesReceived changes,
* this event fires with the downloadId and an object containing the properties that changed.
*
* @param downloadDelta
*/
onChanged: Events.Event<(downloadDelta: OnChangedDownloadDeltaType) => void>;
}
}