netwerk/base/public/nsIBackgroundFileSaver.idl@b8a032363ba2
netwerk/base/public/nsIBackgroundFileSaver.idl
Thu, 22 Jan 2015 13:21:57 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Thu, 22 Jan 2015 13:21:57 +0100
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
- permissions
- -rw-r--r--
Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6
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/. */
7 #include "nsISupports.idl"
9 interface nsIArray;
10 interface nsIBackgroundFileSaverObserver;
11 interface nsIFile;
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;
55 /**
56 * An nsIArray of nsIX509CertList, representing a chain of X.509 signatures on
57 * the downloaded file. Each list may belong to a different signer and contain
58 * certificates all the way up to the root.
59 *
60 * @throws NS_ERROR_NOT_AVAILABLE
61 * In case this is called before the onSaveComplete method has been
62 * called to notify success, or enableSignatureInfo has not been
63 * called.
64 */
65 readonly attribute nsIArray signatureInfo;
67 /**
68 * The SHA-256 hash, in raw bytes, associated with the data that was saved.
69 *
70 * In case the enableAppend method has been called, the hash computation
71 * includes the contents of the existing file, if any.
72 *
73 * @throws NS_ERROR_NOT_AVAILABLE
74 * In case the enableSha256 method has not been called, or before the
75 * onSaveComplete method has been called to notify success.
76 */
77 readonly attribute ACString sha256Hash;
79 /**
80 * Instructs the component to compute the signatureInfo of the target file,
81 * and make it available in the signatureInfo property.
82 *
83 * @remarks This must be set on the main thread before the first call to
84 * setTarget.
85 */
86 void enableSignatureInfo();
88 /**
89 * Instructs the component to compute the SHA-256 hash of the target file, and
90 * make it available in the sha256Hash property.
91 *
92 * @remarks This must be set on the main thread before the first call to
93 * setTarget.
94 */
95 void enableSha256();
97 /**
98 * Instructs the component to append data to the initial target file, that
99 * will be specified by the first call to the setTarget method, instead of
100 * overwriting the file.
101 *
102 * If the initial target file does not exist, this method has no effect.
103 *
104 * @remarks This must be set on the main thread before the first call to
105 * setTarget.
106 */
107 void enableAppend();
109 /**
110 * Sets the name of the output file to be written. The target can be changed
111 * after data has already been fed, in which case the existing file will be
112 * moved to the new destination.
113 *
114 * In case the specified file already exists, and this method is called for
115 * the first time, the file may be either overwritten or appended to, based on
116 * whether the enableAppend method was called. Subsequent calls always
117 * overwrite the specified target file with the previously saved data.
118 *
119 * No file will be written until this function is called at least once. It's
120 * recommended not to feed any data until the output file is set.
121 *
122 * If an input/output error occurs with the specified file, the save operation
123 * fails. Failure is notified asynchronously through the observer.
124 *
125 * @param aTarget
126 * New output file to be written.
127 * @param aKeepPartial
128 * Indicates whether aFile should be kept as partially completed,
129 * rather than deleted, if the operation fails or is canceled. This is
130 * generally set for downloads that use temporary ".part" files.
131 */
132 void setTarget(in nsIFile aTarget, in bool aKeepPartial);
134 /**
135 * Terminates access to the output file, then notifies the observer with the
136 * specified status code. A failure code will force the operation to be
137 * canceled, in which case the output file will be deleted if requested.
138 *
139 * This forces the involved streams to be closed, thus no more data should be
140 * fed to the component after this method has been called.
141 *
142 * This is the last method that should be called on this object, and the
143 * target file name cannot be changed anymore after this method has been
144 * called. Conversely, before calling this method, the file can still be
145 * renamed even if all the data has been fed.
146 *
147 * @param aStatus
148 * Result code that determines whether the operation should succeed or
149 * be canceled, and is notified to the observer. If the operation
150 * fails meanwhile for other reasons, or the observer has been already
151 * notified of completion, this status code is ignored.
152 */
153 void finish(in nsresult aStatus);
154 };
156 [scriptable, uuid(ee7058c3-6e54-4411-b76b-3ce87b76fcb6)]
157 interface nsIBackgroundFileSaverObserver : nsISupports
158 {
159 /**
160 * Called when the name of the output file has been determined. This function
161 * may be called more than once if the target file is renamed while saving.
162 *
163 * @param aSaver
164 * Reference to the object that raised the notification.
165 * @param aTarget
166 * Name of the file that is being written.
167 */
168 void onTargetChange(in nsIBackgroundFileSaver aSaver, in nsIFile aTarget);
170 /**
171 * Called when the operation completed, and the target file has been closed.
172 * If the operation succeeded, the target file is ready to be used, otherwise
173 * it might have been already deleted.
174 *
175 * @param aSaver
176 * Reference to the object that raised the notification.
177 * @param aStatus
178 * Result code that determines whether the operation succeeded or
179 * failed, as well as the failure reason.
180 */
181 void onSaveComplete(in nsIBackgroundFileSaver aSaver, in nsresult aStatus);
182 };
