archive::zip.3

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

\&\f(CW\*(C`FA_*\*(C'\fR values.
.IP "\fIversionNeededToExtract()\fR" 4
.IX Item "versionNeededToExtract()"
Gets the field from the member header.
.IP "\fIbitFlag()\fR" 4
.IX Item "bitFlag()"
Gets the general purpose bit field from the member header.
This is where the \f(CW\*(C`GPBF_*\*(C'\fR bits live.
.IP "\fIcompressionMethod()\fR" 4
.IX Item "compressionMethod()"
Returns the member compression method. This is the method
that is currently being used to compress the member data.
This will be \s-1COMPRESSION_STORED\s0 for added string or file
members, or any of the \f(CW\*(C`COMPRESSION_*\*(C'\fR values for members
from a zip file. However, this module can only handle members
whose data is in \s-1COMPRESSION_STORED\s0 or \s-1COMPRESSION_DEFLATED\s0
format.
.IP "desiredCompressionMethod( [$method] )" 4
.IX Item "desiredCompressionMethod( [$method] )"
Get or set the member's \f(CW\*(C`desiredCompressionMethod\*(C'\fR. This is
the compression method that will be used when the member is
written. Returns prior desiredCompressionMethod. Only
\&\s-1COMPRESSION_DEFLATED\s0 or \s-1COMPRESSION_STORED\s0 are valid
arguments. Changing to \s-1COMPRESSION_STORED\s0 will change the
member desiredCompressionLevel to 0; changing to
\&\s-1COMPRESSION_DEFLATED\s0 will change the member
desiredCompressionLevel to \s-1COMPRESSION_LEVEL_DEFAULT\s0.
.IP "desiredCompressionLevel( [$method] )" 4
.IX Item "desiredCompressionLevel( [$method] )"
Get or set the member's desiredCompressionLevel This is the
method that will be used to write. Returns prior
desiredCompressionLevel. Valid arguments are 0 through 9,
\&\s-1COMPRESSION_LEVEL_NONE\s0, \s-1COMPRESSION_LEVEL_DEFAULT\s0,
\&\s-1COMPRESSION_LEVEL_BEST_COMPRESSION\s0, and
\&\s-1COMPRESSION_LEVEL_FASTEST\s0. 0 or \s-1COMPRESSION_LEVEL_NONE\s0 will
change the desiredCompressionMethod to \s-1COMPRESSION_STORED\s0.
All other arguments will change the desiredCompressionMethod
to \s-1COMPRESSION_DEFLATED\s0.
.IP "\fIexternalFileName()\fR" 4
.IX Item "externalFileName()"
Return the member's external file name, if any, or undef.
.IP "\fIfileName()\fR" 4
.IX Item "fileName()"
Get or set the member's internal filename. Returns the
(possibly new) filename. Names will have backslashes
converted to forward slashes, and will have multiple
consecutive slashes converted to single ones.
.IP "\fIlastModFileDateTime()\fR" 4
.IX Item "lastModFileDateTime()"
Return the member's last modification date/time stamp in
MS-DOS format.
.IP "\fIlastModTime()\fR" 4
.IX Item "lastModTime()"
Return the member's last modification date/time stamp,
converted to unix localtime format.
.Sp
.Vb 1
\&    print "Mod Time: " . scalar( localtime( $member\->lastModTime() ) );
.Ve
.IP "\fIsetLastModFileDateTimeFromUnix()\fR" 4
.IX Item "setLastModFileDateTimeFromUnix()"
Set the member's lastModFileDateTime from the given unix
time.
.Sp
.Vb 1
\&    $member\->setLastModFileDateTimeFromUnix( time() );
.Ve
.IP "\fIinternalFileAttributes()\fR" 4
.IX Item "internalFileAttributes()"
Return the internal file attributes field from the zip
header. This is only set for members read from a zip file.
.IP "\fIexternalFileAttributes()\fR" 4
.IX Item "externalFileAttributes()"
Return member attributes as read from the \s-1ZIP\s0 file. Note that
these are \s-1NOT\s0 \s-1UNIX\s0!
.IP "unixFileAttributes( [$newAttributes] )" 4
.IX Item "unixFileAttributes( [$newAttributes] )"
Get or set the member's file attributes using \s-1UNIX\s0 file
attributes. Returns old attributes.
.Sp
.Vb 1
\&    my $oldAttribs = $member\->unixFileAttributes( 0666 );
.Ve
.Sp
Note that the return value has more than just the file
permissions, so you will have to mask off the lowest bits for
comparisions.
.IP "localExtraField( [$newField] )" 4
.IX Item "localExtraField( [$newField] )"
Gets or sets the extra field that was read from the local
header. This is not set for a member from a zip file until
after the member has been written out. The extra field must
be in the proper format.
.IP "cdExtraField( [$newField] )" 4
.IX Item "cdExtraField( [$newField] )"
Gets or sets the extra field that was read from the central
directory header. The extra field must be in the proper
format.
.IP "\fIextraFields()\fR" 4
.IX Item "extraFields()"
Return both local and \s-1CD\s0 extra fields, concatenated.
.IP "fileComment( [$newComment] )" 4
.IX Item "fileComment( [$newComment] )"
Get or set the member's file comment.
.IP "\fIhasDataDescriptor()\fR" 4
.IX Item "hasDataDescriptor()"
Get or set the data descriptor flag. If this is set, the
local header will not necessarily have the correct data
sizes. Instead, a small structure will be stored at the end
of the member data with these values. This should be
transparent in normal operation.
.IP "\fIcrc32()\fR" 4
.IX Item "crc32()"
Return the \s-1CRC\-32\s0 value for this member. This will not be set
for members that were constructed from strings or external
files until after the member has been written.
.IP "\fIcrc32String()\fR" 4
.IX Item "crc32String()"
Return the \s-1CRC\-32\s0 value for this member as an 8 character
printable hex string. This will not be set for members that
were constructed from strings or external files until after
the member has been written.
.IP "\fIcompressedSize()\fR" 4
.IX Item "compressedSize()"
Return the compressed size for this member. This will not be
set for members that were constructed from strings or
external files until after the member has been written.
.IP "\fIuncompressedSize()\fR" 4
.IX Item "uncompressedSize()"
Return the uncompressed size for this member.
.IP "\fIisEncrypted()\fR" 4
.IX Item "isEncrypted()"
Return true if this member is encrypted. The Archive::Zip
module does not currently create or extract encrypted
members.
.IP "isTextFile( [$flag] )" 4
.IX Item "isTextFile( [$flag] )"
Returns true if I am a text file. Also can set the status if
given an argument (then returns old state). Note that this
module does not currently do anything with this flag upon
extraction or storage. That is, bytes are stored in native
format whether or not they came from a text file.
.IP "\fIisBinaryFile()\fR" 4
.IX Item "isBinaryFile()"
Returns true if I am a binary file. Also can set the status
if given an argument (then returns old state). Note that this
module does not currently do anything with this flag upon
extraction or storage. That is, bytes are stored in native
format whether or not they came from a text file.
.ie n .IP "extractToFileNamed( $fileName )" 4
.el .IP "extractToFileNamed( \f(CW$fileName\fR )" 4
.IX Item "extractToFileNamed( $fileName )"
Extract me to a file with the given name. The file will be
created with default modes. Directories will be created as
needed.
The \f(CW$fileName\fR argument should be a valid file name on your
file system.
Returns \s-1AZ_OK\s0 on success.
.IP "\fIisDirectory()\fR" 4
.IX Item "isDirectory()"
Returns true if I am a directory.
.IP "\fIwriteLocalHeaderRelativeOffset()\fR" 4
.IX Item "writeLocalHeaderRelativeOffset()"
Returns the file offset in bytes the last time I was written.
.IP "\fIwasWritten()\fR" 4
.IX Item "wasWritten()"
Returns true if I was successfully written. Reset at the
beginning of a write attempt.
.Sh "Low-level member data reading"
.IX Subsection "Low-level member data reading"
It is possible to use lower-level routines to access member data
streams, rather than the extract* methods and \fIcontents()\fR. For
instance, here is how to print the uncompressed contents of a member
in chunks using these methods:
.PP
.Vb 10
\&    my ( $member, $status, $bufferRef );
\&    $member = $zip\->memberNamed( \*(Aqxyz.txt\*(Aq );
\&    $member\->desiredCompressionMethod( COMPRESSION_STORED );
\&    $status = $member\->rewindData();
\&    die "error $status" unless $status == AZ_OK;
\&    while ( ! $member\->readIsDone() )
\&    {
\&    ( $bufferRef, $status ) = $member\->readChunk();
\&    die "error $status"
\&                        if $status != AZ_OK && $status != AZ_STREAM_END;
\&    # do something with $bufferRef:
\&    print $$bufferRef;
\&    }
\&    $member\->endRead();
.Ve
.IP "readChunk( [$chunkSize] )" 4
.IX Item "readChunk( [$chunkSize] )"
This reads the next chunk of given size from the member's
data stream and compresses or uncompresses it as necessary,
returning a reference to the bytes read and a status. If size
argument is not given, defaults to global set by
Archive::Zip::setChunkSize. Status is \s-1AZ_OK\s0 on success until
the last chunk, where it returns \s-1AZ_STREAM_END\s0. Returns \f(CW\*(C`(
\&\e$bytes, $status)\*(C'\fR.
.Sp
.Vb 2
\&    my ( $outRef, $status ) = $self\->readChunk();
\&    print $$outRef if $status != AZ_OK && $status != AZ_STREAM_END;
.Ve
.IP "\fIrewindData()\fR" 4
.IX Item "rewindData()"
Rewind data and set up for reading data streams or writing
zip files. Can take options for \f(CW\*(C`inflateInit()\*(C'\fR or
\&\f(CW\*(C`deflateInit()\*(C'\fR, but this isn't likely to be necessary.
Subclass overrides should call this method. Returns \f(CW\*(C`AZ_OK\*(C'\fR
on success.
.IP "\fIendRead()\fR" 4
.IX Item "endRead()"
Reset the read variables and free the inflater or deflater.
Must be called to close files, etc. Returns \s-1AZ_OK\s0 on success.
.IP "\fIreadIsDone()\fR" 4
.IX Item "readIsDone()"
Return true if the read has run out of data or errored out.
.IP "\fIcontents()\fR" 4
.IX Item "contents()"
Return the entire uncompressed member data or undef in scalar
context. When called in array context, returns \f(CW\*(C`( $string,
$status )\*(C'\fR; status will be \s-1AZ_OK\s0 on success:
.Sp
.Vb 4
\&    my $string = $member\->contents();
\&    # or
\&    my ( $string, $status ) = $member\->contents();
\&    die "error $status" unless $status == AZ_OK;
.Ve
.Sp
Can also be used to set the contents of a member (this may
change the class of the member):
.Sp
.Vb 1
\&    $member\->contents( "this is my new contents" );
.Ve
.ie n .IP "extractToFileHandle( $fh )" 4
.el .IP "extractToFileHandle( \f(CW$fh\fR )" 4
.IX Item "extractToFileHandle( $fh )"
Extract (and uncompress, if necessary) the member's contents
to the given file handle. Return \s-1AZ_OK\s0 on success.
.SH "Archive::Zip::FileMember methods"
.IX Header "Archive::Zip::FileMember methods"
The Archive::Zip::FileMember class extends Archive::Zip::Member. It is the
base class for both ZipFileMember and NewFileMember classes. This class adds
an \f(CW\*(C`externalFileName\*(C'\fR and an \f(CW\*(C`fh\*(C'\fR member to keep track of the external
file.
.IP "\fIexternalFileName()\fR" 4
.IX Item "externalFileName()"
Return the member's external filename.
.IP "\fIfh()\fR" 4
.IX Item "fh()"
Return the member's read file handle. Automatically opens file if
necessary.
.SH "Archive::Zip::ZipFileMember methods"
.IX Header "Archive::Zip::ZipFileMember methods"
The Archive::Zip::ZipFileMember class represents members that have been read
from external zip files.
.IP "\fIdiskNumberStart()\fR" 4
.IX Item "diskNumberStart()"
Returns the disk number that the member's local header resides in.
Should be 0.
.IP "\fIlocalHeaderRelativeOffset()\fR" 4
.IX Item "localHeaderRelativeOffset()"
Returns the offset into the zip file where the member's local header
is.
.IP "\fIdataOffset()\fR" 4
.IX Item "dataOffset()"
Returns the offset from the beginning of the zip file to the member's
data.
.SH "REQUIRED MODULES"
.IX Header "REQUIRED MODULES"
Archive::Zip requires several other modules:
.PP
Carp
.PP
Compress::Zlib
.PP
Cwd
.PP
File::Basename
.PP
File::Copy
.PP
File::Find
.PP
File::Path
.PP
File::Spec
.PP
File::Spec
.PP
IO::File
.PP
IO::Seekable
.PP
Time::Local
.SH "BUGS AND CAVEATS"
.IX Header "BUGS AND CAVEATS"
.Sh "When not to use Archive::Zip"
.IX Subsection "When not to use Archive::Zip"
If you are just going to be extracting zips (and/or other archives) you
are recommended to look at using Archive::Extract instead, as it is much
easier to use and factors out archive-specific functionality.
.Sh "Try to avoid IO::Scalar"
.IX Subsection "Try to avoid IO::Scalar"
One of the most common ways to use Archive::Zip is to generate Zip files
in-memory. Most people have use IO::Scalar for this purpose.
.PP
Unfortunately, as of 1.11 this module no longer works with IO::Scalar
as it incorrectly implements seeking.
.PP
Anybody using IO::Scalar should consider porting to IO::String,
which is smaller, lighter, and is implemented to be perfectly compatible
with regular seekable filehandles.
.PP
Support for IO::Scalar most likely will \fBnot\fR be restored in the
future, as IO::Scalar itself cannot change the way it is implemented
due to back-compatibility issues.
.SH "TO DO"
.IX Header "TO DO"
* auto-choosing storing vs compression
.PP
* extra field hooks (see notes.txt)
.PP
* check for dups on addition/renaming?
.PP
* Text file extraction (line end translation)
.PP
* Reading zip files from non-seekable inputs
  (Perhaps by proxying through IO::String?)
.PP
* separate unused constants into separate module
.PP
* cookbook style docs
.PP
* Handle tainted paths correctly
.PP
* Work on better compatability with other \s-1IO::\s0 modules
.SH "SUPPORT"
.IX Header "SUPPORT"
Bugs should be reported via the \s-1CPAN\s0 bug tracker
.PP
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Archive\-Zip>
.PP
For other issues contact the maintainer
.SH "AUTHOR"
.IX Header "AUTHOR"
Adam Kennedy <[e-mail]>
.PP
Previously maintained by Steve Peters <[e-mail]>.
.PP
File attributes code by Maurice Aubrey <[e-mail]>.
.PP
Originally by Ned Konz <[e-mail]>.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000 \- 2004 Ned Konz.
.PP
Some parts copyright 2005 Steve Peters.
.PP
Some parts copyright 2006 \- 2007 Adam Kennedy.
.PP
This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Compress::Zlib, Archive::Tar, Archive::Extract
.PP
There is a Japanese translation of this
document at <http://www.memb.jp/~deq/perl/doc\-ja/Archive\-Zip.html>
that was done by \s-1DEQ\s0 <[e-mail]> . Thanks!