interface/wx/tarstrm.h

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