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