interface/wx/tarstrm.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        tarstrm.h
   3 // Purpose:     interface of wxTar* classes
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8
   9 /** wxTarEntry::GetTypeFlag() values */
  10 enum wxTarType
  11 {
  12     wxTAR_REGTYPE   = '0',      //!< regular file
  13     wxTAR_LNKTYPE   = '1',      //!< hard link
  14     wxTAR_SYMTYPE   = '2',      //!< symbolic link
  15     wxTAR_CHRTYPE   = '3',      //!< character special
  16     wxTAR_BLKTYPE   = '4',      //!< block special
  17     wxTAR_DIRTYPE   = '5',      //!< directory
  18     wxTAR_FIFOTYPE  = '6',      //!< named pipe
  19     wxTAR_CONTTYPE  = '7'       //!< contiguous file
  20 };
  21
  22 /** Archive Formats (use wxTAR_PAX, it's backward compatible) used by wxTarEntry */
  23 enum wxTarFormat
  24 {
  25     wxTAR_USTAR,                //!< POSIX.1-1990 tar format
  26     wxTAR_PAX                   //!< POSIX.1-2001 tar format
  27 };
  28
  29
  30 /**
  31     @class wxTarInputStream
  32
  33     Input stream for reading tar files.
  34
  35     wxTarInputStream::GetNextEntry() returns a wxTarEntry object containing the
  36     meta-data for the next entry in the tar (and gives away ownership).
  37     Reading from the wxTarInputStream then returns the entry's data.
  38     wxTarInputStream::Eof() becomes @true after an attempt has been made to read
  39     past the end of the entry's data.
  40
  41     When there are no more entries, wxTarInputStream::GetNextEntry() returns @NULL
  42     and sets wxTarInputStream::Eof().
  43
  44     Tar entries are seekable if the parent stream is seekable. In practice this
  45     usually means they are only seekable if the tar is stored as a local file and
  46     is not compressed.
  47
  48     @library{wxbase}
  49     @category{archive,streams}
  50
  51     @see @ref overview_archive_byname
  52 */
  53 class wxTarInputStream : public wxArchiveInputStream
  54 {
  55 public:
  56     //@{
  57     /**
  58         Constructor. In a Unicode build the second parameter @a conv is
  59         used to translate fields from the standard tar header into Unicode.
  60
  61         It has no effect on the stream's data. @a conv is only used for the standard
  62         tar headers, any pax extended headers are always UTF-8 encoded.
  63
  64         If the parent stream is passed as a pointer then the new filter stream
  65         takes ownership of it. If it is passed by reference then it does not.
  66     */
  67     wxTarInputStream(wxInputStream& stream,
  68                      wxMBConv& conv = wxConvLocal);
  69     wxTarInputStream(wxInputStream* stream,
  70                      wxMBConv& conv = wxConvLocal);
  71     //@}
  72
  73     /**
  74         Closes the current entry.
  75         On a non-seekable stream reads to the end of the current entry first.
  76     */
  77     bool CloseEntry();
  78
  79     /**
  80         Closes the current entry if one is open, then reads the meta-data for
  81         the next entry and returns it in a wxTarEntry object, giving away ownership.
  82         The stream is then open and can be read.
  83     */
  84     wxTarEntry* GetNextEntry();
  85
  86     /**
  87         Closes the current entry if one is open, then opens the entry specified
  88         by the @a entry object.
  89
  90         @a entry should be from the same tar file, and the tar should be on a
  91         seekable stream.
  92     */
  93     bool OpenEntry(wxTarEntry& entry);
  94 };
  95
  96
  97
  98 /**
  99     @class wxTarClassFactory
 100
 101     Class factory for the tar archive format.
 102     See the base class for details.
 103
 104     @library{wxbase}
 105     @category{archive,streams}
 106
 107     @see @ref overview_archive, @ref overview_archive_generic,
 108          wxTarEntry, wxTarInputStream, wxTarOutputStream
 109 */
 110 class wxTarClassFactory : public wxArchiveClassFactory
 111 {
 112 public:
 113
 114 };
 115
 116
 117
 118 /**
 119     @class wxTarOutputStream
 120
 121     Output stream for writing tar files.
 122
 123     wxTarOutputStream::PutNextEntry() is used to create a new entry in the output tar,
 124     then the entry's data is written to the wxTarOutputStream.
 125     Another call to wxTarOutputStream::PutNextEntry() closes the current entry
 126     and begins the next.
 127
 128     @library{wxbase}
 129     @category{streams}
 130
 131     @see @ref overview_archive, wxTarEntry, wxTarInputStream
 132 */
 133 class wxTarOutputStream : public wxArchiveOutputStream
 134 {
 135 public:
 136     //@{
 137     /**
 138         If the parent stream is passed as a pointer then the new filter stream
 139         takes ownership of it. If it is passed by reference then it does not.
 140
 141         In a Unicode build the third parameter @a conv is used to translate the
 142         headers fields into an 8-bit encoding. It has no effect on the stream's data.
 143
 144         When the @a format is @e wxTAR_PAX, pax extended headers are generated
 145         when any header field will not fit the standard tar header block or if it
 146         uses any non-ascii characters.
 147
 148         Extended headers are stored as extra 'files' within the tar, and will be
 149         extracted as such by any other tar program that does not understand them.
 150         The @a conv parameter only affect the standard tar headers, the extended
 151         headers are always UTF-8 encoded.
 152
 153         When the @a format is @e wxTAR_USTAR, no extended headers are generated,
 154         and instead a warning message is logged if any header field overflows.
 155     */
 156     wxTarOutputStream(wxOutputStream& stream,
 157                       wxTarFormat format = wxTAR_PAX,
 158                       wxMBConv& conv = wxConvLocal);
 159     wxTarOutputStream(wxOutputStream* stream,
 160                       wxTarFormat format = wxTAR_PAX,
 161                       wxMBConv& conv = wxConvLocal);
 162     //@}
 163
 164     /**
 165         The destructor calls Close() to finish writing the tar if it has
 166         not been called already.
 167     */
 168     virtual ~wxTarOutputStream();
 169
 170     /**
 171         Finishes writing the tar, returning @true if successful.
 172         Called by the destructor if not called explicitly.
 173     */
 174     bool Close();
 175
 176     /**
 177         Close the current entry.
 178
 179         It is called implicitly whenever another new entry is created with
 180         CopyEntry() or PutNextEntry(), or when the tar is closed.
 181     */
 182     bool CloseEntry();
 183
 184     /**
 185         See wxArchiveOutputStream::CopyArchiveMetaData().
 186         For the tar format this function does nothing.
 187     */
 188     bool CopyArchiveMetaData(wxTarInputStream& s);
 189
 190     /**
 191         Takes ownership of @a entry and uses it to create a new entry in the tar.
 192         @a entry is then opened in @a inputStream and its contents copied to this stream.
 193
 194         For some other archive formats CopyEntry() is much more efficient than
 195         transferring the data using Read() and Write() since it will copy them
 196         without decompressing and recompressing them.
 197         For tar however it makes no difference.
 198
 199         For tars on seekable streams, @a entry must be from the same tar file
 200         as @a inputStream. For non-seekable streams, @a entry must also be the
 201         last thing read from @a inputStream.
 202     */
 203     bool CopyEntry(wxTarEntry* entry, wxTarInputStream& inputStream);
 204
 205     //@{
 206     /**
 207         The tar is zero padded to round its size up to @e BlockingFactor * 512 bytes.
 208
 209         The blocking factor defaults to 10 for @e wxTAR_PAX and 20 for @e wxTAR_USTAR
 210         (see wxTarOutputStream()), as specified in the POSIX standards.
 211     */
 212     int GetBlockingFactor() const;
 213     void SetBlockingFactor(int factor);
 214     //@}
 215
 216     /**
 217         Create a new directory entry (see wxArchiveEntry::IsDir()) with the given
 218         name and timestamp.
 219
 220         PutNextEntry() can also be used to create directory entries, by supplying
 221         a name with a trailing path separator.
 222     */
 223     bool PutNextDirEntry(const wxString& name, const wxDateTime& dt = wxDateTime::Now());
 224
 225     /**
 226         Takes ownership of entry and uses it to create a new entry in the tar.
 227     */
 228     bool PutNextEntry(wxTarEntry* entry);
 229
 230     /**
 231         Create a new entry with the given name, timestamp and size.
 232     */
 233     bool PutNextEntry(const wxString& name, const wxDateTime& dt = wxDateTime::Now(),
 234                       wxFileOffset size = wxInvalidOffset);
 235 };
 236
 237
 238
 239 /**
 240     @class wxTarEntry
 241
 242     Holds the meta-data for an entry in a tar.
 243
 244     @section tarentry_fields Field availability
 245
 246     The tar format stores all the meta-data for an entry ahead of its data,
 247     therefore GetNextEntry() always returns a fully populated wxTarEntry object,
 248     both when reading from seekable and non-seekable streams.
 249
 250     @library{wxbase}
 251     @category{archive,streams}
 252
 253     @see @ref overview_archive, wxTarInputStream, wxTarOutputStream
 254 */
 255 class wxTarEntry : public wxArchiveEntry
 256 {
 257 public:
 258     /**
 259         Constructor.
 260
 261         The tar archive format stores the entry's size ahead of the entry's data.
 262         Therefore when creating an archive on a non-seekable stream it is necessary
 263         to supply the correct size when each entry is created.
 264     */
 265     wxTarEntry(const wxString& name = wxEmptyString,
 266                const wxDateTime& dt = wxDateTime::Now(),
 267                wxFileOffset size = wxInvalidOffset);
 268
 269     /**
 270         Copy constructor.
 271     */
 272     wxTarEntry(const wxTarEntry& entry);
 273
 274     //@{
 275     /**
 276         Gets/sets the entry's access time stamp.
 277         See also wxArchiveEntry::GetDateTime() and wxArchiveEntry::SetDateTime().
 278     */
 279     wxDateTime GetAccessTime() const;
 280     void SetAccessTime(const wxDateTime& dt);
 281     //@}
 282
 283     //@{
 284     /**
 285         The entry's creation time stamp.
 286         See also wxArchiveEntry::GetDateTime() and wxArchiveEntry::SetDateTime().
 287     */
 288     wxDateTime GetCreateTime() const;
 289     void SetCreateTime(const wxDateTime& dt);
 290     //@}
 291
 292     //@{
 293     /**
 294         OS specific IDs defining a device; these are only meaningful when
 295         wxTarEntry::GetTypeFlag() is @e wxTAR_CHRTYPE or @e wxTAR_BLKTYPE.
 296     */
 297     int GetDevMajor() const;
 298     int GetDevMinor() const;
 299     void SetDevMajor(int dev);
 300     void SetDevMinor(int dev);
 301     //@}
 302
 303     //@{
 304     /**
 305         The user ID and group ID that has permissions (see wxTarEntry::GetMode())
 306         over this entry.
 307
 308         These values aren't usually useful unless the file will only be
 309         restored to the same system it originated from.
 310         wxTarEntry::GetGroupName() and wxTarEntry::GetUserName() can be used instead.
 311     */
 312     int GetGroupId() const;
 313     int GetUserId() const;
 314     void SetGroupId(int id);
 315     void SetUserId(int id);
 316     //@}
 317
 318     //@{
 319     /**
 320         The names of the user and group that has permissions (see wxTarEntry::GetMode())
 321         over this entry. These are not present in very old tars.
 322     */
 323     wxString GetGroupName() const;
 324     wxString GetUserName() const;
 325     void SetGroupName(const wxString& group);
 326     void SetUserName(const wxString& user);
 327     //@}
 328
 329     //@{
 330     /**
 331         The filename of a previous entry in the tar that this entry is a link to.
 332         Only meaningful when wxTarEntry::GetTypeFlag() is set to @e wxTAR_LNKTYPE
 333         or @e wxTAR_SYMTYPE.
 334     */
 335     wxString GetLinkName() const;
 336     void SetLinkName(const wxString& link);
 337     //@}
 338
 339     //@{
 340     /**
 341         UNIX permission bits for this entry.
 342         Giving read, write and execute permissions to the file's user and group
 343         (see GetGroupName() and GetUserName()) and to others.
 344
 345         The integer is one or more ::wxPosixPermissions flags OR-combined.
 346     */
 347     int GetMode() const;
 348     void SetMode(int mode);
 349     //@}
 350
 351     //@{
 352     /**
 353         The size of the entry's data in bytes.
 354
 355         The tar archive format stores the entry's size ahead of the entry's data.
 356         Therefore when creating an archive on a non-seekable stream it is necessary to
 357         supply the correct size when each entry is created.
 358
 359         For seekable streams this is not necessary as wxTarOutputStream will attempt
 360         to seek back and fix the entry's header when the entry is closed, though it is
 361         still more efficient if the size is given beforehand.
 362     */
 363     void SetSize(wxFileOffset size);
 364     wxFileOffset GetSize() const;
 365     //@}
 366
 367     //@{
 368     /**
 369         Returns/Sets the type of the entry as a ::wxTarType value.
 370
 371         When creating archives use only one of ::wxTarType values.
 372         When reading archives, GetTypeFlag() may return a value which does not
 373         match any value of ::wxTarType; in this case the returned value should be
 374         treated as @e wxTAR_REGTYPE.
 375     */
 376     int GetTypeFlag() const;
 377     void SetTypeFlag(int type);
 378     //@}
 379
 380     /**
 381         Returns the entry's filename in the internal format used within the archive.
 382
 383         The name can include directory components, i.e. it can be a full path.
 384         The names of directory entries are returned without any trailing path separator.
 385         This gives a canonical name that can be used in comparisons.
 386     */
 387     wxString GetInternalName() const;
 388
 389     /**
 390         A static member that translates a filename into the internal format used
 391         within the archive.
 392
 393         If the third parameter is provided, the bool pointed to is set to indicate
 394         whether the name looks like a directory name (i.e. has a trailing path separator).
 395     */
 396     static wxString GetInternalName(const wxString& name,
 397                                     wxPathFormat format = wxPATH_NATIVE,
 398                                     bool* pIsDir = NULL);
 399
 400     /**
 401         Assignment operator.
 402     */
 403     wxTarEntry& operator operator=(const wxTarEntry& entry);
 404 };
 405