diff options
Diffstat (limited to 'toolkit/components/bitsdownload/nsIBits.idl')
| -rw-r--r-- | toolkit/components/bitsdownload/nsIBits.idl | 427 |
1 files changed, 427 insertions, 0 deletions
diff --git a/toolkit/components/bitsdownload/nsIBits.idl b/toolkit/components/bitsdownload/nsIBits.idl new file mode 100644 index 0000000000..993c10243c --- /dev/null +++ b/toolkit/components/bitsdownload/nsIBits.idl @@ -0,0 +1,427 @@ +/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ +/* 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 "nsIRequest.idl" + +interface nsIRequest; +interface nsIRequestObserver; + +interface nsIBitsRequest; + +interface nsIBitsNewRequestCallback; +interface nsIBitsCallback; + +typedef long nsProxyUsage; +typedef long nsBitsErrorType; +typedef long nsBitsErrorAction; +typedef long nsBitsErrorStage; + +/** + * An interface for interacting with Windows Background Intelligent Transfer + * Service. This should only be used on Windows. + * + * It would be preferable for the functions in this interface to return + * Promises, but this interface is implemented in Rust, which does not yet have + * support for Promises. There is a JS wrapper around this class that should be + * preferred over using this interface directly, located in Bits.sys.mjs. + * + * Methods of this class that take a nsIBitsNewRequestCallback do not return or + * throw errors. All errors will be reported through the callback. The only + * things that should cause methods to directly throw errors are null arguments. + */ +[scriptable, uuid(495d6f3d-9748-4d30-8ce5-0290c0001edf)] +interface nsIBits : nsISupports +{ + /** + * nsBitsErrorType values + * The BITS interface returns many error codes. These are intended to help + * determine appropriate fallback actions and to report to telemetry. + */ + const long ERROR_TYPE_SUCCESS = 0; + const long ERROR_TYPE_UNKNOWN = 1; + const long ERROR_TYPE_METHOD_THREW = 2; + const long ERROR_TYPE_METHOD_TIMEOUT = 3; + const long ERROR_TYPE_NULL_ARGUMENT = 4; + const long ERROR_TYPE_INVALID_ARGUMENT = 5; + const long ERROR_TYPE_NOT_INITIALIZED = 6; + const long ERROR_TYPE_NO_UTF8_CONVERSION = 7; + const long ERROR_TYPE_INVALID_GUID = 8; + const long ERROR_TYPE_PIPE_NOT_CONNECTED = 9; + const long ERROR_TYPE_PIPE_TIMEOUT = 10; + const long ERROR_TYPE_PIPE_BAD_WRITE_COUNT = 11; + const long ERROR_TYPE_PIPE_API_ERROR = 12; + const long ERROR_TYPE_FAILED_TO_CREATE_BITS_JOB = 13; + const long ERROR_TYPE_FAILED_TO_ADD_FILE_TO_JOB = 14; + const long ERROR_TYPE_FAILED_TO_APPLY_BITS_JOB_SETTINGS = 15; + const long ERROR_TYPE_FAILED_TO_RESUME_BITS_JOB = 16; + const long ERROR_TYPE_OTHER_BITS_ERROR = 17; + const long ERROR_TYPE_OTHER_BITS_CLIENT_ERROR = 18; + const long ERROR_TYPE_BITS_JOB_NOT_FOUND = 19; + const long ERROR_TYPE_FAILED_TO_GET_BITS_JOB = 20; + const long ERROR_TYPE_FAILED_TO_SUSPEND_BITS_JOB = 21; + const long ERROR_TYPE_FAILED_TO_COMPLETE_BITS_JOB = 22; + const long ERROR_TYPE_PARTIALLY_COMPLETED_BITS_JOB = 23; + const long ERROR_TYPE_FAILED_TO_CANCEL_BITS_JOB = 24; + const long ERROR_TYPE_MISSING_RESULT_DATA = 25; + const long ERROR_TYPE_MISSING_CALLBACK = 26; + const long ERROR_TYPE_CALLBACK_ON_WRONG_THREAD = 27; + const long ERROR_TYPE_MISSING_BITS_SERVICE = 28; + const long ERROR_TYPE_BITS_SERVICE_ON_WRONG_THREAD = 29; + const long ERROR_TYPE_MISSING_BITS_REQUEST = 30; + const long ERROR_TYPE_BITS_REQUEST_ON_WRONG_THREAD = 31; + const long ERROR_TYPE_MISSING_OBSERVER = 32; + const long ERROR_TYPE_OBSERVER_ON_WRONG_THREAD = 33; + const long ERROR_TYPE_MISSING_CONTEXT = 34; + const long ERROR_TYPE_CONTEXT_ON_WRONG_THREAD = 35; + const long ERROR_TYPE_FAILED_TO_START_THREAD = 36; + const long ERROR_TYPE_FAILED_TO_CONSTRUCT_TASK_RUNNABLE = 37; + const long ERROR_TYPE_FAILED_TO_DISPATCH_RUNNABLE = 38; + const long ERROR_TYPE_TRANSFER_ALREADY_COMPLETE = 39; + const long ERROR_TYPE_OPERATION_ALREADY_IN_PROGRESS = 40; + const long ERROR_TYPE_MISSING_BITS_CLIENT = 41; + const long ERROR_TYPE_FAILED_TO_GET_JOB_STATUS = 42; + const long ERROR_TYPE_BITS_STATE_ERROR = 43; + const long ERROR_TYPE_BITS_STATE_TRANSIENT_ERROR = 44; + const long ERROR_TYPE_BITS_STATE_CANCELLED = 45; + const long ERROR_TYPE_BITS_STATE_UNEXPECTED = 46; + const long ERROR_TYPE_VERIFICATION_FAILURE = 47; + const long ERROR_TYPE_ACCESS_DENIED_EXPECTED = 48; + const long ERROR_TYPE_FAILED_TO_CONNECT_TO_BCM = 49; + const long ERROR_TYPE_USE_AFTER_REQUEST_SHUTDOWN = 50; + const long ERROR_TYPE_BROWSER_SHUTTING_DOWN = 51; + /** + * nsBitsErrorAction values + * These values indicate where the error occurred. + */ + const long ERROR_ACTION_UNKNOWN = 1; + const long ERROR_ACTION_NONE = 2; + const long ERROR_ACTION_START_DOWNLOAD = 3; + const long ERROR_ACTION_MONITOR_DOWNLOAD = 4; + const long ERROR_ACTION_CHANGE_MONITOR_INTERVAL = 5; + const long ERROR_ACTION_CANCEL = 6; + const long ERROR_ACTION_SET_PRIORITY = 7; + const long ERROR_ACTION_COMPLETE = 8; + const long ERROR_ACTION_SUSPEND = 9; + const long ERROR_ACTION_RESUME = 10; + const long ERROR_ACTION_SET_NO_PROGRESS_TIMEOUT = 11; + + /** + * nsBitsErrorStage values + * These values allow the caller to determine at what point in the download + * mechanism a failure occurred. + */ + const long ERROR_STAGE_UNKNOWN = 1; + const long ERROR_STAGE_PRETASK = 2; + const long ERROR_STAGE_COMMAND_THREAD = 3; + const long ERROR_STAGE_AGENT_COMMUNICATION = 4; + const long ERROR_STAGE_BITS_CLIENT = 5; + const long ERROR_STAGE_MAIN_THREAD = 6; + const long ERROR_STAGE_MONITOR = 7; + const long ERROR_STAGE_VERIFICATION = 8; + + /** + * These values indicate what type of error code was returned. These are used + * to allow the different types taken by the different callback failure + * functions to be made into one generic error type in Javascript. + */ + const long ERROR_CODE_TYPE_NONE = 1; + const long ERROR_CODE_TYPE_NSRESULT = 2; + const long ERROR_CODE_TYPE_HRESULT = 3; + const long ERROR_CODE_TYPE_STRING = 4; + const long ERROR_CODE_TYPE_EXCEPTION = 5; + + /** + * Indicates whether init() has been called. + */ + readonly attribute boolean initialized; + + /** + * Initializes the BITS interface. Unlike other functions here, this happens + * synchronously. + * init() should only be called only once. + * + * @param jobName + * The name of the BITS job. This is used both to set the name during + * job creation and to verify that a job is ours. + * @param savePathPrefix + * The directory that downloads will be saved to. Providing a safe + * directory here ensures that the download path cannot be manipulated + * to save files to a malicious location. Downloads are guaranteed to + * be saved to this directory or a subdirectory. + * @param monitorTimeoutMs + * The amount of time to wait between download monitor notifications. + * This should be larger than the largest monitorIntervalMs that will + * be passed to startDownload(), monitorDownload(), or + * changeMonitorInterval(). This value may not be 0. + */ + void init(in AUTF8String jobName, + in AUTF8String savePathPrefix, + in unsigned long monitorTimeoutMs); + + /** + * Downloads the specified URL to the specified location within the + * savePathPrefix passed to init(). + * + * @param downloadURL + * The URL to be downloaded. + * @param saveRelativePath + * The location to download to. The path given should be a path + * relative to the savePathPrefix passed to init(). If this attempts to + * escape the directory specified by savePathPrefix, this call will + * fail (ex: Don't pass "../filename"). + * @param proxy + * Specifies what proxy to use when downloading. Valid values are + * listed below. + * @param noProgressTimeoutSecs + * The number of seconds for the "no progress" timeout. After there has + * been no download progress for this long, BITS will not retry the job + * following a transient error, producing instead a permanent error. + * @param monitorIntervalMs + * The number of milliseconds between download status notifications. + * @param observer + * An observer to be notified of various events. OnStartRequest is + * called once the BITS job has been created. OnStopRequest is called + * when the file transfer has completed or when an error occurs. If + * this object implements nsIProgressEventSink, then its OnProgress + * method will be called as data is transferred. + * IMPORTANT NOTE: When OnStopRequest is called, the download has + * completed, but nsIBitsRequest::complete() still + * needs to be called to save the file to the + * filesystem. + * @param context + * User defined object forwarded to the observer's onProgress method. + * This parameter, unlike others for this interface, can be passed a + * null pointer. + * @param callback + * The callback used to relay the response from BITS. + */ + void startDownload(in AUTF8String downloadURL, + in AUTF8String saveRelativePath, + in nsProxyUsage proxy, + in unsigned long noProgressTimeoutSecs, + in unsigned long monitorIntervalMs, + in nsIRequestObserver observer, + in nsISupports context, + in nsIBitsNewRequestCallback callback); + + // nsProxyUsage values + const long PROXY_NONE = 1; + const long PROXY_PRECONFIG = 2; + const long PROXY_AUTODETECT = 3; + + /** + * Similar to startDownload, but connects to a BITS transfer that has already + * been started. + * + * @param id + * The GUID of the download to monitor. + * @param monitorIntervalMs + * The number of milliseconds between download status notifications. + * @param observer + * An observer to be notified of various events. OnStartRequest is + * called once the BITS job has been created. OnStopRequest is called + * when the file transfer has completed or when an error occurs. If + * this object implements nsIProgressEventSink, then its OnProgress + * method will be called as data is transferred. + * IMPORTANT NOTE: When OnStopRequest is called, the download has + * completed, but nsIBitsRequest::complete() still + * needs to be called to save the file to the + * filesystem. + * @param context + * User defined object forwarded to the observer's onProgress method. + * This parameter, unlike others for this interface, can be passed a + * null pointer. + * @param callback + * The callback used to relay the response from BITS. + */ + void monitorDownload(in AUTF8String id, + in unsigned long monitorIntervalMs, + in nsIRequestObserver observer, + in nsISupports context, + in nsIBitsNewRequestCallback callback); +}; + +/** + * This callback interface is for use by the nsIBits interface for returning + * results asynchronously to the caller. + */ +[scriptable, uuid(aa12e433-5b9f-452d-b5c9-840a9541328b)] +interface nsIBitsNewRequestCallback : nsISupports +{ + void success(in nsIBitsRequest request); + void failure(in nsBitsErrorType errorType, + in nsBitsErrorAction errorAction, + in nsBitsErrorStage errorStage); + void failureNsresult(in nsBitsErrorType errorType, + in nsBitsErrorAction errorAction, + in nsBitsErrorStage errorStage, + in nsresult errorCode); + void failureHresult(in nsBitsErrorType errorType, + in nsBitsErrorAction errorAction, + in nsBitsErrorStage errorStage, + in long errorCode); + void failureString(in nsBitsErrorType errorType, + in nsBitsErrorAction errorAction, + in nsBitsErrorStage errorStage, + in AUTF8String errorMessage); +}; + +/* + * An interface for managing a running BITS download. + * + * It would be preferable for the functions in this interface to return + * Promises, but this interface is implemented in Rust, which does not yet have + * support for Promises. There is a JS wrapper around this class that should be + * preferred over using this interface directly, located in Bits.sys.mjs. + * + * Methods of this class that take a nsIBitsCallback do not return or throw + * errors. All errors will be reported through the callback. The only + * things that should cause methods to directly throw errors are null arguments. + * + * Note: Although the nsIBits interface derives from nsIRequest, implementations + * may not implement the loadGroup or loadFlags attributes. + * + * Note: Once the file transfer has stopped (due to completion or error), + * calling any method besides complete() or cancel() will result in an + * error with type nsIBits::ERROR_TYPE_TRANSFER_ALREADY_COMPLETE. + * Calling complete() or cancel() again after either has already been + * called will also result in an ERROR_TYPE_TRANSFER_ALREADY_COMPLETE + * error. + * Attributes and nsIRequest::isPending() can still be accessed at any + * time. + */ +[scriptable, uuid(ab9da0e9-06bf-4e73-bb1b-c0f2ea9ecc3e)] +interface nsIBitsRequest : nsIRequest +{ + /** + * The BITS id of the download. This will be a string representing a UUID. + */ + readonly attribute AUTF8String bitsId; + + /** + * The transfer result of the download, meant to be accessed after the + * transfer has stopped (i.e. after the observer's onStopRequest method has + * been called). Will be nsIBits::ERROR_TYPE_SUCCESS if the transfer is + * successful (and before transfer completion). If the transfer failed, this + * will be a different nsBitsErrorType value indicating the cause of the + * failure. + */ + readonly attribute nsBitsErrorType transferError; + + /** + * Requests a change to the frequency that Firefox is receiving download + * status notifications. + * + * @param monitorIntervalMs + * The new number of milliseconds between download status + * notifications. + * @param callback + * The callback function used to relay success or failure. + */ + void changeMonitorInterval(in unsigned long monitorIntervalMs, + in nsIBitsCallback callback); + + /** + * Cancels the download. This function is named this way to avoid conflict + * with nsIRequest::cancel. + * + * @param status + * The reason for cancelling the request. This must be a failure code + * rather than a success code like NS_OK. + * @param callback + * The callback function used to relay success or failure. + */ + void cancelAsync(in nsresult status, + in nsIBitsCallback callback); + + /** + * Sets the priority of the BITS job to high (i.e. foreground download). + * + * @param callback + * The callback function used to relay success or failure. + */ + void setPriorityHigh(in nsIBitsCallback callback); + + /** + * Sets the priority of the BITS job to low (i.e. background download). + * + * @param callback + * The callback function used to relay success or failure. + */ + void setPriorityLow(in nsIBitsCallback callback); + + /** + * Sets the BITS "no progress" timeout for the job. + * + * @param timeoutSecs + * The new number of seconds for the timeout. After there has been + * no progress for this long, BITS will not retry the job following + * a transient error, producing instead a permanent error. + * @param callback + * The callback function used to relay success or failure. + */ + void setNoProgressTimeout(in unsigned long timeoutSecs, + in nsIBitsCallback callback); + + /* + * Completes the download, moving it out of the BITS system and onto the + * disk location specified when startDownload was called. + * + * @param callback + * The callback function used to relay success or failure. + */ + void complete(in nsIBitsCallback callback); + + /* + * Suspends the download, preventing more data from being transferred until + * the download is resumed. This function is named this way to avoid conflict + * with nsIRequest::suspend. + * + * @param callback + * The callback function used to relay success or failure. + */ + void suspendAsync(in nsIBitsCallback callback); + + /* + * Resumes a previously suspended download. This function is named this way + * to avoid conflict with nsIRequest::resume. + * + * @param callback + * The callback function used to relay success or failure. + */ + void resumeAsync(in nsIBitsCallback callback); +}; + +/** + * This callback interface is for use by the nsIBitsRequest interface for + * returning results asynchronously to the caller. + */ +[scriptable, uuid(ea657e66-6bad-4e41-84d9-c6d107e9799d)] +interface nsIBitsCallback : nsISupports +{ + void success(); + void failure(in nsBitsErrorType errorType, + in nsBitsErrorAction errorAction, + in nsBitsErrorStage errorStage); + void failureNsresult(in nsBitsErrorType errorType, + in nsBitsErrorAction errorAction, + in nsBitsErrorStage errorStage, + in nsresult errorCode); + void failureHresult(in nsBitsErrorType errorType, + in nsBitsErrorAction errorAction, + in nsBitsErrorStage errorStage, + in long errorCode); + void failureString(in nsBitsErrorType errorType, + in nsBitsErrorAction errorAction, + in nsBitsErrorStage errorStage, + in AUTF8String errorMessage); +}; + +%{C++ +#define NS_BITS_CID \ + { 0xa334de05, 0xb9de, 0x46a1, \ + { 0x98, 0xa9, 0x3f, 0x5c, 0xed, 0x82, 0x1e, 0x68 } } +#define NS_BITS_CONTRACTID "@mozilla.org/bits;1" +%} |