Source code

Revision control

Other Tools

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 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;
66
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;
78
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();
87
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();
96
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();
108
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);
133
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
};
155
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);
169
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
};