1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/netwerk/base/public/nsIBackgroundFileSaver.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,182 @@
1.4 +/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* vim: set ts=2 et sw=2 tw=80: */
1.6 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.7 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.8 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.9 +
1.10 +#include "nsISupports.idl"
1.11 +
1.12 +interface nsIArray;
1.13 +interface nsIBackgroundFileSaverObserver;
1.14 +interface nsIFile;
1.15 +
1.16 +/**
1.17 + * Allows saving data to a file, while handling all the input/output on a
1.18 + * background thread, including the initial file name assignment and any
1.19 + * subsequent renaming of the target file.
1.20 + *
1.21 + * This interface is designed for file downloads. Generally, they start in the
1.22 + * temporary directory, while the user is selecting the final name. Then, they
1.23 + * are moved to the chosen target directory with a ".part" extension appended to
1.24 + * the file name. Finally, they are renamed when the download is completed.
1.25 + *
1.26 + * Components implementing both nsIBackgroundFileSaver and nsIStreamListener
1.27 + * allow data to be fed using an implementation of OnDataAvailable that never
1.28 + * blocks the calling thread. They suspend the request that drives the stream
1.29 + * listener in case too much data is being fed, and resume it when the data has
1.30 + * been written. Calling OnStopRequest does not necessarily close the target
1.31 + * file, and the Finish method must be called to complete the operation.
1.32 + *
1.33 + * Components implementing both nsIBackgroundFileSaver and nsIAsyncOutputStream
1.34 + * allow data to be fed directly to the non-blocking output stream, that however
1.35 + * may return NS_BASE_STREAM_WOULD_BLOCK in case too much data is being fed.
1.36 + * Closing the output stream does not necessarily close the target file, and the
1.37 + * Finish method must be called to complete the operation.
1.38 + *
1.39 + * @remarks Implementations may require the consumer to always call Finish. If
1.40 + * the object reference is released without calling Finish, a memory
1.41 + * leak may occur, and the target file might be kept locked. All
1.42 + * public methods of the interface may only be called from the main
1.43 + * thread.
1.44 + */
1.45 +[scriptable, uuid(c43544a4-682c-4262-b407-2453d26e660d)]
1.46 +interface nsIBackgroundFileSaver : nsISupports
1.47 +{
1.48 + /**
1.49 + * This observer receives notifications when the target file name changes and
1.50 + * when the operation completes, successfully or not.
1.51 + *
1.52 + * @remarks A strong reference to the observer is held. Notification events
1.53 + * are dispatched to the thread that created the object that
1.54 + * implements nsIBackgroundFileSaver.
1.55 + */
1.56 + attribute nsIBackgroundFileSaverObserver observer;
1.57 +
1.58 + /**
1.59 + * An nsIArray of nsIX509CertList, representing a chain of X.509 signatures on
1.60 + * the downloaded file. Each list may belong to a different signer and contain
1.61 + * certificates all the way up to the root.
1.62 + *
1.63 + * @throws NS_ERROR_NOT_AVAILABLE
1.64 + * In case this is called before the onSaveComplete method has been
1.65 + * called to notify success, or enableSignatureInfo has not been
1.66 + * called.
1.67 + */
1.68 + readonly attribute nsIArray signatureInfo;
1.69 +
1.70 + /**
1.71 + * The SHA-256 hash, in raw bytes, associated with the data that was saved.
1.72 + *
1.73 + * In case the enableAppend method has been called, the hash computation
1.74 + * includes the contents of the existing file, if any.
1.75 + *
1.76 + * @throws NS_ERROR_NOT_AVAILABLE
1.77 + * In case the enableSha256 method has not been called, or before the
1.78 + * onSaveComplete method has been called to notify success.
1.79 + */
1.80 + readonly attribute ACString sha256Hash;
1.81 +
1.82 + /**
1.83 + * Instructs the component to compute the signatureInfo of the target file,
1.84 + * and make it available in the signatureInfo property.
1.85 + *
1.86 + * @remarks This must be set on the main thread before the first call to
1.87 + * setTarget.
1.88 + */
1.89 + void enableSignatureInfo();
1.90 +
1.91 + /**
1.92 + * Instructs the component to compute the SHA-256 hash of the target file, and
1.93 + * make it available in the sha256Hash property.
1.94 + *
1.95 + * @remarks This must be set on the main thread before the first call to
1.96 + * setTarget.
1.97 + */
1.98 + void enableSha256();
1.99 +
1.100 + /**
1.101 + * Instructs the component to append data to the initial target file, that
1.102 + * will be specified by the first call to the setTarget method, instead of
1.103 + * overwriting the file.
1.104 + *
1.105 + * If the initial target file does not exist, this method has no effect.
1.106 + *
1.107 + * @remarks This must be set on the main thread before the first call to
1.108 + * setTarget.
1.109 + */
1.110 + void enableAppend();
1.111 +
1.112 + /**
1.113 + * Sets the name of the output file to be written. The target can be changed
1.114 + * after data has already been fed, in which case the existing file will be
1.115 + * moved to the new destination.
1.116 + *
1.117 + * In case the specified file already exists, and this method is called for
1.118 + * the first time, the file may be either overwritten or appended to, based on
1.119 + * whether the enableAppend method was called. Subsequent calls always
1.120 + * overwrite the specified target file with the previously saved data.
1.121 + *
1.122 + * No file will be written until this function is called at least once. It's
1.123 + * recommended not to feed any data until the output file is set.
1.124 + *
1.125 + * If an input/output error occurs with the specified file, the save operation
1.126 + * fails. Failure is notified asynchronously through the observer.
1.127 + *
1.128 + * @param aTarget
1.129 + * New output file to be written.
1.130 + * @param aKeepPartial
1.131 + * Indicates whether aFile should be kept as partially completed,
1.132 + * rather than deleted, if the operation fails or is canceled. This is
1.133 + * generally set for downloads that use temporary ".part" files.
1.134 + */
1.135 + void setTarget(in nsIFile aTarget, in bool aKeepPartial);
1.136 +
1.137 + /**
1.138 + * Terminates access to the output file, then notifies the observer with the
1.139 + * specified status code. A failure code will force the operation to be
1.140 + * canceled, in which case the output file will be deleted if requested.
1.141 + *
1.142 + * This forces the involved streams to be closed, thus no more data should be
1.143 + * fed to the component after this method has been called.
1.144 + *
1.145 + * This is the last method that should be called on this object, and the
1.146 + * target file name cannot be changed anymore after this method has been
1.147 + * called. Conversely, before calling this method, the file can still be
1.148 + * renamed even if all the data has been fed.
1.149 + *
1.150 + * @param aStatus
1.151 + * Result code that determines whether the operation should succeed or
1.152 + * be canceled, and is notified to the observer. If the operation
1.153 + * fails meanwhile for other reasons, or the observer has been already
1.154 + * notified of completion, this status code is ignored.
1.155 + */
1.156 + void finish(in nsresult aStatus);
1.157 +};
1.158 +
1.159 +[scriptable, uuid(ee7058c3-6e54-4411-b76b-3ce87b76fcb6)]
1.160 +interface nsIBackgroundFileSaverObserver : nsISupports
1.161 +{
1.162 + /**
1.163 + * Called when the name of the output file has been determined. This function
1.164 + * may be called more than once if the target file is renamed while saving.
1.165 + *
1.166 + * @param aSaver
1.167 + * Reference to the object that raised the notification.
1.168 + * @param aTarget
1.169 + * Name of the file that is being written.
1.170 + */
1.171 + void onTargetChange(in nsIBackgroundFileSaver aSaver, in nsIFile aTarget);
1.172 +
1.173 + /**
1.174 + * Called when the operation completed, and the target file has been closed.
1.175 + * If the operation succeeded, the target file is ready to be used, otherwise
1.176 + * it might have been already deleted.
1.177 + *
1.178 + * @param aSaver
1.179 + * Reference to the object that raised the notification.
1.180 + * @param aStatus
1.181 + * Result code that determines whether the operation succeeded or
1.182 + * failed, as well as the failure reason.
1.183 + */
1.184 + void onSaveComplete(in nsIBackgroundFileSaver aSaver, in nsresult aStatus);
1.185 +};
