The Tor Browser / file comparison

comparison: modules/libjar/zipwriter/public/nsIZipWriter.idl

modules/libjar/zipwriter/public/nsIZipWriter.idl

branch
TOR_BUG_3246
changeset 7
129ffea94266
equal deleted inserted replaced
-1:000000000000 0:b997f3db379b
1 /* This Source Code Form is subject to the terms of the Mozilla Public
2 * License, v. 2.0. If a copy of the MPL was not distributed with this
3 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
4 */
5
6 #include "nsISupports.idl"
7 interface nsIChannel;
8 interface nsIInputStream;
9 interface nsIRequestObserver;
10 interface nsIFile;
11 interface nsIZipEntry;
12
13 /**
14 * nsIZipWriter
15 *
16 * An interface for a zip archiver that can be used from script.
17 *
18 * The interface supports both a synchronous method of archiving data and a
19 * queueing system to allow operations to be prepared then run in sequence
20 * with notification after completion.
21 *
22 * Operations added to the queue do not get performed until performQueue is
23 * called at which point they will be performed in the order that they were
24 * added to the queue.
25 *
26 * Operations performed on the queue will throw any errors out to the
27 * observer.
28 *
29 * An attempt to perform a synchronous operation while the background queue
30 * is in progress will throw NS_ERROR_IN_PROGRESS.
31 *
32 * Entry names should use /'s as path separators and should not start with
33 * a /.
34 *
35 * It is not generally necessary to add directory entries in order to add file
36 * entries within them, however it is possible that some zip programs may
37 * experience problems what that.
38 */
39 [scriptable, uuid(3ca10750-797e-4a22-bcfe-66170b5e96dd)]
40 interface nsIZipWriter : nsISupports
41 {
42 /**
43 * Some predefined compression levels
44 */
45 const uint32_t COMPRESSION_NONE = 0;
46 const uint32_t COMPRESSION_FASTEST = 1;
47 const uint32_t COMPRESSION_DEFAULT = 6;
48 const uint32_t COMPRESSION_BEST = 9;
49
50 /**
51 * Gets or sets the comment associated with the open zip file.
52 *
53 * @throws NS_ERROR_NOT_INITIALIZED if no zip file has been opened
54 */
55 attribute ACString comment;
56
57 /**
58 * Indicates that operations on the background queue are being performed.
59 */
60 readonly attribute boolean inQueue;
61
62 /**
63 * The file that the zipwriter is writing to.
64 */
65 readonly attribute nsIFile file;
66
67 /**
68 * Opens a zip file.
69 *
70 * @param aFile the zip file to open
71 * @param aIoFlags the open flags for the zip file from prio.h
72 *
73 * @throws NS_ERROR_ALREADY_INITIALIZED if a zip file is already open
74 * @throws NS_ERROR_INVALID_ARG if aFile is null
75 * @throws NS_ERROR_FILE_NOT_FOUND if aFile does not exist and flags did
76 * not allow for creation
77 * @throws NS_ERROR_FILE_CORRUPTED if the file does not contain zip markers
78 * @throws <other-error> on failure to open zip file (most likely corrupt
79 * or unsupported form)
80 */
81 void open(in nsIFile aFile, in int32_t aIoFlags);
82
83 /**
84 * Returns a nsIZipEntry describing a specified zip entry or null if there
85 * is no such entry in the zip file
86 *
87 * @param aZipEntry the path of the entry
88 */
89 nsIZipEntry getEntry(in AUTF8String aZipEntry);
90
91 /**
92 * Checks whether the zipfile contains an entry specified by zipEntry.
93 *
94 * @param aZipEntry the path of the entry
95 */
96 boolean hasEntry(in AUTF8String aZipEntry);
97
98 /**
99 * Adds a new directory entry to the zip file. If aZipEntry does not end with
100 * "/" then it will be added.
101 *
102 * @param aZipEntry the path of the directory entry
103 * @param aModTime the modification time of the entry in microseconds
104 * @param aQueue adds the operation to the background queue. Will be
105 * performed when processQueue is called.
106 *
107 * @throws NS_ERROR_NOT_INITIALIZED if no zip file has been opened
108 * @throws NS_ERROR_FILE_ALREADY_EXISTS if the path already exists in the
109 * file
110 * @throws NS_ERROR_IN_PROGRESS if another operation is currently in progress
111 */
112 void addEntryDirectory(in AUTF8String aZipEntry, in PRTime aModTime,
113 in boolean aQueue);
114
115 /**
116 * Adds a new file or directory to the zip file. If the specified file is
117 * a directory then this will be equivalent to a call to
118 * addEntryDirectory(aZipEntry, aFile.lastModifiedTime, aQueue)
119 *
120 * @param aZipEntry the path of the file entry
121 * @param aCompression the compression level, 0 is no compression, 9 is best
122 * @param aFile the file to get the data and modification time from
123 * @param aQueue adds the operation to the background queue. Will be
124 * performed when processQueue is called.
125 *
126 * @throws NS_ERROR_NOT_INITIALIZED if no zip file has been opened
127 * @throws NS_ERROR_FILE_ALREADY_EXISTS if the path already exists in the zip
128 * @throws NS_ERROR_IN_PROGRESS if another operation is currently in progress
129 * @throws NS_ERROR_FILE_NOT_FOUND if file does not exist
130 */
131 void addEntryFile(in AUTF8String aZipEntry,
132 in int32_t aCompression, in nsIFile aFile,
133 in boolean aQueue);
134
135 /**
136 * Adds data from a channel to the zip file. If the operation is performed
137 * on the queue then the channel will be opened asynchronously, otherwise
138 * the channel must support being opened synchronously.
139 *
140 * @param aZipEntry the path of the file entry
141 * @param aModTime the modification time of the entry in microseconds
142 * @param aCompression the compression level, 0 is no compression, 9 is best
143 * @param aChannel the channel to get the data from
144 * @param aQueue adds the operation to the background queue. Will be
145 * performed when processQueue is called.
146 *
147 * @throws NS_ERROR_NOT_INITIALIZED if no zip file has been opened
148 * @throws NS_ERROR_FILE_ALREADY_EXISTS if the path already exists in the zip
149 * @throws NS_ERROR_IN_PROGRESS if another operation is currently in progress
150 */
151 void addEntryChannel(in AUTF8String aZipEntry, in PRTime aModTime,
152 in int32_t aCompression, in nsIChannel aChannel,
153 in boolean aQueue);
154
155 /**
156 * Adds data from an input stream to the zip file.
157 *
158 * @param aZipEntry the path of the file entry
159 * @param aModTime the modification time of the entry in microseconds
160 * @param aCompression the compression level, 0 is no compression, 9 is best
161 * @param aStream the input stream to get the data from
162 * @param aQueue adds the operation to the background queue. Will be
163 * performed when processQueue is called.
164 *
165 * @throws NS_ERROR_NOT_INITIALIZED if no zip file has been opened
166 * @throws NS_ERROR_FILE_ALREADY_EXISTS if the path already exists in the zip
167 * @throws NS_ERROR_IN_PROGRESS if another operation is currently in progress
168 */
169 void addEntryStream(in AUTF8String aZipEntry, in PRTime aModTime,
170 in int32_t aCompression, in nsIInputStream aStream,
171 in boolean aQueue);
172
173 /**
174 * Removes an existing entry from the zip file.
175 *
176 * @param aZipEntry the path of the entry to be removed
177 * @param aQueue adds the operation to the background queue. Will be
178 * performed when processQueue is called.
179 *
180 * @throws NS_ERROR_NOT_INITIALIZED if no zip file has been opened
181 * @throws NS_ERROR_IN_PROGRESS if another operation is currently in progress
182 * @throws NS_ERROR_FILE_NOT_FOUND if no entry with the given path exists
183 * @throws <other-error> on failure to update the zip file
184 */
185 void removeEntry(in AUTF8String aZipEntry, in boolean aQueue);
186
187 /**
188 * Processes all queued items until complete or some error occurs. The
189 * observer will be notified when the first operation starts and when the
190 * last operation completes. Any failures will be passed to the observer.
191 * The zip writer will be busy until the queue is complete or some error
192 * halted processing of the queue early. In the event of an early failure,
193 * remaining items will stay in the queue and calling processQueue will
194 * continue.
195 *
196 * @throws NS_ERROR_NOT_INITIALIZED if no zip file has been opened
197 * @throws NS_ERROR_IN_PROGRESS if the queue is already in progress
198 */
199 void processQueue(in nsIRequestObserver aObserver, in nsISupports aContext);
200
201 /**
202 * Closes the zip file.
203 *
204 * @throws NS_ERROR_NOT_INITIALIZED if no zip file has been opened
205 * @throws NS_ERROR_IN_PROGRESS if another operation is currently in progress
206 * @throws <other-error> on failure to complete the zip file
207 */
208 void close();
209
210 /**
211 * Make all stored(uncompressed) files align to given alignment size.
212 *
213 * @param aAlignSize is the alignment size, valid values from 2 to 32768, and
214 must be power of 2.
215 *
216 * @throws NS_ERROR_INVALID_ARG if aAlignSize is invalid
217 * @throws <other-error> on failure to update the zip file
218 */
219 void alignStoredFiles(in uint16_t aAlignSize);
220 };

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial