Added wxPATH_NORM_SHORTCUT

[wxWidgets.git] / docs / latex / wx / gzstream.tex

%
% automatically generated by HelpGen $Revision$ from
% gzstream.h at 20/Aug/03 18:41:55
%

%
% wxGzipInputStream
%

\section{\class{wxGzipInputStream}}\label{wxgzipinputstream}

A stream filter to decompress gzipped data. The gzip format is specified in
RFC-1952.

A gzip stream can contain the original filename and timestamp of the
compressed data. These fields can be obtained using the
 \helpref{GetName()}{wxgzipinputstreamgetname} and
 \helpref{GetDateTime()}{wxgzipinputstreamgetdatetime} accessors.

If the stream turns out not to be a gzip stream (i.e. the signature bytes
0x1f, 0x8b are not found), then the constructor unreads the bytes read and
sets the stream state to {\it wxSTREAM\_EOF}.

So given a possibly gzipped stream '{\it maybe\_gzipped}' you can construct
a decompressed stream '{\it decompressed}' with something like:

\begin{verbatim}
wxGzipInputStream gzip(maybe_gzipped);
wxInputStream *decompressed = &gzip;
if (gzip.Eof())
    decompressed = &maybe_gzipped;

\end{verbatim}
The stream will not read past the end of the gzip data, therefore you
can read another gzip entry concatenated by creating another
 {\it wxGzipInputStream} on the same underlying stream.

The stream is not seekable, \helpref{SeekI()}{wxinputstreamseeki} returns
 {\it wxInvalidOffset}.  Also \helpref{GetSize()}{wxstreambasegetsize} is
not supported, it always returns $0$.

\wxheading{Derived from}

\helpref{wxFilterInputStream}{wxfilterinputstream}

\wxheading{Include files}

<wx/gzstream.h>

\wxheading{See also}

\helpref{wxGzipOutputStream}{wxgzipoutputstream}, 
 \helpref{wxZlibInputStream}{wxzlibinputstream},
 \helpref{wxInputStream}{wxinputstream}.

\latexignore{\rtfignore{\wxheading{Members}}}


\membersection{wxGzipInputStream::wxGzipInputStream}\label{wxgzipinputstreamwxgzipinputstream}

\func{}{wxGzipInputStream}{\param{wxInputStream\& }{stream}, \param{wxMBConv\& }{conv = wxConvFile}}

Constructs an object to decompress a gzipped stream.

The constructor reads the gzip header. If the original file name and timestamp
are present, then they can be obtained through the 
 \helpref{GetName()}{wxgzipinputstreamgetname} and
 \helpref{GetDateTime()}{wxgzipinputstreamgetdatetime} accessors.

The filename in the header is stored using an 8-bit character set. In a
Unicode build {\it conv} is used to translate the filename into Unicode (it
has no effect on the stream data). RFC-1952 specifies that the character set
should be ISO-8859-1, however the default here is to use {\it wxConvFile}
 which more closely matches the behaviour of the gzip program. In
a non-Unicode build {\it conv} is ignored.

If the first two bytes are not the gzip signature, then the data is not
gzipped after all. The stream state is set to {\it wxSTREAM\_EOF}, and the
two bytes are unread so that the underlying stream can be read directly.


\membersection{wxGzipInputStream::\destruct{wxGzipInputStream}}\label{wxgzipinputstreamdtor}

\func{}{\destruct{wxGzipInputStream}}{\void}

Destructor.


\membersection{wxGzipInputStream::GetDateTime}\label{wxgzipinputstreamgetdatetime}

\constfunc{wxDateTime}{GetDateTime}{\void}

Returns the original modification time of gzipped data, as obtained from the
gzip header.


\membersection{wxGzipInputStream::GetName}\label{wxgzipinputstreamgetname}

\constfunc{wxString}{GetName}{\void}

Returns the original filename of gzipped data, with any directory components
removed.


%
% wxGzipOutputStream
%

\section{\class{wxGzipOutputStream}}\label{wxgzipoutputstream}

A stream filter to compress gzipped data. The gzip format is specified in
RFC-1952.

The stream is not seekable, \helpref{SeekO()}{wxoutputstreamseeko} returns 
 {\it wxInvalidOffset}.


\wxheading{Derived from}

\helpref{wxFilterOutputStream}{wxfilteroutputstream}

\wxheading{Include files}

<wx/gzstream.h>

\wxheading{See also}

\helpref{wxGzipInputStream}{wxgzipinputstream}, 
 \helpref{wxZlibOutputStream}{wxzliboutputstream},
 \helpref{wxOutputStream}{wxoutputstream}.

\latexignore{\rtfignore{\wxheading{Members}}}


\membersection{wxGzipOutputStream::wxGzipOutputStream}\label{wxgzipoutputstreamwxgzipoutputstream}

\func{}{wxGzipOutputStream}{\param{wxOutputStream\& }{stream}, \param{const wxString\& }{originalName = wxEmptyString}, \param{const wxDateTime\& }{originalTime = wxDateTime::Now()}, \param{int }{level = -1}, \param{wxMBConv\& }{conv = wxConvFile}}

If the {\it originalName} is given, then it is written to the gzip header
with any directory components removed. On a Unicode build it is first
converted to an 8-bit encoding using {\it conv}. RFC-1952 specifies that
the character set should be ISO-8859-1, however the default here is to
use {\it wxConvFile} which more closely matches the behaviour of the gzip
program. In a non-Unicode build {\it conv} is ignored. {\it conv} has no
effect on the stream data.

If {\it originalTime} is given then it is also written to the gzip header
as the timestamp. If omitted the current time is used.

{\it level} is the compression level. It can be an integer between $0$ (no
compression) and $9$ (most compression). $-1$ specifies that the default
compression should be used, and is currently equivalent to $6$.

You can also use the following constants from <wx/zstream.h>:

\begin{verbatim}
// Compression level
enum {
    wxZ_DEFAULT_COMPRESSION = -1,
    wxZ_NO_COMPRESSION = 0,
    wxZ_BEST_SPEED = 1,
    wxZ_BEST_COMPRESSION = 9
}
\end{verbatim}


\membersection{wxGzipOutputStream::\destruct{wxGzipOutputStream}}\label{wxgzipoutputstreamdtor}

\func{}{\destruct{wxGzipOutputStream}}{\void}

Destructor.