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