compress::zlib.3

视频监控网络部分的协议ddns,的模块的实现代码,请大家大胆指正.

.Sp
It is legal to intermix calls to \f(CW\*(C`gzread\*(C'\fR and \f(CW\*(C`gzreadline\*(C'\fR.
.Sp
To maintain backward compatibility with version 1.x of this module
\&\f(CW\*(C`gzreadline\*(C'\fR ignores the \f(CW$/\fR variable \- it \fIalways\fR uses the string
\&\f(CW"\en"\fR as the line delimiter.
.Sp
If you want to read a gzip file a line at a time and have it respect the
\&\f(CW$/\fR variable (or \f(CW$INPUT_RECORD_SEPARATOR\fR, or \f(CW$RS\fR when \f(CW\*(C`English\*(C'\fR is
in use) see IO::Uncompress::Gunzip.
.ie n .IP "\fB\fB$byteswritten\fB = \f(BI$gz\fB\->gzwrite($buffer) ;\fR" 5
.el .IP "\fB\f(CB$byteswritten\fB = \f(CB$gz\fB\->gzwrite($buffer) ;\fR" 5
.IX Item "$byteswritten = $gz->gzwrite($buffer) ;"
Writes the contents of \f(CW$buffer\fR to the compressed file. Returns the
number of bytes actually written, or 0 on error.
.ie n .IP "\fB\fB$status\fB = \f(BI$gz\fB\->gzflush($flush_type) ;\fR" 5
.el .IP "\fB\f(CB$status\fB = \f(CB$gz\fB\->gzflush($flush_type) ;\fR" 5
.IX Item "$status = $gz->gzflush($flush_type) ;"
Flushes all pending output into the compressed file.
.Sp
This method takes an optional parameter, \f(CW$flush_type\fR, that controls
how the flushing will be carried out. By default the \f(CW$flush_type\fR
used is \f(CW\*(C`Z_FINISH\*(C'\fR. Other valid values for \f(CW$flush_type\fR are
\&\f(CW\*(C`Z_NO_FLUSH\*(C'\fR, \f(CW\*(C`Z_SYNC_FLUSH\*(C'\fR, \f(CW\*(C`Z_FULL_FLUSH\*(C'\fR and \f(CW\*(C`Z_BLOCK\*(C'\fR. It is
strongly recommended that you only set the \f(CW\*(C`flush_type\*(C'\fR parameter if
you fully understand the implications of what it does \- overuse of \f(CW\*(C`flush\*(C'\fR
can seriously degrade the level of compression achieved. See the \f(CW\*(C`zlib\*(C'\fR
documentation for details.
.Sp
Returns 0 on success.
.ie n .IP "\fB\fB$offset\fB = \f(BI$gz\fB\->\f(BIgztell()\fB ;\fR" 5
.el .IP "\fB\f(CB$offset\fB = \f(CB$gz\fB\->\f(BIgztell()\fB ;\fR" 5
.IX Item "$offset = $gz->gztell() ;"
Returns the uncompressed file offset.
.ie n .IP "\fB\fB$status\fB = \f(BI$gz\fB\->gzseek($offset, \f(CB$whence\fB) ;\fR" 5
.el .IP "\fB\f(CB$status\fB = \f(CB$gz\fB\->gzseek($offset, \f(CB$whence\fB) ;\fR" 5
.IX Item "$status = $gz->gzseek($offset, $whence) ;"
Provides a sub-set of the \f(CW\*(C`seek\*(C'\fR functionality, with the restriction
that it is only legal to seek forward in the compressed file.
It is a fatal error to attempt to seek backward.
.Sp
When opened for writing, empty parts of the file will have \s-1NULL\s0 (0x00)
bytes written to them.
.Sp
The \f(CW$whence\fR parameter should be one of \s-1SEEK_SET\s0, \s-1SEEK_CUR\s0 or \s-1SEEK_END\s0.
.Sp
Returns 1 on success, 0 on failure.
.ie n .IP "\fB\fB$gz\fB\->gzclose\fR" 5
.el .IP "\fB\f(CB$gz\fB\->gzclose\fR" 5
.IX Item "$gz->gzclose"
Closes the compressed file. Any pending data is flushed to the file
before it is closed.
.Sp
Returns 0 on success.
.ie n .IP "\fB\fB$gz\fB\->gzsetparams($level, \f(BI$strategy\fB\fR" 5
.el .IP "\fB\f(CB$gz\fB\->gzsetparams($level, \f(CB$strategy\fB\fR" 5
.IX Item "$gz->gzsetparams($level, $strategy"
Change settings for the deflate stream \f(CW$gz\fR.
.Sp
The list of the valid options is shown below. Options not specified
will remain unchanged.
.Sp
Note: This method is only available if you are running zlib 1.0.6 or better.
.RS 5
.ie n .IP "\fB\fB$level\fB\fR" 5
.el .IP "\fB\f(CB$level\fB\fR" 5
.IX Item "$level"
Defines the compression level. Valid values are 0 through 9,
\&\f(CW\*(C`Z_NO_COMPRESSION\*(C'\fR, \f(CW\*(C`Z_BEST_SPEED\*(C'\fR, \f(CW\*(C`Z_BEST_COMPRESSION\*(C'\fR, and
\&\f(CW\*(C`Z_DEFAULT_COMPRESSION\*(C'\fR.
.ie n .IP "\fB\fB$strategy\fB\fR" 5
.el .IP "\fB\f(CB$strategy\fB\fR" 5
.IX Item "$strategy"
Defines the strategy used to tune the compression. The valid values are
\&\f(CW\*(C`Z_DEFAULT_STRATEGY\*(C'\fR, \f(CW\*(C`Z_FILTERED\*(C'\fR and \f(CW\*(C`Z_HUFFMAN_ONLY\*(C'\fR.
.RE
.RS 5
.RE
.ie n .IP "\fB\fB$gz\fB\->gzerror\fR" 5
.el .IP "\fB\f(CB$gz\fB\->gzerror\fR" 5
.IX Item "$gz->gzerror"
Returns the \fIzlib\fR error message or number for the last operation
associated with \f(CW$gz\fR. The return value will be the \fIzlib\fR error
number when used in a numeric context and the \fIzlib\fR error message
when used in a string context. The \fIzlib\fR error number constants,
shown below, are available for use.
.Sp
.Vb 7
\&    Z_OK
\&    Z_STREAM_END
\&    Z_ERRNO
\&    Z_STREAM_ERROR
\&    Z_DATA_ERROR
\&    Z_MEM_ERROR
\&    Z_BUF_ERROR
.Ve
.ie n .IP "\fB\fB$gzerrno\fB\fR" 5
.el .IP "\fB\f(CB$gzerrno\fB\fR" 5
.IX Item "$gzerrno"
The \f(CW$gzerrno\fR scalar holds the error code associated with the most
recent \fIgzip\fR routine. Note that unlike \f(CW\*(C`gzerror()\*(C'\fR, the error is
\&\fInot\fR associated with a particular file.
.Sp
As with \f(CW\*(C`gzerror()\*(C'\fR it returns an error number in numeric context and
an error message in string context. Unlike \f(CW\*(C`gzerror()\*(C'\fR though, the
error message will correspond to the \fIzlib\fR message when the error is
associated with \fIzlib\fR itself, or the \s-1UNIX\s0 error message when it is
not (i.e. \fIzlib\fR returned \f(CW\*(C`Z_ERRORNO\*(C'\fR).
.Sp
As there is an overlap between the error numbers used by \fIzlib\fR and
\&\s-1UNIX\s0, \f(CW$gzerrno\fR should only be used to check for the presence of
\&\fIan\fR error in numeric context. Use \f(CW\*(C`gzerror()\*(C'\fR to check for specific
\&\fIzlib\fR errors. The \fIgzcat\fR example below shows how the variable can
be used safely.
.Sh "Examples"
.IX Subsection "Examples"
Here is an example script which uses the interface. It implements a
\&\fIgzcat\fR function.
.PP
.Vb 2
\&    use strict ;
\&    use warnings ;
\&    
\&    use Compress::Zlib ;
\&    
\&    # use stdin if no files supplied
\&    @ARGV = \*(Aq\-\*(Aq unless @ARGV ;
\&    
\&    foreach my $file (@ARGV) {
\&        my $buffer ;
\&    
\&        my $gz = gzopen($file, "rb") 
\&             or die "Cannot open $file: $gzerrno\en" ;
\&    
\&        print $buffer while $gz\->gzread($buffer) > 0 ;
\&    
\&        die "Error reading from $file: $gzerrno" . ($gzerrno+0) . "\en" 
\&            if $gzerrno != Z_STREAM_END ;
\&        
\&        $gz\->gzclose() ;
\&    }
.Ve
.PP
Below is a script which makes use of \f(CW\*(C`gzreadline\*(C'\fR. It implements a
very simple \fIgrep\fR like script.
.PP
.Vb 2
\&    use strict ;
\&    use warnings ;
\&    
\&    use Compress::Zlib ;
\&    
\&    die "Usage: gzgrep pattern [file...]\en"
\&        unless @ARGV >= 1;
\&    
\&    my $pattern = shift ;
\&    
\&    # use stdin if no files supplied
\&    @ARGV = \*(Aq\-\*(Aq unless @ARGV ;
\&    
\&    foreach my $file (@ARGV) {
\&        my $gz = gzopen($file, "rb") 
\&             or die "Cannot open $file: $gzerrno\en" ;
\&    
\&        while ($gz\->gzreadline($_) > 0) {
\&            print if /$pattern/ ;
\&        }
\&    
\&        die "Error reading from $file: $gzerrno\en" 
\&            if $gzerrno != Z_STREAM_END ;
\&        
\&        $gz\->gzclose() ;
\&    }
.Ve
.PP
This script, \fIgzstream\fR, does the opposite of the \fIgzcat\fR script
above. It reads from standard input and writes a gzip data stream to
standard output.
.PP
.Vb 2
\&    use strict ;
\&    use warnings ;
\&    
\&    use Compress::Zlib ;
\&    
\&    binmode STDOUT;  # gzopen only sets it on the fd
\&    
\&    my $gz = gzopen(\e*STDOUT, "wb")
\&          or die "Cannot open stdout: $gzerrno\en" ;
\&    
\&    while (<>) {
\&        $gz\->gzwrite($_) 
\&          or die "error writing: $gzerrno\en" ;
\&    }
\&
\&    $gz\->gzclose ;
.Ve
.Sh "Compress::Zlib::memGzip"
.IX Subsection "Compress::Zlib::memGzip"
This function is used to create an in-memory gzip file with the minimum
possible gzip header (exactly 10 bytes).
.PP
.Vb 1
\&    $dest = Compress::Zlib::memGzip($buffer) ;
.Ve
.PP
If successful, it returns the in-memory gzip file, otherwise it returns
undef.
.PP
The \f(CW$buffer\fR parameter can either be a scalar or a scalar reference.
.PP
See IO::Compress::Gzip for an alternative way to
carry out in-memory gzip compression.
.Sh "Compress::Zlib::memGunzip"
.IX Subsection "Compress::Zlib::memGunzip"
This function is used to uncompress an in-memory gzip file.
.PP
.Vb 1
\&    $dest = Compress::Zlib::memGunzip($buffer) ;
.Ve
.PP
If successful, it returns the uncompressed gzip file, otherwise it
returns undef.
.PP
The \f(CW$buffer\fR parameter can either be a scalar or a scalar reference. The
contents of the \f(CW$buffer\fR parameter are destroyed after calling this function.
.PP
See IO::Uncompress::Gunzip for an alternative way
to carry out in-memory gzip uncompression.
.SH "COMPRESS/UNCOMPRESS"
.IX Header "COMPRESS/UNCOMPRESS"
Two functions are provided to perform in-memory compression/uncompression of
\&\s-1RFC\s0 1950 data streams. They are called \f(CW\*(C`compress\*(C'\fR and \f(CW\*(C`uncompress\*(C'\fR.
.ie n .IP "\fB\fB$dest\fB = compress($source [, \f(BI$level\fB] ) ;\fR" 5
.el .IP "\fB\f(CB$dest\fB = compress($source [, \f(CB$level\fB] ) ;\fR" 5
.IX Item "$dest = compress($source [, $level] ) ;"
Compresses \f(CW$source\fR. If successful it returns the compressed
data. Otherwise it returns \fIundef\fR.
.Sp
The source buffer, \f(CW$source\fR, can either be a scalar or a scalar
reference.
.Sp
The \f(CW$level\fR parameter defines the compression level. Valid values are
0 through 9, \f(CW\*(C`Z_NO_COMPRESSION\*(C'\fR, \f(CW\*(C`Z_BEST_SPEED\*(C'\fR,
\&\f(CW\*(C`Z_BEST_COMPRESSION\*(C'\fR, and \f(CW\*(C`Z_DEFAULT_COMPRESSION\*(C'\fR.
If \f(CW$level\fR is not specified \f(CW\*(C`Z_DEFAULT_COMPRESSION\*(C'\fR will be used.
.ie n .IP "\fB\fB$dest\fB = uncompress($source) ;\fR" 5
.el .IP "\fB\f(CB$dest\fB = uncompress($source) ;\fR" 5
.IX Item "$dest = uncompress($source) ;"
Uncompresses \f(CW$source\fR. If successful it returns the uncompressed
data. Otherwise it returns \fIundef\fR.
.Sp
The source buffer can either be a scalar or a scalar reference.
.PP
Please note: the two functions defined above are \fInot\fR compatible with
the Unix commands of the same name.
.PP
See IO::Deflate and IO::Inflate included with
this distribution for an alternative interface for reading/writing \s-1RFC\s0 1950
files/buffers.
.SH "Deflate Interface"
.IX Header "Deflate Interface"
This section defines an interface that allows in-memory compression using
the \fIdeflate\fR interface provided by zlib.
.PP
Here is a definition of the interface available:
.ie n .Sh "\fB($d, \fP\fB$status\fP\fB) = deflateInit( [\s-1OPT\s0] )\fP"
.el .Sh "\fB($d, \fP\f(CB$status\fP\fB) = deflateInit( [\s-1OPT\s0] )\fP"
.IX Subsection "($d, $status) = deflateInit( [OPT] )"
Initialises a deflation stream.
.PP
It combines the features of the \fIzlib\fR functions \f(CW\*(C`deflateInit\*(C'\fR,
\&\f(CW\*(C`deflateInit2\*(C'\fR and \f(CW\*(C`deflateSetDictionary\*(C'\fR.
.PP
If successful, it will return the initialised deflation stream, \f(CW$d\fR
and \f(CW$status\fR of \f(CW\*(C`Z_OK\*(C'\fR in a list context. In scalar context it
returns the deflation stream, \f(CW$d\fR, only.
.PP
If not successful, the returned deflation stream (\f(CW$d\fR) will be
\&\fIundef\fR and \f(CW$status\fR will hold the exact \fIzlib\fR error code.
.PP
The function optionally takes a number of named options specified as
\&\f(CW\*(C`\-Name=>value\*(C'\fR pairs. This allows individual options to be
tailored without having to specify them all in the parameter list.
.PP
For backward compatibility, it is also possible to pass the parameters
as a reference to a hash containing the name=>value pairs.
.PP
The function takes one optional parameter, a reference to a hash.  The
contents of the hash allow the deflation interface to be tailored.
.PP
Here is a list of the valid options:
.IP "\fB\-Level\fR" 5
.IX Item "-Level"
Defines the compression level. Valid values are 0 through 9,
\&\f(CW\*(C`Z_NO_COMPRESSION\*(C'\fR, \f(CW\*(C`Z_BEST_SPEED\*(C'\fR, \f(CW\*(C`Z_BEST_COMPRESSION\*(C'\fR, and
\&\f(CW\*(C`Z_DEFAULT_COMPRESSION\*(C'\fR.
.Sp
The default is Z_DEFAULT_COMPRESSION.
.IP "\fB\-Method\fR" 5
.IX Item "-Method"
Defines the compression method. The only valid value at present (and
the default) is Z_DEFLATED.
.IP "\fB\-WindowBits\fR" 5
.IX Item "-WindowBits"
To create an \s-1RFC\s0 1950 data stream, set \f(CW\*(C`WindowBits\*(C'\fR to a positive number.
.Sp
To create an \s-1RFC\s0 1951 data stream, set \f(CW\*(C`WindowBits\*(C'\fR to \f(CW\*(C`\-MAX_WBITS\*(C'\fR.
.Sp
For a full definition of the meaning and valid values for \f(CW\*(C`WindowBits\*(C'\fR refer
to the \fIzlib\fR documentation for \fIdeflateInit2\fR.
.Sp
Defaults to \s-1MAX_WBITS\s0.
.IP "\fB\-MemLevel\fR" 5
.IX Item "-MemLevel"
For a definition of the meaning and valid values for \f(CW\*(C`MemLevel\*(C'\fR
refer to the \fIzlib\fR documentation for \fIdeflateInit2\fR.
.Sp
Defaults to \s-1MAX_MEM_LEVEL\s0.
.IP "\fB\-Strategy\fR" 5
.IX Item "-Strategy"
Defines the strategy used to tune the compression. The valid values are
\&\f(CW\*(C`Z_DEFAULT_STRATEGY\*(C'\fR, \f(CW\*(C`Z_FILTERED\*(C'\fR and \f(CW\*(C`Z_HUFFMAN_ONLY\*(C'\fR.
.Sp
The default is Z_DEFAULT_STRATEGY.
.IP "\fB\-Dictionary\fR" 5
.IX Item "-Dictionary"