]>
Commit | Line | Data |
---|---|---|
23324ae1 FM |
1 | ///////////////////////////////////////////////////////////////////////////// |
2 | // Name: zipstrm.h | |
e54c96f1 | 3 | // Purpose: interface of wxZipNotifier |
23324ae1 FM |
4 | // Author: wxWidgets team |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows license | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
9 | /** | |
10 | @class wxZipNotifier | |
7c913512 | 11 | |
23324ae1 FM |
12 | If you need to know when a wxZipInputStream |
13 | updates a wxZipEntry, | |
14 | you can create a notifier by deriving from this abstract base class, | |
15 | overriding wxZipNotifier::OnEntryUpdated. | |
16 | An instance of your notifier class can then be assigned to wxZipEntry | |
17 | objects, using wxZipEntry::SetNotifier. | |
7c913512 | 18 | |
23324ae1 FM |
19 | Setting a notifier is not usually necessary. It is used to handle |
20 | certain cases when modifying an zip in a pipeline (i.e. between | |
21 | non-seekable streams). | |
22 | See '@ref overview_wxarcnoseek "Archives on non-seekable streams"'. | |
7c913512 | 23 | |
23324ae1 FM |
24 | @library{wxbase} |
25 | @category{FIXME} | |
7c913512 | 26 | |
e54c96f1 | 27 | @see @ref overview_wxarcnoseek "Archives on non-seekable streams", wxZipEntry, |
23324ae1 FM |
28 | wxZipInputStream, wxZipOutputStream |
29 | */ | |
7c913512 | 30 | class wxZipNotifier |
23324ae1 FM |
31 | { |
32 | public: | |
33 | /** | |
34 | Override this to receive notifications when | |
35 | an wxZipEntry object changes. | |
36 | */ | |
37 | void OnEntryUpdated(wxZipEntry& entry); | |
38 | }; | |
39 | ||
40 | ||
e54c96f1 | 41 | |
23324ae1 FM |
42 | /** |
43 | @class wxZipEntry | |
7c913512 | 44 | |
23324ae1 | 45 | Holds the meta-data for an entry in a zip. |
7c913512 | 46 | |
23324ae1 FM |
47 | @library{wxbase} |
48 | @category{FIXME} | |
7c913512 | 49 | |
e54c96f1 | 50 | @see @ref overview_wxarc "Archive formats such as zip", wxZipInputStream, |
23324ae1 FM |
51 | wxZipOutputStream, wxZipNotifier |
52 | */ | |
53 | class wxZipEntry : public wxArchiveEntry | |
54 | { | |
55 | public: | |
56 | //@{ | |
57 | /** | |
58 | Copy constructor. | |
59 | */ | |
60 | wxZipEntry(const wxString& name = wxEmptyString); | |
7c913512 | 61 | wxZipEntry(const wxZipEntry& entry); |
23324ae1 FM |
62 | //@} |
63 | ||
64 | /** | |
65 | Make a copy of this entry. | |
66 | */ | |
328f5751 | 67 | wxZipEntry* Clone() const; |
23324ae1 FM |
68 | |
69 | //@{ | |
70 | /** | |
71 | A short comment for this entry. | |
72 | */ | |
73 | wxString GetComment(); | |
328f5751 | 74 | const void SetComment(const wxString& comment); |
23324ae1 FM |
75 | //@} |
76 | ||
77 | //@{ | |
78 | /** | |
79 | The low 8 bits are always the DOS/Windows file attributes for this entry. | |
80 | The values of these attributes are given in the | |
81 | enumeration @c wxZipAttributes. | |
23324ae1 FM |
82 | The remaining bits can store platform specific permission bits or |
83 | attributes, and their meaning depends on the value | |
84 | of @ref systemmadeby() SetSystemMadeBy. | |
85 | If IsMadeByUnix() is @true then the | |
86 | high 16 bits are unix mode bits. | |
23324ae1 | 87 | The following other accessors access these bits: |
23324ae1 | 88 | @ref wxArchiveEntry::isreadonly IsReadOnly/SetIsReadOnly |
3c4f71cc | 89 | |
23324ae1 | 90 | @ref wxArchiveEntry::isdir IsDir/SetIsDir |
3c4f71cc | 91 | |
23324ae1 FM |
92 | @ref mode() Get/SetMode |
93 | */ | |
94 | wxUint32 GetExternalAttributes(); | |
328f5751 | 95 | const void SetExternalAttributes(wxUint32 attr); |
23324ae1 FM |
96 | //@} |
97 | ||
98 | //@{ | |
99 | /** | |
100 | The extra field from the entry's central directory record. | |
23324ae1 FM |
101 | The extra field is used to store platform or application specific |
102 | data. See Pkware's document 'appnote.txt' for information on its format. | |
103 | */ | |
104 | const char* GetExtra(); | |
328f5751 FM |
105 | const size_t GetExtraLen(); |
106 | const void SetExtra(const char* extra, size_t len); | |
23324ae1 FM |
107 | //@} |
108 | ||
109 | //@{ | |
110 | /** | |
111 | The extra field from the entry's local record. | |
23324ae1 FM |
112 | The extra field is used to store platform or application specific |
113 | data. See Pkware's document 'appnote.txt' for information on its format. | |
114 | */ | |
115 | const char* GetLocalExtra(); | |
328f5751 FM |
116 | const size_t GetLocalExtraLen(); |
117 | const void SetLocalExtra(const char* extra, size_t len); | |
23324ae1 FM |
118 | //@} |
119 | ||
120 | //@{ | |
121 | /** | |
122 | The compression method. The enumeration @c wxZipMethod lists the | |
123 | possible values. | |
23324ae1 FM |
124 | The default constructor sets this to wxZIP_METHOD_DEFAULT, |
125 | which allows wxZipOutputStream to | |
126 | choose the method when writing the entry. | |
127 | */ | |
128 | int GetMethod(); | |
328f5751 | 129 | const void SetMethod(int method); |
23324ae1 FM |
130 | //@} |
131 | ||
132 | //@{ | |
133 | /** | |
134 | Sets the DOS attributes | |
135 | in @ref externalattributes() GetExternalAttributes | |
136 | to be consistent with the @c mode given. | |
23324ae1 FM |
137 | If IsMadeByUnix() is @true then also |
138 | stores @c mode in GetExternalAttributes(). | |
23324ae1 | 139 | Note that the default constructor |
7c913512 | 140 | sets @ref systemmadeby() GetSystemMadeBy to |
23324ae1 FM |
141 | wxZIP_SYSTEM_MSDOS by default. So to be able to store unix |
142 | permissions when creating zips, call SetSystemMadeBy(wxZIP_SYSTEM_UNIX). | |
143 | */ | |
144 | int GetMode(); | |
328f5751 | 145 | const void SetMode(int mode); |
23324ae1 FM |
146 | //@} |
147 | ||
148 | //@{ | |
149 | /** | |
150 | The originating file-system. The default constructor sets this to | |
151 | wxZIP_SYSTEM_MSDOS. Set it to wxZIP_SYSTEM_UNIX in order to be | |
152 | able to store unix permissions using @ref mode() SetMode. | |
153 | */ | |
154 | int GetSystemMadeBy(); | |
328f5751 | 155 | const void SetSystemMadeBy(int system); |
23324ae1 FM |
156 | //@} |
157 | ||
158 | /** | |
159 | The compressed size of this entry in bytes. | |
160 | */ | |
328f5751 | 161 | off_t GetCompressedSize() const; |
23324ae1 FM |
162 | |
163 | /** | |
164 | CRC32 for this entry's data. | |
165 | */ | |
328f5751 | 166 | wxUint32 GetCrc() const; |
23324ae1 FM |
167 | |
168 | /** | |
169 | Returns a combination of the bits flags in the enumeration @c wxZipFlags. | |
170 | */ | |
328f5751 | 171 | int GetFlags() const; |
23324ae1 FM |
172 | |
173 | //@{ | |
174 | /** | |
175 | A static member that translates a filename into the internal format used | |
176 | within the archive. If the third parameter is provided, the bool pointed | |
177 | to is set to indicate whether the name looks like a directory name | |
178 | (i.e. has a trailing path separator). | |
3c4f71cc | 179 | |
4cc4bfaf | 180 | @see @ref overview_wxarcbyname "Looking up an archive entry by name" |
23324ae1 FM |
181 | */ |
182 | wxString GetInternalName(); | |
328f5751 FM |
183 | const wxString GetInternalName(const wxString& name, |
184 | wxPathFormat format = wxPATH_NATIVE, | |
185 | bool* pIsDir = NULL); | |
23324ae1 FM |
186 | //@} |
187 | ||
188 | /** | |
189 | Returns @true if @ref systemmadeby() GetSystemMadeBy | |
190 | is a flavour of unix. | |
191 | */ | |
328f5751 | 192 | bool IsMadeByUnix() const; |
23324ae1 FM |
193 | |
194 | //@{ | |
195 | /** | |
196 | Indicates that this entry's data is text in an 8-bit encoding. | |
197 | */ | |
198 | bool IsText(); | |
328f5751 | 199 | const void SetIsText(bool isText = true); |
23324ae1 FM |
200 | //@} |
201 | ||
202 | //@{ | |
203 | /** | |
e54c96f1 | 204 | Sets the notifier() for this entry. |
23324ae1 FM |
205 | Whenever the wxZipInputStream updates |
206 | this entry, it will then invoke the associated | |
207 | notifier's wxZipNotifier::OnEntryUpdated | |
208 | method. | |
23324ae1 FM |
209 | Setting a notifier is not usually necessary. It is used to handle |
210 | certain cases when modifying an zip in a pipeline (i.e. between | |
211 | non-seekable streams). | |
3c4f71cc | 212 | |
4cc4bfaf | 213 | @see @ref overview_wxarcnoseek "Archives on non-seekable streams", wxZipNotifier |
23324ae1 FM |
214 | */ |
215 | void SetNotifier(wxZipNotifier& notifier); | |
7c913512 | 216 | void UnsetNotifier(); |
23324ae1 FM |
217 | //@} |
218 | ||
219 | /** | |
220 | Assignment operator. | |
221 | */ | |
222 | wxZipEntry& operator operator=(const wxZipEntry& entry); | |
223 | }; | |
224 | ||
225 | ||
e54c96f1 | 226 | |
23324ae1 FM |
227 | /** |
228 | @class wxZipInputStream | |
7c913512 | 229 | |
23324ae1 | 230 | Input stream for reading zip files. |
7c913512 | 231 | |
23324ae1 FM |
232 | wxZipInputStream::GetNextEntry returns an |
233 | wxZipEntry object containing the meta-data | |
234 | for the next entry in the zip (and gives away ownership). Reading from | |
235 | the wxZipInputStream then returns the entry's data. Eof() becomes @true | |
236 | after an attempt has been made to read past the end of the entry's data. | |
237 | When there are no more entries, GetNextEntry() returns @NULL and sets Eof(). | |
7c913512 | 238 | |
23324ae1 FM |
239 | Note that in general zip entries are not seekable, and |
240 | wxZipInputStream::SeekI() always returns wxInvalidOffset. | |
7c913512 | 241 | |
23324ae1 FM |
242 | @library{wxbase} |
243 | @category{streams} | |
7c913512 | 244 | |
e54c96f1 FM |
245 | @see @ref overview_wxarc "Archive formats such as zip", wxZipEntry, |
246 | wxZipOutputStream | |
23324ae1 FM |
247 | */ |
248 | class wxZipInputStream : public wxArchiveInputStream | |
249 | { | |
250 | public: | |
251 | //@{ | |
252 | /** | |
253 | Compatibility constructor (requires WXWIN_COMPATIBILITY_2_6). | |
23324ae1 FM |
254 | When this constructor is used, an emulation of seeking is |
255 | switched on for compatibility with previous versions. Note however, | |
256 | that it is deprecated. | |
257 | */ | |
258 | wxZipInputStream(wxInputStream& stream, | |
259 | wxMBConv& conv = wxConvLocal); | |
7c913512 FM |
260 | wxZipInputStream(wxInputStream* stream, |
261 | wxMBConv& conv = wxConvLocal); | |
262 | wxZipInputStream(const wxString& archive, | |
263 | const wxString& file); | |
23324ae1 FM |
264 | //@} |
265 | ||
266 | /** | |
267 | Closes the current entry. On a non-seekable stream reads to the end of | |
268 | the current entry first. | |
269 | */ | |
270 | bool CloseEntry(); | |
271 | ||
272 | /** | |
273 | Returns the zip comment. | |
23324ae1 FM |
274 | This is stored at the end of the zip, therefore when reading a zip |
275 | from a non-seekable stream, it returns the empty string until the | |
276 | end of the zip has been reached, i.e. when GetNextEntry() returns | |
277 | @NULL. | |
278 | */ | |
279 | wxString GetComment(); | |
280 | ||
281 | /** | |
282 | Closes the current entry if one is open, then reads the meta-data for | |
283 | the next entry and returns it in a wxZipEntry | |
284 | object, giving away ownership. The stream is then open and can be read. | |
285 | */ | |
286 | wxZipEntry* GetNextEntry(); | |
287 | ||
288 | /** | |
289 | For a zip on a seekable stream returns the total number of entries in | |
290 | the zip. For zips on non-seekable streams returns the number of entries | |
291 | returned so far by GetNextEntry(). | |
292 | */ | |
293 | int GetTotalEntries(); | |
294 | ||
295 | /** | |
296 | Closes the current entry if one is open, then opens the entry specified | |
4cc4bfaf FM |
297 | by the @a entry object. |
298 | @a entry should be from the same zip file, and the zip should | |
23324ae1 FM |
299 | be on a seekable stream. |
300 | */ | |
301 | bool OpenEntry(wxZipEntry& entry); | |
302 | }; | |
303 | ||
304 | ||
e54c96f1 | 305 | |
23324ae1 FM |
306 | /** |
307 | @class wxZipClassFactory | |
7c913512 | 308 | |
23324ae1 FM |
309 | Class factory for the zip archive format. See the base class |
310 | for details. | |
7c913512 | 311 | |
23324ae1 FM |
312 | @library{wxbase} |
313 | @category{FIXME} | |
7c913512 | 314 | |
e54c96f1 FM |
315 | @see @ref overview_wxarc "Archive formats such as zip", @ref |
316 | overview_wxarcgeneric "Generic archive programming", wxZipEntry, wxZipInputStream, wxZipOutputStream | |
23324ae1 FM |
317 | */ |
318 | class wxZipClassFactory : public wxArchiveClassFactory | |
319 | { | |
320 | public: | |
7c913512 | 321 | |
23324ae1 FM |
322 | }; |
323 | ||
324 | ||
e54c96f1 | 325 | |
23324ae1 FM |
326 | /** |
327 | @class wxZipOutputStream | |
7c913512 | 328 | |
23324ae1 | 329 | Output stream for writing zip files. |
7c913512 | 330 | |
23324ae1 FM |
331 | wxZipOutputStream::PutNextEntry is used to create |
332 | a new entry in the output zip, then the entry's data is written to the | |
333 | wxZipOutputStream. Another call to PutNextEntry() closes the current | |
334 | entry and begins the next. | |
7c913512 | 335 | |
23324ae1 FM |
336 | @library{wxbase} |
337 | @category{streams} | |
7c913512 | 338 | |
e54c96f1 FM |
339 | @see @ref overview_wxarc "Archive formats such as zip", wxZipEntry, |
340 | wxZipInputStream | |
23324ae1 FM |
341 | */ |
342 | class wxZipOutputStream : public wxArchiveOutputStream | |
343 | { | |
344 | public: | |
345 | //@{ | |
346 | /** | |
347 | Constructor. @c level is the compression level to use. | |
348 | It can be a value between 0 and 9 or -1 to use the default value | |
349 | which currently is equivalent to 6. | |
23324ae1 FM |
350 | If the parent stream is passed as a pointer then the new filter stream |
351 | takes ownership of it. If it is passed by reference then it does not. | |
23324ae1 FM |
352 | In a Unicode build the third parameter @c conv is used to translate |
353 | the filename and comment fields to an 8-bit encoding. It has no effect on the | |
354 | stream's data. | |
355 | */ | |
356 | wxZipOutputStream(wxOutputStream& stream, int level = -1, | |
357 | wxMBConv& conv = wxConvLocal); | |
7c913512 FM |
358 | wxZipOutputStream(wxOutputStream* stream, int level = -1, |
359 | wxMBConv& conv = wxConvLocal); | |
23324ae1 FM |
360 | //@} |
361 | ||
362 | /** | |
363 | The destructor calls Close() to finish | |
364 | writing the zip if it has not been called already. | |
365 | */ | |
366 | ~wxZipOutputStream(); | |
367 | ||
368 | /** | |
369 | Finishes writing the zip, returning @true if successful. | |
370 | Called by the destructor if not called explicitly. | |
371 | */ | |
372 | bool Close(); | |
373 | ||
374 | /** | |
375 | Close the current entry. It is called implicitly whenever another new | |
376 | entry is created with CopyEntry() | |
377 | or PutNextEntry(), or | |
378 | when the zip is closed. | |
379 | */ | |
380 | bool CloseEntry(); | |
381 | ||
382 | /** | |
383 | Transfers the zip comment from the wxZipInputStream | |
384 | to this output stream. | |
385 | */ | |
386 | bool CopyArchiveMetaData(wxZipInputStream& inputStream); | |
387 | ||
388 | /** | |
389 | Takes ownership of @c entry and uses it to create a new entry | |
390 | in the zip. @c entry is then opened in @c inputStream and its contents | |
391 | copied to this stream. | |
23324ae1 FM |
392 | CopyEntry() is much more efficient than transferring the data using |
393 | Read() and Write() since it will copy them without decompressing and | |
394 | recompressing them. | |
23324ae1 FM |
395 | For zips on seekable streams, @c entry must be from the same zip file |
396 | as @c stream. For non-seekable streams, @c entry must also be the | |
397 | last thing read from @c inputStream. | |
398 | */ | |
399 | bool CopyEntry(wxZipEntry* entry, wxZipInputStream& inputStream); | |
400 | ||
401 | //@{ | |
402 | /** | |
403 | Set the compression level that will be used the next time an entry is | |
404 | created. It can be a value between 0 and 9 or -1 to use the default value | |
405 | which currently is equivalent to 6. | |
406 | */ | |
407 | int GetLevel(); | |
328f5751 | 408 | const void SetLevel(int level); |
23324ae1 FM |
409 | //@} |
410 | ||
411 | /** | |
412 | ) | |
23324ae1 FM |
413 | Create a new directory entry |
414 | (see wxArchiveEntry::IsDir) | |
415 | with the given name and timestamp. | |
23324ae1 FM |
416 | PutNextEntry() can |
417 | also be used to create directory entries, by supplying a name with | |
418 | a trailing path separator. | |
419 | */ | |
420 | bool PutNextDirEntry(const wxString& name); | |
421 | ||
422 | //@{ | |
423 | /** | |
424 | , @b off_t@e size = wxInvalidOffset) | |
23324ae1 FM |
425 | Create a new entry with the given name, timestamp and size. |
426 | */ | |
427 | bool PutNextEntry(wxZipEntry* entry); | |
7c913512 | 428 | bool PutNextEntry(const wxString& name); |
23324ae1 FM |
429 | //@} |
430 | ||
431 | /** | |
432 | Sets a comment for the zip as a whole. It is written at the end of the | |
433 | zip. | |
434 | */ | |
435 | void SetComment(const wxString& comment); | |
436 | }; | |
e54c96f1 | 437 |