interface/tarstrm.h

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