gecko-dev/netwerk/base/nsIBackgroundFileSaver.idl

183 lines
7.7 KiB
Plaintext
Raw Normal View History

/* -*- 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);
};