interface/wx/tarstrm.h

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