diff options
Diffstat (limited to 'netwerk/base/nsIBackgroundFileSaver.idl')
| -rw-r--r-- | netwerk/base/nsIBackgroundFileSaver.idl | 182 |
1 files changed, 182 insertions, 0 deletions
diff --git a/netwerk/base/nsIBackgroundFileSaver.idl b/netwerk/base/nsIBackgroundFileSaver.idl new file mode 100644 index 000000000..df560d02f --- /dev/null +++ b/netwerk/base/nsIBackgroundFileSaver.idl @@ -0,0 +1,182 @@ +/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ +/* vim: set ts=2 et sw=2 tw=80: */ +/* 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 "nsISupports.idl" + +interface nsIArray; +interface nsIBackgroundFileSaverObserver; +interface nsIFile; + +/** + * Allows saving data to a file, while handling all the input/output on a + * background thread, including the initial file name assignment and any + * subsequent renaming of the target file. + * + * This interface is designed for file downloads. Generally, they start in the + * temporary directory, while the user is selecting the final name. Then, they + * are moved to the chosen target directory with a ".part" extension appended to + * the file name. Finally, they are renamed when the download is completed. + * + * Components implementing both nsIBackgroundFileSaver and nsIStreamListener + * allow data to be fed using an implementation of OnDataAvailable that never + * blocks the calling thread. They suspend the request that drives the stream + * listener in case too much data is being fed, and resume it when the data has + * been written. Calling OnStopRequest does not necessarily close the target + * file, and the Finish method must be called to complete the operation. + * + * Components implementing both nsIBackgroundFileSaver and nsIAsyncOutputStream + * allow data to be fed directly to the non-blocking output stream, that however + * may return NS_BASE_STREAM_WOULD_BLOCK in case too much data is being fed. + * Closing the output stream does not necessarily close the target file, and the + * Finish method must be called to complete the operation. + * + * @remarks Implementations may require the consumer to always call Finish. If + * the object reference is released without calling Finish, a memory + * leak may occur, and the target file might be kept locked. All + * public methods of the interface may only be called from the main + * thread. + */ +[scriptable, uuid(c43544a4-682c-4262-b407-2453d26e660d)] +interface nsIBackgroundFileSaver : nsISupports +{ + /** + * This observer receives notifications when the target file name changes and + * when the operation completes, successfully or not. + * + * @remarks A strong reference to the observer is held. Notification events + * are dispatched to the thread that created the object that + * implements nsIBackgroundFileSaver. + */ + attribute nsIBackgroundFileSaverObserver observer; + + /** + * An nsIArray of nsIX509CertList, representing a chain of X.509 signatures on + * the downloaded file. Each list may belong to a different signer and contain + * certificates all the way up to the root. + * + * @throws NS_ERROR_NOT_AVAILABLE + * In case this is called before the onSaveComplete method has been + * called to notify success, or enableSignatureInfo has not been + * called. + */ + readonly attribute nsIArray signatureInfo; + + /** + * The SHA-256 hash, in raw bytes, associated with the data that was saved. + * + * In case the enableAppend method has been called, the hash computation + * includes the contents of the existing file, if any. + * + * @throws NS_ERROR_NOT_AVAILABLE + * In case the enableSha256 method has not been called, or before the + * onSaveComplete method has been called to notify success. + */ + readonly attribute ACString sha256Hash; + + /** + * Instructs the component to compute the signatureInfo of the target file, + * and make it available in the signatureInfo property. + * + * @remarks This must be set on the main thread before the first call to + * setTarget. + */ + void enableSignatureInfo(); + + /** + * Instructs the component to compute the SHA-256 hash of the target file, and + * make it available in the sha256Hash property. + * + * @remarks This must be set on the main thread before the first call to + * setTarget. + */ + void enableSha256(); + + /** + * Instructs the component to append data to the initial target file, that + * will be specified by the first call to the setTarget method, instead of + * overwriting the file. + * + * If the initial target file does not exist, this method has no effect. + * + * @remarks This must be set on the main thread before the first call to + * setTarget. + */ + void enableAppend(); + + /** + * Sets the name of the output file to be written. The target can be changed + * after data has already been fed, in which case the existing file will be + * moved to the new destination. + * + * In case the specified file already exists, and this method is called for + * the first time, the file may be either overwritten or appended to, based on + * whether the enableAppend method was called. Subsequent calls always + * overwrite the specified target file with the previously saved data. + * + * No file will be written until this function is called at least once. It's + * recommended not to feed any data until the output file is set. + * + * If an input/output error occurs with the specified file, the save operation + * fails. Failure is notified asynchronously through the observer. + * + * @param aTarget + * New output file to be written. + * @param aKeepPartial + * Indicates whether aFile should be kept as partially completed, + * rather than deleted, if the operation fails or is canceled. This is + * generally set for downloads that use temporary ".part" files. + */ + void setTarget(in nsIFile aTarget, in bool aKeepPartial); + + /** + * Terminates access to the output file, then notifies the observer with the + * specified status code. A failure code will force the operation to be + * canceled, in which case the output file will be deleted if requested. + * + * This forces the involved streams to be closed, thus no more data should be + * fed to the component after this method has been called. + * + * This is the last method that should be called on this object, and the + * target file name cannot be changed anymore after this method has been + * called. Conversely, before calling this method, the file can still be + * renamed even if all the data has been fed. + * + * @param aStatus + * Result code that determines whether the operation should succeed or + * be canceled, and is notified to the observer. If the operation + * fails meanwhile for other reasons, or the observer has been already + * notified of completion, this status code is ignored. + */ + void finish(in nsresult aStatus); +}; + +[scriptable, uuid(ee7058c3-6e54-4411-b76b-3ce87b76fcb6)] +interface nsIBackgroundFileSaverObserver : nsISupports +{ + /** + * Called when the name of the output file has been determined. This function + * may be called more than once if the target file is renamed while saving. + * + * @param aSaver + * Reference to the object that raised the notification. + * @param aTarget + * Name of the file that is being written. + */ + void onTargetChange(in nsIBackgroundFileSaver aSaver, in nsIFile aTarget); + + /** + * Called when the operation completed, and the target file has been closed. + * If the operation succeeded, the target file is ready to be used, otherwise + * it might have been already deleted. + * + * @param aSaver + * Reference to the object that raised the notification. + * @param aStatus + * Result code that determines whether the operation succeeded or + * failed, as well as the failure reason. + */ + void onSaveComplete(in nsIBackgroundFileSaver aSaver, in nsresult aStatus); +}; |