interface revisions of ta*h te*h headers; grouped wxTextAttr #defines into enums to make it easier to document them
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@56075 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
@@ -1,31 +1,55 @@
|
||||
/////////////////////////////////////////////////////////////////////////////
|
||||
// Name: tarstrm.h
|
||||
// Purpose: interface of wxTarInputStream
|
||||
// Purpose: interface of wxTar* classes
|
||||
// Author: wxWidgets team
|
||||
// RCS-ID: $Id$
|
||||
// Licence: wxWindows license
|
||||
/////////////////////////////////////////////////////////////////////////////
|
||||
|
||||
|
||||
/** wxTarEntry::GetTypeFlag() values */
|
||||
enum wxTarType
|
||||
{
|
||||
wxTAR_REGTYPE = '0', //!< regular file
|
||||
wxTAR_LNKTYPE = '1', //!< hard link
|
||||
wxTAR_SYMTYPE = '2', //!< symbolic link
|
||||
wxTAR_CHRTYPE = '3', //!< character special
|
||||
wxTAR_BLKTYPE = '4', //!< block special
|
||||
wxTAR_DIRTYPE = '5', //!< directory
|
||||
wxTAR_FIFOTYPE = '6', //!< named pipe
|
||||
wxTAR_CONTTYPE = '7' //!< contiguous file
|
||||
};
|
||||
|
||||
/** Archive Formats (use wxTAR_PAX, it's backward compatible) used by wxTarEntry */
|
||||
enum wxTarFormat
|
||||
{
|
||||
wxTAR_USTAR, //!< POSIX.1-1990 tar format
|
||||
wxTAR_PAX //!< POSIX.1-2001 tar format
|
||||
};
|
||||
|
||||
|
||||
/**
|
||||
@class wxTarInputStream
|
||||
|
||||
Input stream for reading tar files.
|
||||
|
||||
wxTarInputStream::GetNextEntry returns an
|
||||
wxTarEntry object containing the meta-data
|
||||
for the next entry in the tar (and gives away ownership). Reading from
|
||||
the wxTarInputStream then returns the entry's data. Eof() becomes @true
|
||||
after an attempt has been made to read past the end of the entry's data.
|
||||
When there are no more entries, GetNextEntry() returns @NULL and sets Eof().
|
||||
wxTarInputStream::GetNextEntry() returns a wxTarEntry object containing the
|
||||
meta-data for the next entry in the tar (and gives away ownership).
|
||||
Reading from the wxTarInputStream then returns the entry's data.
|
||||
wxTarInputStream::Eof() becomes @true after an attempt has been made to read
|
||||
past the end of the entry's data.
|
||||
|
||||
When there are no more entries, wxTarInputStream::GetNextEntry() returns @NULL
|
||||
and sets wxTarInputStream::Eof().
|
||||
|
||||
Tar entries are seekable if the parent stream is seekable. In practice this
|
||||
usually means they are only seekable if the tar is stored as a local file and
|
||||
is not compressed.
|
||||
|
||||
@library{wxbase}
|
||||
@category{streams}
|
||||
@category{archive,streams}
|
||||
|
||||
@see @ref overview_wxarcbyname "Looking up an archive entry by name"
|
||||
@see @ref overview_archive_byname
|
||||
*/
|
||||
class wxTarInputStream : public wxArchiveInputStream
|
||||
{
|
||||
@@ -33,9 +57,11 @@ public:
|
||||
//@{
|
||||
/**
|
||||
Constructor. In a Unicode build the second parameter @a conv is
|
||||
used to translate fields from the standard tar header into Unicode. It has
|
||||
no effect on the stream's data. @a conv is only used for the standard
|
||||
used to translate fields from the standard tar header into Unicode.
|
||||
|
||||
It has no effect on the stream's data. @a conv is only used for the standard
|
||||
tar headers, any pax extended headers are always UTF-8 encoded.
|
||||
|
||||
If the parent stream is passed as a pointer then the new filter stream
|
||||
takes ownership of it. If it is passed by reference then it does not.
|
||||
*/
|
||||
@@ -46,23 +72,24 @@ public:
|
||||
//@}
|
||||
|
||||
/**
|
||||
Closes the current entry. On a non-seekable stream reads to the end of
|
||||
the current entry first.
|
||||
Closes the current entry.
|
||||
On a non-seekable stream reads to the end of the current entry first.
|
||||
*/
|
||||
bool CloseEntry();
|
||||
|
||||
/**
|
||||
Closes the current entry if one is open, then reads the meta-data for
|
||||
the next entry and returns it in a wxTarEntry
|
||||
object, giving away ownership. The stream is then open and can be read.
|
||||
the next entry and returns it in a wxTarEntry object, giving away ownership.
|
||||
The stream is then open and can be read.
|
||||
*/
|
||||
wxTarEntry* GetNextEntry();
|
||||
|
||||
/**
|
||||
Closes the current entry if one is open, then opens the entry specified
|
||||
by the @a entry object.
|
||||
@a entry should be from the same tar file, and the tar should
|
||||
be on a seekable stream.
|
||||
|
||||
@a entry should be from the same tar file, and the tar should be on a
|
||||
seekable stream.
|
||||
*/
|
||||
bool OpenEntry(wxTarEntry& entry);
|
||||
};
|
||||
@@ -72,14 +99,14 @@ public:
|
||||
/**
|
||||
@class wxTarClassFactory
|
||||
|
||||
Class factory for the tar archive format. See the base class
|
||||
for details.
|
||||
Class factory for the tar archive format.
|
||||
See the base class for details.
|
||||
|
||||
@library{wxbase}
|
||||
@category{FIXME}
|
||||
@category{archive,streams}
|
||||
|
||||
@see @ref overview_wxarc "Archive formats such as zip", @ref
|
||||
overview_wxarcgeneric "Generic archive programming", wxTarEntry, wxTarInputStream, wxTarOutputStream
|
||||
@see @ref overview_archive, @ref overview_archive_generic,
|
||||
wxTarEntry, wxTarInputStream, wxTarOutputStream
|
||||
*/
|
||||
class wxTarClassFactory : public wxArchiveClassFactory
|
||||
{
|
||||
@@ -94,16 +121,15 @@ public:
|
||||
|
||||
Output stream for writing tar files.
|
||||
|
||||
wxTarOutputStream::PutNextEntry is used to create
|
||||
a new entry in the output tar, then the entry's data is written to the
|
||||
wxTarOutputStream. Another call to PutNextEntry() closes the current
|
||||
entry and begins the next.
|
||||
wxTarOutputStream::PutNextEntry() is used to create a new entry in the output tar,
|
||||
then the entry's data is written to the wxTarOutputStream.
|
||||
Another call to wxTarOutputStream::PutNextEntry() closes the current entry
|
||||
and begins the next.
|
||||
|
||||
@library{wxbase}
|
||||
@category{streams}
|
||||
|
||||
@see @ref overview_wxarc "Archive formats such as zip", wxTarEntry,
|
||||
wxTarInputStream
|
||||
@see @ref overview_archive, wxTarEntry, wxTarInputStream
|
||||
*/
|
||||
class wxTarOutputStream : public wxArchiveOutputStream
|
||||
{
|
||||
@@ -112,18 +138,21 @@ public:
|
||||
/**
|
||||
If the parent stream is passed as a pointer then the new filter stream
|
||||
takes ownership of it. If it is passed by reference then it does not.
|
||||
|
||||
In a Unicode build the third parameter @a conv is used to translate the
|
||||
headers fields into an 8-bit encoding. It has no effect on the stream's data.
|
||||
|
||||
When the @a format is @e wxTAR_PAX, pax extended headers are generated
|
||||
when any header field will not fit the standard tar header block or if it
|
||||
uses any non-ascii characters.
|
||||
|
||||
Extended headers are stored as extra 'files' within the tar, and will be
|
||||
extracted as such by any other tar program that does not understand them.
|
||||
The @a conv parameter only affect the standard tar headers, the extended
|
||||
headers are always UTF-8 encoded.
|
||||
When the @a format is @e wxTAR_USTAR, no extended headers are
|
||||
generated, and instead a warning message is logged if any header field
|
||||
overflows.
|
||||
|
||||
When the @a format is @e wxTAR_USTAR, no extended headers are generated,
|
||||
and instead a warning message is logged if any header field overflows.
|
||||
*/
|
||||
wxTarOutputStream(wxOutputStream& stream,
|
||||
wxTarFormat format = wxTAR_PAX,
|
||||
@@ -134,8 +163,8 @@ public:
|
||||
//@}
|
||||
|
||||
/**
|
||||
The destructor calls Close() to finish
|
||||
writing the tar if it has not been called already.
|
||||
The destructor calls Close() to finish writing the tar if it has
|
||||
not been called already.
|
||||
*/
|
||||
virtual ~wxTarOutputStream();
|
||||
|
||||
@@ -146,63 +175,64 @@ public:
|
||||
bool Close();
|
||||
|
||||
/**
|
||||
Close the current entry. It is called implicitly whenever another new
|
||||
entry is created with CopyEntry()
|
||||
or PutNextEntry(), or
|
||||
when the tar is closed.
|
||||
Close the current entry.
|
||||
|
||||
It is called implicitly whenever another new entry is created with
|
||||
CopyEntry() or PutNextEntry(), or when the tar is closed.
|
||||
*/
|
||||
bool CloseEntry();
|
||||
|
||||
/**
|
||||
See wxArchiveOutputStream::CopyArchiveMetaData.
|
||||
See wxArchiveOutputStream::CopyArchiveMetaData().
|
||||
For the tar format this function does nothing.
|
||||
*/
|
||||
bool CopyArchiveMetaData(wxTarInputStream& s);
|
||||
|
||||
/**
|
||||
Takes ownership of @a entry and uses it to create a new entry
|
||||
in the tar. @a entry is then opened in @a inputStream and its contents
|
||||
copied to this stream.
|
||||
Takes ownership of @a entry and uses it to create a new entry in the tar.
|
||||
@a entry is then opened in @a inputStream and its contents copied to this stream.
|
||||
|
||||
For some other archive formats CopyEntry() is much more efficient than
|
||||
transferring the data using Read() and Write() since it will copy them
|
||||
without decompressing and recompressing them. For tar however it makes
|
||||
no difference.
|
||||
without decompressing and recompressing them.
|
||||
For tar however it makes no difference.
|
||||
|
||||
For tars on seekable streams, @a entry must be from the same tar file
|
||||
as @e stream. For non-seekable streams, @a entry must also be the
|
||||
last thing read from @e inputStream.
|
||||
as @a inputStream. For non-seekable streams, @a entry must also be the
|
||||
last thing read from @a inputStream.
|
||||
*/
|
||||
bool CopyEntry(wxTarEntry* entry, wxTarInputStream& inputStream);
|
||||
|
||||
//@{
|
||||
/**
|
||||
The tar is zero padded to round its size up to @e BlockingFactor * 512 bytes.
|
||||
Defaults to 10 for @e wxTAR_PAX and 20 for @e wxTAR_USTAR
|
||||
(see the @ref wxtaroutputstream() constructor), as
|
||||
specified in the POSIX standards.
|
||||
|
||||
The blocking factor defaults to 10 for @e wxTAR_PAX and 20 for @e wxTAR_USTAR
|
||||
(see wxTarOutputStream()), as specified in the POSIX standards.
|
||||
*/
|
||||
int GetBlockingFactor();
|
||||
const void SetBlockingFactor(int factor);
|
||||
int GetBlockingFactor() const;
|
||||
void SetBlockingFactor(int factor);
|
||||
//@}
|
||||
|
||||
/**
|
||||
)
|
||||
Create a new directory entry
|
||||
(see wxArchiveEntry::IsDir)
|
||||
with the given name and timestamp.
|
||||
PutNextEntry() can
|
||||
also be used to create directory entries, by supplying a name with
|
||||
a trailing path separator.
|
||||
*/
|
||||
bool PutNextDirEntry(const wxString& name);
|
||||
Create a new directory entry (see wxArchiveEntry::IsDir()) with the given
|
||||
name and timestamp.
|
||||
|
||||
PutNextEntry() can also be used to create directory entries, by supplying
|
||||
a name with a trailing path separator.
|
||||
*/
|
||||
bool PutNextDirEntry(const wxString& name, const wxDateTime& dt = wxDateTime::Now());
|
||||
|
||||
//@{
|
||||
/**
|
||||
, @b wxFileOffset@e size = wxInvalidOffset)
|
||||
Create a new entry with the given name, timestamp and size.
|
||||
Takes ownership of entry and uses it to create a new entry in the tar.
|
||||
*/
|
||||
bool PutNextEntry(wxTarEntry* entry);
|
||||
bool PutNextEntry(const wxString& name);
|
||||
//@}
|
||||
|
||||
/**
|
||||
Create a new entry with the given name, timestamp and size.
|
||||
*/
|
||||
bool PutNextEntry(const wxString& name, const wxDateTime& dt = wxDateTime::Now(),
|
||||
wxFileOffset size = wxInvalidOffset);
|
||||
};
|
||||
|
||||
|
||||
@@ -212,135 +242,161 @@ public:
|
||||
|
||||
Holds the meta-data for an entry in a tar.
|
||||
|
||||
@library{wxbase}
|
||||
@category{FIXME}
|
||||
@section tarentry_fields Field availability
|
||||
|
||||
@see @ref overview_wxarc "Archive formats such as zip", wxTarInputStream,
|
||||
wxTarOutputStream
|
||||
The tar format stores all the meta-data for an entry ahead of its data,
|
||||
therefore GetNextEntry() always returns a fully populated wxTarEntry object,
|
||||
both when reading from seekable and non-seekable streams.
|
||||
|
||||
@library{wxbase}
|
||||
@category{archive,streams}
|
||||
|
||||
@see @ref overview_archive, wxTarInputStream, wxTarOutputStream
|
||||
*/
|
||||
class wxTarEntry : public wxArchiveEntry
|
||||
{
|
||||
public:
|
||||
//@{
|
||||
/**
|
||||
Constructor.
|
||||
|
||||
The tar archive format stores the entry's size ahead of the entry's data.
|
||||
Therefore when creating an archive on a non-seekable stream it is necessary
|
||||
to supply the correct size when each entry is created.
|
||||
*/
|
||||
wxTarEntry(const wxString& name = wxEmptyString,
|
||||
const wxDateTime& dt = wxDateTime::Now(),
|
||||
wxFileOffset size = wxInvalidOffset);
|
||||
|
||||
/**
|
||||
Copy constructor.
|
||||
*/
|
||||
wxTarEntry(const wxString& name = wxEmptyString);
|
||||
wxTarEntry(const wxTarEntry& entry);
|
||||
|
||||
//@{
|
||||
/**
|
||||
Gets/sets the entry's access time stamp.
|
||||
See also wxArchiveEntry::GetDateTime() and wxArchiveEntry::SetDateTime().
|
||||
*/
|
||||
wxDateTime GetAccessTime() const;
|
||||
void SetAccessTime(const wxDateTime& dt);
|
||||
//@}
|
||||
|
||||
//@{
|
||||
/**
|
||||
The entry's access time stamp. See also
|
||||
wxArchiveEntry::Get/SetDateTime.
|
||||
The entry's creation time stamp.
|
||||
See also wxArchiveEntry::GetDateTime() and wxArchiveEntry::SetDateTime().
|
||||
*/
|
||||
wxDateTime GetAccessTime();
|
||||
const void SetAccessTime(const wxDateTime& dt);
|
||||
wxDateTime GetCreateTime() const;
|
||||
void SetCreateTime(const wxDateTime& dt);
|
||||
//@}
|
||||
|
||||
//@{
|
||||
/**
|
||||
The entry's creation time stamp. See also
|
||||
wxArchiveEntry::Get/SetDateTime.
|
||||
OS specific IDs defining a device; these are only meaningful when
|
||||
wxTarEntry::GetTypeFlag() is @e wxTAR_CHRTYPE or @e wxTAR_BLKTYPE.
|
||||
*/
|
||||
wxDateTime GetCreateTime();
|
||||
const void SetCreateTime(const wxDateTime& dt);
|
||||
//@}
|
||||
|
||||
//@{
|
||||
/**
|
||||
OS specific IDs defining a device, these are only meaningful when
|
||||
TypeFlag() is set to @e wxTAR_CHRTYPE
|
||||
or @e wxTAR_BLKTYPE.
|
||||
*/
|
||||
int GetDevMajor();
|
||||
const int GetDevMinor();
|
||||
const void SetDevMajor(int dev);
|
||||
int GetDevMajor() const;
|
||||
int GetDevMinor() const;
|
||||
void SetDevMajor(int dev);
|
||||
void SetDevMinor(int dev);
|
||||
//@}
|
||||
|
||||
//@{
|
||||
/**
|
||||
The user ID and group ID that has @ref mode() permissions over
|
||||
this entry. These values aren't usually useful unless the file will only be
|
||||
restored to the same system it originated from. @ref unamegname()
|
||||
"Get/SetGroupName and
|
||||
Get/SetUserName" can be used instead.
|
||||
The user ID and group ID that has permissions (see wxTarEntry::GetMode())
|
||||
over this entry.
|
||||
|
||||
These values aren't usually useful unless the file will only be
|
||||
restored to the same system it originated from.
|
||||
wxTarEntry::GetGroupName() and wxTarEntry::GetUserName() can be used instead.
|
||||
*/
|
||||
int GetGroupId();
|
||||
const int GetUserId();
|
||||
const void SetGroupId(int id);
|
||||
int GetGroupId() const;
|
||||
int GetUserId() const;
|
||||
void SetGroupId(int id);
|
||||
void SetUserId(int id);
|
||||
//@}
|
||||
|
||||
//@{
|
||||
/**
|
||||
The names of the user and group that has @ref mode() permissions
|
||||
The names of the user and group that has permissions (see wxTarEntry::GetMode())
|
||||
over this entry. These are not present in very old tars.
|
||||
*/
|
||||
wxString GetGroupName();
|
||||
const wxString GetUserName();
|
||||
const void SetGroupName(const wxString& group);
|
||||
wxString GetGroupName() const;
|
||||
wxString GetUserName() const;
|
||||
void SetGroupName(const wxString& group);
|
||||
void SetUserName(const wxString& user);
|
||||
//@}
|
||||
|
||||
//@{
|
||||
/**
|
||||
The filename of a previous entry in the tar that this entry is a link to.
|
||||
Only meaningful when TypeFlag() is set
|
||||
to @e wxTAR_LNKTYPE or @e wxTAR_SYMTYPE.
|
||||
Only meaningful when wxTarEntry::GetTypeFlag() is set to @e wxTAR_LNKTYPE
|
||||
or @e wxTAR_SYMTYPE.
|
||||
*/
|
||||
wxString GetLinkName();
|
||||
const void SetLinkName(const wxString& link);
|
||||
wxString GetLinkName() const;
|
||||
void SetLinkName(const wxString& link);
|
||||
//@}
|
||||
|
||||
//@{
|
||||
/**
|
||||
UNIX permission bits for this entry. Giving read, write and execute permissions
|
||||
to the file's @ref unamegname() "User and Group" and to others.
|
||||
Symbols are defined for them in wx/file.h.
|
||||
UNIX permission bits for this entry.
|
||||
Giving read, write and execute permissions to the file's user and group
|
||||
(see GetGroupName() and GetUserName()) and to others.
|
||||
|
||||
The integer is one or more ::wxPosixPermissions flags OR-combined.
|
||||
*/
|
||||
int GetMode();
|
||||
const void SetMode(int mode);
|
||||
int GetMode() const;
|
||||
void SetMode(int mode);
|
||||
//@}
|
||||
|
||||
//@{
|
||||
/**
|
||||
The size of the entry's data in bytes.
|
||||
|
||||
The tar archive format stores the entry's size ahead of the entry's data.
|
||||
Therefore when creating an archive on a non-seekable stream it is necessary to
|
||||
supply the correct size when each entry is created. For seekable streams this
|
||||
is not necessary as wxTarOutputStream will attempt
|
||||
supply the correct size when each entry is created.
|
||||
|
||||
For seekable streams this is not necessary as wxTarOutputStream will attempt
|
||||
to seek back and fix the entry's header when the entry is closed, though it is
|
||||
still more efficient if the size is given beforehand.
|
||||
*/
|
||||
void SetSize(wxFileOffset size) const;
|
||||
void SetSize(wxFileOffset size);
|
||||
wxFileOffset GetSize() const;
|
||||
//@}
|
||||
|
||||
//@{
|
||||
/**
|
||||
Returns the type of the entry. It should be one of the following:
|
||||
Returns/Sets the type of the entry as a ::wxTarType value.
|
||||
|
||||
When creating archives use just these values. When reading archives
|
||||
any other values should be treated as @e wxTAR_REGTYPE.
|
||||
When creating archives use only one of ::wxTarType values.
|
||||
When reading archives, GetTypeFlag() may return a value which does not
|
||||
match any value of ::wxTarType; in this case the returned value should be
|
||||
treated as @e wxTAR_REGTYPE.
|
||||
*/
|
||||
int GetTypeFlag();
|
||||
const void SetTypeFlag(int type);
|
||||
int GetTypeFlag() const;
|
||||
void SetTypeFlag(int type);
|
||||
//@}
|
||||
|
||||
//@{
|
||||
/**
|
||||
Returns the entry's filename in the internal format used within the archive.
|
||||
|
||||
The name can include directory components, i.e. it can be a full path.
|
||||
The names of directory entries are returned without any trailing path separator.
|
||||
This gives a canonical name that can be used in comparisons.
|
||||
*/
|
||||
wxString GetInternalName() const;
|
||||
|
||||
/**
|
||||
A static member that translates a filename into the internal format used
|
||||
within the archive. If the third parameter is provided, the bool pointed
|
||||
to is set to indicate whether the name looks like a directory name
|
||||
(i.e. has a trailing path separator).
|
||||
within the archive.
|
||||
|
||||
If the third parameter is provided, the bool pointed to is set to indicate
|
||||
whether the name looks like a directory name (i.e. has a trailing path separator).
|
||||
*/
|
||||
wxString GetInternalName();
|
||||
const wxString GetInternalName(const wxString& name,
|
||||
static wxString GetInternalName(const wxString& name,
|
||||
wxPathFormat format = wxPATH_NATIVE,
|
||||
bool* pIsDir = NULL);
|
||||
//@}
|
||||
|
||||
/**
|
||||
Assignment operator.
|
||||
|
Reference in New Issue
Block a user