gecko/netwerk/base/public/nsIBackgroundFileSaver.idl

140 lines
6.0 KiB
Plaintext

/* -*- 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 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(17a2ff32-918f-11e2-8fc9-f9626188709b)]
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;
/**
* The SHA256 hash in raw bytes associated with the file that was downloaded.
*
* @remarks Reading this will throw NS_ERROR_NOT_AVAILABLE unless
* sha256enabled is true and onSaveComplete has been called.
*/
readonly attribute ACString sha256Hash;
/**
* Compute SHA256.
*
* @remarks This must be set on the main thread before the first call to
* setTarget.
*/
void enableSha256();
/**
* Sets the name of the output file to be written. The output file may
* already exist, in which case it will be overwritten. The target can be
* changed after data has already been fed, in which case the existing file
* will be moved to the new destination.
*
* 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 succeded or
* failed, as well as the failure reason.
*/
void onSaveComplete(in nsIBackgroundFileSaver aSaver, in nsresult aStatus);
};