]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/zipstrm.h
put both versions of wxGetMousePosition in one place so they can use one implementation
[wxWidgets.git] / interface / wx / zipstrm.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: zipstrm.h
3 // Purpose: interface of wxZipNotifier
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows licence
7 /////////////////////////////////////////////////////////////////////////////
8
9
10
11 /// Compression Method, only 0 (store) and 8 (deflate) are supported here
12 enum wxZipMethod
13 {
14 wxZIP_METHOD_STORE,
15 wxZIP_METHOD_SHRINK,
16 wxZIP_METHOD_REDUCE1,
17 wxZIP_METHOD_REDUCE2,
18 wxZIP_METHOD_REDUCE3,
19 wxZIP_METHOD_REDUCE4,
20 wxZIP_METHOD_IMPLODE,
21 wxZIP_METHOD_TOKENIZE,
22 wxZIP_METHOD_DEFLATE,
23 wxZIP_METHOD_DEFLATE64,
24 wxZIP_METHOD_BZIP2 = 12,
25 wxZIP_METHOD_DEFAULT = 0xffff
26 };
27
28 /// Originating File-System.
29 ///
30 /// These are Pkware's values. Note that Info-zip disagree on some of them,
31 /// most notably NTFS.
32 enum wxZipSystem
33 {
34 wxZIP_SYSTEM_MSDOS,
35 wxZIP_SYSTEM_AMIGA,
36 wxZIP_SYSTEM_OPENVMS,
37 wxZIP_SYSTEM_UNIX,
38 wxZIP_SYSTEM_VM_CMS,
39 wxZIP_SYSTEM_ATARI_ST,
40 wxZIP_SYSTEM_OS2_HPFS,
41 wxZIP_SYSTEM_MACINTOSH,
42 wxZIP_SYSTEM_Z_SYSTEM,
43 wxZIP_SYSTEM_CPM,
44 wxZIP_SYSTEM_WINDOWS_NTFS,
45 wxZIP_SYSTEM_MVS,
46 wxZIP_SYSTEM_VSE,
47 wxZIP_SYSTEM_ACORN_RISC,
48 wxZIP_SYSTEM_VFAT,
49 wxZIP_SYSTEM_ALTERNATE_MVS,
50 wxZIP_SYSTEM_BEOS,
51 wxZIP_SYSTEM_TANDEM,
52 wxZIP_SYSTEM_OS_400
53 };
54
55 /// Dos/Win file attributes
56 enum wxZipAttributes
57 {
58 wxZIP_A_RDONLY = 0x01,
59 wxZIP_A_HIDDEN = 0x02,
60 wxZIP_A_SYSTEM = 0x04,
61 wxZIP_A_SUBDIR = 0x10,
62 wxZIP_A_ARCH = 0x20,
63
64 wxZIP_A_MASK = 0x37
65 };
66
67 /// Values for the flags field in the zip headers
68 enum wxZipFlags
69 {
70 wxZIP_ENCRYPTED = 0x0001,
71 wxZIP_DEFLATE_NORMAL = 0x0000, // normal compression
72 wxZIP_DEFLATE_EXTRA = 0x0002, // extra compression
73 wxZIP_DEFLATE_FAST = 0x0004, // fast compression
74 wxZIP_DEFLATE_SUPERFAST = 0x0006, // superfast compression
75 wxZIP_DEFLATE_MASK = 0x0006,
76 wxZIP_SUMS_FOLLOW = 0x0008, // crc and sizes come after the data
77 wxZIP_ENHANCED = 0x0010,
78 wxZIP_PATCH = 0x0020,
79 wxZIP_STRONG_ENC = 0x0040,
80 wxZIP_UNUSED = 0x0F80,
81 wxZIP_RESERVED = 0xF000
82 };
83
84
85 /**
86 @class wxZipNotifier
87
88 If you need to know when a wxZipInputStream updates a wxZipEntry,
89 you can create a notifier by deriving from this abstract base class,
90 overriding wxZipNotifier::OnEntryUpdated().
91
92 An instance of your notifier class can then be assigned to wxZipEntry
93 objects, using wxZipEntry::SetNotifier().
94
95 Setting a notifier is not usually necessary. It is used to handle
96 certain cases when modifying an zip in a pipeline (i.e. between
97 non-seekable streams).
98 See @ref overview_archive_noseek.
99
100 @library{wxbase}
101 @category{archive,streams}
102
103 @see @ref overview_archive_noseek, wxZipEntry, wxZipInputStream, wxZipOutputStream
104 */
105 class wxZipNotifier
106 {
107 public:
108 /**
109 Override this to receive notifications when an wxZipEntry object changes.
110 */
111 virtual void OnEntryUpdated(wxZipEntry& entry) = 0;
112 };
113
114
115
116 /**
117 @class wxZipEntry
118
119 Holds the meta-data for an entry in a zip.
120
121 @section zipentry_avail Field availability
122
123 When reading a zip from a stream that is seekable, wxZipEntry::GetNextEntry()
124 returns a fully populated wxZipEntry object except for wxZipEntry::GetLocalExtra().
125 wxZipEntry::GetLocalExtra() becomes available when the entry is opened, either by
126 calling wxZipInputStream::OpenEntry() or by making an attempt to read the entry's data.
127
128 For zips on non-seekable streams, the following fields are always available
129 when wxZipEntry::GetNextEntry() returns:
130 - wxZipEntry::GetDateTime
131 - wxZipEntry::GetInternalFormat
132 - wxZipEntry::GetInternalName
133 - wxZipEntry::GetFlags
134 - wxZipEntry::GetLocalExtra
135 - wxZipEntry::GetMethod
136 - wxZipEntry::GetName
137 - wxZipEntry::GetOffset
138 - wxZipEntry::IsDir
139
140 The following fields are also usually available when GetNextEntry() returns,
141 however, if the zip was also written to a non-seekable stream the zipper is
142 permitted to store them after the entry's data. In that case they become
143 available when the entry's data has been read to Eof(), or CloseEntry()
144 has been called. (GetFlags() & wxZIP_SUMS_FOLLOW) != 0 indicates that
145 one or more of these come after the data:
146 - wxZipEntry::GetCompressedSize
147 - wxZipEntry::GetCrc
148 - wxZipEntry::GetSize
149
150 The following are stored at the end of the zip, and become available when the
151 end of the zip has been reached, i.e. after GetNextEntry() returns @NULL
152 and Eof() is true:
153 - wxZipEntry::GetComment
154 - wxZipEntry::GetExternalAttributes
155 - wxZipEntry::GetExtra
156 - wxZipEntry::GetMode
157 - wxZipEntry::GetSystemMadeBy
158 - wxZipEntry::IsReadOnly
159 - wxZipEntry::IsMadeByUnix
160 - wxZipEntry::IsText
161
162 @library{wxbase}
163 @category{archive,streams}
164
165 @see @ref overview_archive, wxZipInputStream, wxZipOutputStream, wxZipNotifier
166 */
167 class wxZipEntry : public wxArchiveEntry
168 {
169 public:
170 wxZipEntry(const wxString& name = wxEmptyString,
171 const wxDateTime& dt = Now(),
172 wxFileOffset size = wxInvalidOffset);
173
174 /**
175 Copy constructor.
176 */
177 wxZipEntry(const wxZipEntry& entry);
178
179 /**
180 Make a copy of this entry.
181 */
182 wxZipEntry* Clone() const;
183
184 //@{
185 /**
186 Gets and sets the short comment for this entry.
187 */
188 wxString GetComment() const;
189 void SetComment(const wxString& comment);
190 //@}
191
192 //@{
193 /**
194 The low 8 bits are always the DOS/Windows file attributes for this entry.
195 The values of these attributes are given in the enumeration ::wxZipAttributes.
196
197 The remaining bits can store platform specific permission bits or
198 attributes, and their meaning depends on the value of SetSystemMadeBy().
199 If IsMadeByUnix() is @true then the high 16 bits are unix mode bits.
200
201 The following other accessors access these bits:
202 - IsReadOnly() / SetIsReadOnly()
203 - IsDir() / SetIsDir()
204 - GetMode() / SetMode()
205 */
206 wxUint32 GetExternalAttributes() const;
207 void SetExternalAttributes(wxUint32 attr);
208 //@}
209
210 //@{
211 /**
212 The extra field from the entry's central directory record.
213
214 The extra field is used to store platform or application specific
215 data. See Pkware's document 'appnote.txt' for information on its format.
216 */
217 const char* GetExtra() const;
218 size_t GetExtraLen() const;
219 void SetExtra(const char* extra, size_t len);
220 //@}
221
222 //@{
223 /**
224 The extra field from the entry's local record.
225
226 The extra field is used to store platform or application specific
227 data. See Pkware's document 'appnote.txt' for information on its format.
228 */
229 const char* GetLocalExtra() const;
230 size_t GetLocalExtraLen() const;
231 void SetLocalExtra(const char* extra, size_t len);
232 //@}
233
234 //@{
235 /**
236 The compression method.
237 The enumeration ::wxZipMethod lists the possible values.
238
239 The default constructor sets this to @c wxZIP_METHOD_DEFAULT,
240 which allows wxZipOutputStream to choose the method when writing the entry.
241 */
242 int GetMethod() const;
243 void SetMethod(int method);
244 //@}
245
246 //@{
247 /**
248 If IsMadeByUnix() is true then returns the unix permission bits stored
249 in GetExternalAttributes(). Otherwise synthesises them from the DOS attributes.
250 */
251 int GetMode() const;
252
253 /**
254 Sets the DOS attributes in GetExternalAttributes() to be consistent with
255 the @a mode given.
256
257 If IsMadeByUnix() is @true then also stores @a mode in GetExternalAttributes().
258 Note that the default constructor sets GetSystemMadeBy() to
259 @c wxZIP_SYSTEM_MSDOS by default. So to be able to store unix
260 permissions when creating zips, call SetSystemMadeBy(wxZIP_SYSTEM_UNIX).
261 */
262 void SetMode(int mode);
263 //@}
264
265 //@{
266 /**
267 The originating file-system.
268
269 The default constructor sets this to @c wxZIP_SYSTEM_MSDOS.
270 Set it to @c wxZIP_SYSTEM_UNIX in order to be able to store unix
271 permissions using SetMode().
272 */
273 int GetSystemMadeBy() const;
274 void SetSystemMadeBy(int system);
275 //@}
276
277 /**
278 The compressed size of this entry in bytes.
279 */
280 wxFileOffset GetCompressedSize() const;
281
282 /**
283 CRC32 for this entry's data.
284 */
285 wxUint32 GetCrc() const;
286
287 /**
288 Returns a combination of the bits flags in the enumeration @c wxZipFlags.
289 */
290 int GetFlags() const;
291
292 //@{
293 /**
294 A static member that translates a filename into the internal format used
295 within the archive. If the third parameter is provided, the bool pointed
296 to is set to indicate whether the name looks like a directory name
297 (i.e. has a trailing path separator).
298
299 @see @ref overview_archive_byname
300 */
301 wxString GetInternalName(const wxString& name,
302 wxPathFormat format = wxPATH_NATIVE,
303 bool* pIsDir = NULL);
304 /**
305 Returns the entry's filename in the internal format used within the archive.
306 The name can include directory components, i.e. it can be a full path.
307
308 The names of directory entries are returned without any trailing path separator.
309 This gives a canonical name that can be used in comparisons.
310 */
311 wxString GetInternalName() const;
312 //@}
313
314 /**
315 Returns @true if GetSystemMadeBy() is a flavour of unix.
316 */
317 bool IsMadeByUnix() const;
318
319 //@{
320 /**
321 Indicates that this entry's data is text in an 8-bit encoding.
322 */
323 bool IsText() const;
324 void SetIsText(bool isText = true);
325 //@}
326
327 //@{
328 /**
329 Sets the notifier (see wxZipNotifier) for this entry.
330 Whenever the wxZipInputStream updates this entry, it will then invoke
331 the associated notifier's wxZipNotifier::OnEntryUpdated() method.
332
333 Setting a notifier is not usually necessary. It is used to handle
334 certain cases when modifying an zip in a pipeline (i.e. between
335 non-seekable streams).
336
337 @see @ref overview_archive_noseek, wxZipNotifier
338 */
339 void SetNotifier(wxZipNotifier& notifier);
340 void UnsetNotifier();
341 //@}
342
343 /**
344 Assignment operator.
345 */
346 wxZipEntry& operator=(const wxZipEntry& entry);
347 };
348
349
350 /**
351 @class wxZipInputStream
352
353 Input stream for reading zip files.
354
355 wxZipInputStream::GetNextEntry() returns a wxZipEntry object containing the
356 meta-data for the next entry in the zip (and gives away ownership).
357 Reading from the wxZipInputStream then returns the entry's data.
358 Eof() becomes @true after an attempt has been made to read past the end of
359 the entry's data.
360 When there are no more entries, GetNextEntry() returns @NULL and sets Eof().
361
362 Note that in general zip entries are not seekable, and
363 wxZipInputStream::SeekI() always returns ::wxInvalidOffset.
364
365 @library{wxbase}
366 @category{archive,streams}
367
368 @see @ref overview_archive, wxZipEntry, wxZipOutputStream
369 */
370 class wxZipInputStream : public wxArchiveInputStream
371 {
372 public:
373
374 //@{
375 /**
376 Constructor. In a Unicode build the second parameter @a conv is used to
377 translate the filename and comment fields into Unicode.
378 It has no effect on the stream's data.
379 If the parent stream is passed as a pointer then the new filter stream
380 takes ownership of it. If it is passed by reference then it does not.
381 */
382 wxZipInputStream(wxInputStream& stream,
383 wxMBConv& conv = wxConvLocal);
384 wxZipInputStream(wxInputStream* stream,
385 wxMBConv& conv = wxConvLocal);
386 //@}
387
388 /**
389 @deprecated
390 Compatibility constructor (requires WXWIN_COMPATIBILITY_2_6).
391 When this constructor is used, an emulation of seeking is
392 switched on for compatibility with previous versions. Note however,
393 that it is deprecated.
394 */
395 wxZipInputStream(const wxString& archive,
396 const wxString& file);
397
398 /**
399 Closes the current entry.
400 On a non-seekable stream reads to the end of the current entry first.
401 */
402 bool CloseEntry();
403
404 /**
405 Returns the zip comment.
406
407 This is stored at the end of the zip, therefore when reading a zip
408 from a non-seekable stream, it returns the empty string until the end
409 of the zip has been reached, i.e. when GetNextEntry() returns @NULL.
410 */
411 wxString GetComment();
412
413 /**
414 Closes the current entry if one is open, then reads the meta-data for
415 the next entry and returns it in a wxZipEntry object, giving away ownership.
416 The stream is then open and can be read.
417 */
418 wxZipEntry* GetNextEntry();
419
420 /**
421 For a zip on a seekable stream returns the total number of entries in
422 the zip. For zips on non-seekable streams returns the number of entries
423 returned so far by GetNextEntry().
424 */
425 int GetTotalEntries();
426
427 /**
428 Closes the current entry if one is open, then opens the entry specified
429 by the @a entry object.
430
431 @a entry should be from the same zip file, and the zip should
432 be on a seekable stream.
433
434 @see overview_archive_byname
435 */
436 bool OpenEntry(wxZipEntry& entry);
437 };
438
439
440
441 /**
442 @class wxZipClassFactory
443
444 Class factory for the zip archive format.
445 See the base class for details.
446
447 @library{wxbase}
448 @category{archive,streams}
449
450 @see @ref overview_archive,
451 @ref overview_archive_generic,
452 wxZipEntry, wxZipInputStream, wxZipOutputStream
453 */
454 class wxZipClassFactory : public wxArchiveClassFactory
455 {
456 public:
457
458 };
459
460
461
462 /**
463 @class wxZipOutputStream
464
465 Output stream for writing zip files.
466
467 wxZipOutputStream::PutNextEntry() is used to create a new entry in the
468 output zip, then the entry's data is written to the wxZipOutputStream.
469 Another call to wxZipOutputStream::PutNextEntry() closes the current
470 entry and begins the next.
471
472 @library{wxbase}
473 @category{archive,streams}
474
475 @see @ref overview_archive, wxZipEntry, wxZipInputStream
476 */
477 class wxZipOutputStream : public wxArchiveOutputStream
478 {
479 public:
480 //@{
481 /**
482 Constructor.
483
484 @a level is the compression level to use.
485 It can be a value between 0 and 9 or -1 to use the default value
486 which currently is equivalent to 6.
487
488 If the parent stream is passed as a pointer then the new filter stream
489 takes ownership of it. If it is passed by reference then it does not.
490 In a Unicode build the third parameter @a conv is used to translate
491 the filename and comment fields to an 8-bit encoding.
492 It has no effect on the stream's data.
493 */
494 wxZipOutputStream(wxOutputStream& stream, int level = -1,
495 wxMBConv& conv = wxConvLocal);
496 wxZipOutputStream(wxOutputStream* stream, int level = -1,
497 wxMBConv& conv = wxConvLocal);
498 //@}
499
500 /**
501 The destructor calls Close() to finish writing the zip if it has
502 not been called already.
503 */
504 virtual ~wxZipOutputStream();
505
506 /**
507 Finishes writing the zip, returning @true if successful.
508 Called by the destructor if not called explicitly.
509 */
510 bool Close();
511
512 /**
513 Close the current entry.
514 It is called implicitly whenever another new entry is created with CopyEntry()
515 or PutNextEntry(), or when the zip is closed.
516 */
517 bool CloseEntry();
518
519 /**
520 Transfers the zip comment from the wxZipInputStream
521 to this output stream.
522 */
523 bool CopyArchiveMetaData(wxZipInputStream& inputStream);
524
525 /**
526 Takes ownership of @a entry and uses it to create a new entry
527 in the zip. @a entry is then opened in @a inputStream and its contents
528 copied to this stream.
529
530 CopyEntry() is much more efficient than transferring the data using
531 Read() and Write() since it will copy them without decompressing and
532 recompressing them.
533
534 For zips on seekable streams, @a entry must be from the same zip file
535 as @a inputStream. For non-seekable streams, @a entry must also be the
536 last thing read from @a inputStream.
537 */
538 bool CopyEntry(wxZipEntry* entry, wxZipInputStream& inputStream);
539
540 //@{
541 /**
542 Set the compression level that will be used the next time an entry is
543 created.
544
545 It can be a value between 0 and 9 or -1 to use the default value
546 which currently is equivalent to 6.
547 */
548 int GetLevel() const;
549 void SetLevel(int level);
550 //@}
551
552 /**
553 Create a new directory entry (see wxArchiveEntry::IsDir) with the given
554 name and timestamp.
555
556 PutNextEntry() can also be used to create directory entries, by supplying
557 a name with a trailing path separator.
558 */
559 bool PutNextDirEntry(const wxString& name,
560 const wxDateTime& dt = wxDateTime::Now());
561
562 //@{
563 /**
564 Takes ownership of @a entry and uses it to create a new entry in the zip.
565 */
566 bool PutNextEntry(wxZipEntry* entry);
567
568 /**
569 Create a new entry with the given name, timestamp and size.
570 */
571 bool PutNextEntry(const wxString& name,
572 const wxDateTime& dt = wxDateTime::Now(),
573 wxFileOffset size = wxInvalidOffset);
574 //@}
575
576 /**
577 Sets a comment for the zip as a whole.
578 It is written at the end of the zip.
579 */
580 void SetComment(const wxString& comment);
581 };
582