nsIBackgroundFileSaver.idl (7900B)
1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 2 /* vim: set ts=2 et sw=2 tw=80: */ 3 /* This Source Code Form is subject to the terms of the Mozilla Public 4 * License, v. 2.0. If a copy of the MPL was not distributed with this 5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 6 7 #include "nsISupports.idl" 8 9 interface nsIArray; 10 interface nsIBackgroundFileSaverObserver; 11 interface nsIFile; 12 13 /** 14 * Allows saving data to a file, while handling all the input/output on a 15 * background thread, including the initial file name assignment and any 16 * subsequent renaming of the target file. 17 * 18 * This interface is designed for file downloads. Generally, they start in the 19 * temporary directory, while the user is selecting the final name. Then, they 20 * are moved to the chosen target directory with a ".part" extension appended to 21 * the file name. Finally, they are renamed when the download is completed. 22 * 23 * Components implementing both nsIBackgroundFileSaver and nsIStreamListener 24 * allow data to be fed using an implementation of OnDataAvailable that never 25 * blocks the calling thread. They suspend the request that drives the stream 26 * listener in case too much data is being fed, and resume it when the data has 27 * been written. Calling OnStopRequest does not necessarily close the target 28 * file, and the Finish method must be called to complete the operation. 29 * 30 * Components implementing both nsIBackgroundFileSaver and nsIAsyncOutputStream 31 * allow data to be fed directly to the non-blocking output stream, that however 32 * may return NS_BASE_STREAM_WOULD_BLOCK in case too much data is being fed. 33 * Closing the output stream does not necessarily close the target file, and the 34 * Finish method must be called to complete the operation. 35 * 36 * @remarks Implementations may require the consumer to always call Finish. If 37 * the object reference is released without calling Finish, a memory 38 * leak may occur, and the target file might be kept locked. All 39 * public methods of the interface may only be called from the main 40 * thread. 41 */ 42 [scriptable, uuid(c43544a4-682c-4262-b407-2453d26e660d)] 43 interface nsIBackgroundFileSaver : nsISupports 44 { 45 /** 46 * This observer receives notifications when the target file name changes and 47 * when the operation completes, successfully or not. 48 * 49 * @remarks A strong reference to the observer is held. Notification events 50 * are dispatched to the thread that created the object that 51 * implements nsIBackgroundFileSaver. 52 */ 53 attribute nsIBackgroundFileSaverObserver observer; 54 55 /** 56 * An Array of Array of Array of bytes, representing a chain of 57 * X.509 certificates, the last of which signed the downloaded file. 58 * Each list may belong to a different signer and contain certificates 59 * all the way up to the root. 60 * 61 * @throws NS_ERROR_NOT_AVAILABLE 62 * In case this is called before the onSaveComplete method has been 63 * called to notify success, or enableSignatureInfo has not been 64 * called. 65 */ 66 readonly attribute Array<Array<Array<uint8_t> > > signatureInfo; 67 68 /** 69 * The SHA-256 hash, in raw bytes, associated with the data that was saved. 70 * 71 * In case the enableAppend method has been called, the hash computation 72 * includes the contents of the existing file, if any. 73 * 74 * @throws NS_ERROR_NOT_AVAILABLE 75 * In case the enableSha256 method has not been called, or before the 76 * onSaveComplete method has been called to notify success. 77 */ 78 readonly attribute ACString sha256Hash; 79 80 /** 81 * Instructs the component to compute the signatureInfo of the target file, 82 * and make it available in the signatureInfo property. 83 * 84 * @remarks This must be set on the main thread before the first call to 85 * setTarget. 86 */ 87 void enableSignatureInfo(); 88 89 /** 90 * Instructs the component to compute the SHA-256 hash of the target file, and 91 * make it available in the sha256Hash property. 92 * 93 * @remarks This must be set on the main thread before the first call to 94 * setTarget. 95 */ 96 void enableSha256(); 97 98 /** 99 * Instructs the component to append data to the initial target file, that 100 * will be specified by the first call to the setTarget method, instead of 101 * overwriting the file. 102 * 103 * If the initial target file does not exist, this method has no effect. 104 * 105 * @remarks This must be set on the main thread before the first call to 106 * setTarget. 107 */ 108 void enableAppend(); 109 110 /** 111 * Sets the name of the output file to be written. The target can be changed 112 * after data has already been fed, in which case the existing file will be 113 * moved to the new destination. 114 * 115 * In case the specified file already exists, and this method is called for 116 * the first time, the file may be either overwritten or appended to, based on 117 * whether the enableAppend method was called. Subsequent calls always 118 * overwrite the specified target file with the previously saved data. 119 * 120 * No file will be written until this function is called at least once. It's 121 * recommended not to feed any data until the output file is set. 122 * 123 * If an input/output error occurs with the specified file, the save operation 124 * fails. Failure is notified asynchronously through the observer. 125 * 126 * @param aTarget 127 * New output file to be written. 128 * @param aKeepPartial 129 * Indicates whether aFile should be kept as partially completed, 130 * rather than deleted, if the operation fails or is canceled. This is 131 * generally set for downloads that use temporary ".part" files. 132 */ 133 void setTarget(in nsIFile aTarget, in boolean aKeepPartial); 134 135 /** 136 * Terminates access to the output file, then notifies the observer with the 137 * specified status code. A failure code will force the operation to be 138 * canceled, in which case the output file will be deleted if requested. 139 * 140 * This forces the involved streams to be closed, thus no more data should be 141 * fed to the component after this method has been called. 142 * 143 * This is the last method that should be called on this object, and the 144 * target file name cannot be changed anymore after this method has been 145 * called. Conversely, before calling this method, the file can still be 146 * renamed even if all the data has been fed. 147 * 148 * @param aStatus 149 * Result code that determines whether the operation should succeed or 150 * be canceled, and is notified to the observer. If the operation 151 * fails meanwhile for other reasons, or the observer has been already 152 * notified of completion, this status code is ignored. 153 */ 154 void finish(in nsresult aStatus); 155 }; 156 157 [scriptable, uuid(ee7058c3-6e54-4411-b76b-3ce87b76fcb6)] 158 interface nsIBackgroundFileSaverObserver : nsISupports 159 { 160 /** 161 * Called when the name of the output file has been determined. This function 162 * may be called more than once if the target file is renamed while saving. 163 * 164 * @param aSaver 165 * Reference to the object that raised the notification. 166 * @param aTarget 167 * Name of the file that is being written. 168 */ 169 void onTargetChange(in nsIBackgroundFileSaver aSaver, in nsIFile aTarget); 170 171 /** 172 * Called when the operation completed, and the target file has been closed. 173 * If the operation succeeded, the target file is ready to be used, otherwise 174 * it might have been already deleted. 175 * 176 * @param aSaver 177 * Reference to the object that raised the notification. 178 * @param aStatus 179 * Result code that determines whether the operation succeeded or 180 * failed, as well as the failure reason. 181 */ 182 void onSaveComplete(in nsIBackgroundFileSaver aSaver, in nsresult aStatus); 183 };