archive::zip.3

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

actually makes an Archive::Zip::Archive object, but you don't have to worry
about this unless you're subclassing.
.Sh "Constructor"
.IX Subsection "Constructor"
.IP "new( [$fileName] )" 4
.IX Item "new( [$fileName] )"
Make a new, empty zip archive.
.Sp
.Vb 1
\&    my $zip = Archive::Zip\->new();
.Ve
.Sp
If an additional argument is passed, \fInew()\fR will call \fIread()\fR
to read the contents of an archive:
.Sp
.Vb 1
\&    my $zip = Archive::Zip\->new( \*(Aqxyz.zip\*(Aq );
.Ve
.Sp
If a filename argument is passed and the read fails for any
reason, new will return undef. For this reason, it may be
better to call read separately.
.Sh "Zip Archive Utility Methods"
.IX Subsection "Zip Archive Utility Methods"
These Archive::Zip methods may be called as functions or as object
methods. Do not call them as class methods:
.PP
.Vb 4
\&    $zip = Archive::Zip\->new();
\&    $crc = Archive::Zip::computeCRC32( \*(Aqghijkl\*(Aq );    # OK
\&    $crc = $zip\->computeCRC32( \*(Aqghijkl\*(Aq );            # also OK
\&    $crc = Archive::Zip\->computeCRC32( \*(Aqghijkl\*(Aq );    # NOT OK
.Ve
.ie n .IP "Archive::Zip::computeCRC32( $string\fR [, \f(CW$crc] )" 4
.el .IP "Archive::Zip::computeCRC32( \f(CW$string\fR [, \f(CW$crc\fR] )" 4
.IX Item "Archive::Zip::computeCRC32( $string [, $crc] )"
This is a utility function that uses the Compress::Zlib \s-1CRC\s0
routine to compute a \s-1CRC\-32\s0. You can get the \s-1CRC\s0 of a string:
.Sp
.Vb 1
\&    $crc = Archive::Zip::computeCRC32( $string );
.Ve
.Sp
Or you can compute the running \s-1CRC:\s0
.Sp
.Vb 3
\&    $crc = 0;
\&    $crc = Archive::Zip::computeCRC32( \*(Aqabcdef\*(Aq, $crc );
\&    $crc = Archive::Zip::computeCRC32( \*(Aqghijkl\*(Aq, $crc );
.Ve
.ie n .IP "Archive::Zip::setChunkSize( $number )" 4
.el .IP "Archive::Zip::setChunkSize( \f(CW$number\fR )" 4
.IX Item "Archive::Zip::setChunkSize( $number )"
Report or change chunk size used for reading and writing.
This can make big differences in dealing with large files.
Currently, this defaults to 32K. This also changes the chunk
size used for Compress::Zlib. You must call \fIsetChunkSize()\fR
before reading or writing. This is not exportable, so you
must call it like:
.Sp
.Vb 1
\&    Archive::Zip::setChunkSize( 4096 );
.Ve
.Sp
or as a method on a zip (though this is a global setting).
Returns old chunk size.
.IP "\fIArchive::Zip::chunkSize()\fR" 4
.IX Item "Archive::Zip::chunkSize()"
Returns the current chunk size:
.Sp
.Vb 1
\&    my $chunkSize = Archive::Zip::chunkSize();
.Ve
.IP "Archive::Zip::setErrorHandler( \e&subroutine )" 4
.IX Item "Archive::Zip::setErrorHandler( &subroutine )"
Change the subroutine called with error strings. This
defaults to \e&Carp::carp, but you may want to change it to
get the error strings. This is not exportable, so you must
call it like:
.Sp
.Vb 1
\&    Archive::Zip::setErrorHandler( \e&myErrorHandler );
.Ve
.Sp
If myErrorHandler is undef, resets handler to default.
Returns old error handler. Note that if you call Carp::carp
or a similar routine or if you're chaining to the default
error handler from your error handler, you may want to
increment the number of caller levels that are skipped (do
not just set it to a number):
.Sp
.Vb 1
\&    $Carp::CarpLevel++;
.Ve
.IP "Archive::Zip::tempFile( [$tmpdir] )" 4
.IX Item "Archive::Zip::tempFile( [$tmpdir] )"
Create a uniquely named temp file. It will be returned open
for read/write. If \f(CW$tmpdir\fR is given, it is used as the
name of a directory to create the file in. If not given,
creates the file using \f(CW\*(C`File::Spec::tmpdir()\*(C'\fR. Generally, you can
override this choice using the
.Sp
.Vb 1
\&    $ENV{TMPDIR}
.Ve
.Sp
environment variable. But see the File::Spec
documentation for your system. Note that on many systems, if you're
running in taint mode, then you must make sure that \f(CW$ENV{TMPDIR}\fR is
untainted for it to be used.
Will \fI\s-1NOT\s0\fR create \f(CW$tmpdir\fR if it doesn't exist (this is a change
from prior versions!). Returns file handle and name:
.Sp
.Vb 3
\&    my ($fh, $name) = Archive::Zip::tempFile();
\&    my ($fh, $name) = Archive::Zip::tempFile(\*(AqmyTempDir\*(Aq);
\&    my $fh = Archive::Zip::tempFile();  # if you don\*(Aqt need the name
.Ve
.Sh "Zip Archive Accessors"
.IX Subsection "Zip Archive Accessors"
.IP "\fImembers()\fR" 4
.IX Item "members()"
Return a copy of the members array
.Sp
.Vb 1
\&    my @members = $zip\->members();
.Ve
.IP "\fInumberOfMembers()\fR" 4
.IX Item "numberOfMembers()"
Return the number of members I have
.IP "\fImemberNames()\fR" 4
.IX Item "memberNames()"
Return a list of the (internal) file names of the zip members
.ie n .IP "memberNamed( $string )" 4
.el .IP "memberNamed( \f(CW$string\fR )" 4
.IX Item "memberNamed( $string )"
Return ref to member whose filename equals given filename or
undef. \f(CW$string\fR must be in Zip (Unix) filename format.
.ie n .IP "membersMatching( $regex )" 4
.el .IP "membersMatching( \f(CW$regex\fR )" 4
.IX Item "membersMatching( $regex )"
Return array of members whose filenames match given regular
expression in list context. Returns number of matching
members in scalar context.
.Sp
.Vb 3
\&    my @textFileMembers = $zip\->membersMatching( \*(Aq.*\e.txt\*(Aq );
\&    # or
\&    my $numberOfTextFiles = $zip\->membersMatching( \*(Aq.*\e.txt\*(Aq );
.Ve
.IP "\fIdiskNumber()\fR" 4
.IX Item "diskNumber()"
Return the disk that I start on. Not used for writing zips,
but might be interesting if you read a zip in. This should be
0, as Archive::Zip does not handle multi-volume archives.
.IP "\fIdiskNumberWithStartOfCentralDirectory()\fR" 4
.IX Item "diskNumberWithStartOfCentralDirectory()"
Return the disk number that holds the beginning of the
central directory. Not used for writing zips, but might be
interesting if you read a zip in. This should be 0, as
Archive::Zip does not handle multi-volume archives.
.IP "\fInumberOfCentralDirectoriesOnThisDisk()\fR" 4
.IX Item "numberOfCentralDirectoriesOnThisDisk()"
Return the number of \s-1CD\s0 structures in the zipfile last read in.
Not used for writing zips, but might be interesting if you read a zip
in.
.IP "\fInumberOfCentralDirectories()\fR" 4
.IX Item "numberOfCentralDirectories()"
Return the number of \s-1CD\s0 structures in the zipfile last read in.
Not used for writing zips, but might be interesting if you read a zip
in.
.IP "\fIcentralDirectorySize()\fR" 4
.IX Item "centralDirectorySize()"
Returns central directory size, as read from an external zip
file. Not used for writing zips, but might be interesting if
you read a zip in.
.IP "\fIcentralDirectoryOffsetWRTStartingDiskNumber()\fR" 4
.IX Item "centralDirectoryOffsetWRTStartingDiskNumber()"
Returns the offset into the zip file where the \s-1CD\s0 begins. Not
used for writing zips, but might be interesting if you read a
zip in.
.IP "zipfileComment( [$string] )" 4
.IX Item "zipfileComment( [$string] )"
Get or set the zipfile comment. Returns the old comment.
.Sp
.Vb 2
\&    print $zip\->zipfileComment();
\&    $zip\->zipfileComment( \*(AqNew Comment\*(Aq );
.Ve
.IP "\fIeocdOffset()\fR" 4
.IX Item "eocdOffset()"
Returns the (unexpected) number of bytes between where the
\&\s-1EOCD\s0 was found and where it expected to be. This is normally
0, but would be positive if something (a virus, perhaps) had
added bytes somewhere before the \s-1EOCD\s0. Not used for writing
zips, but might be interesting if you read a zip in. Here is
an example of how you can diagnose this:
.Sp
.Vb 5
\&  my $zip = Archive::Zip\->new(\*(Aqsomefile.zip\*(Aq);
\&  if ($zip\->eocdOffset())
\&  {
\&    warn "A virus has added ", $zip\->eocdOffset, " bytes of garbage\en";
\&  }
.Ve
.Sp
The \f(CW\*(C`eocdOffset()\*(C'\fR is used to adjust the starting position of member
headers, if necessary.
.IP "\fIfileName()\fR" 4
.IX Item "fileName()"
Returns the name of the file last read from. If nothing has
been read yet, returns an empty string; if read from a file
handle, returns the handle in string form.
.Sh "Zip Archive Member Operations"
.IX Subsection "Zip Archive Member Operations"
Various operations on a zip file modify members. When a member is
passed as an argument, you can either use a reference to the member
itself, or the name of a member. Of course, using the name requires
that names be unique within a zip (this is not enforced).
.ie n .IP "removeMember( $memberOrName )" 4
.el .IP "removeMember( \f(CW$memberOrName\fR )" 4
.IX Item "removeMember( $memberOrName )"
Remove and return the given member, or match its name and
remove it. Returns undef if member or name doesn't exist in this
Zip. No-op if member does not belong to this zip.
.ie n .IP "replaceMember( $memberOrName\fR, \f(CW$newMember )" 4
.el .IP "replaceMember( \f(CW$memberOrName\fR, \f(CW$newMember\fR )" 4
.IX Item "replaceMember( $memberOrName, $newMember )"
Remove and return the given member, or match its name and
remove it. Replace with new member. Returns undef if member or
name doesn't exist in this Zip, or if \f(CW$newMember\fR is undefined.
.Sp
It is an (undiagnosed) error to provide a \f(CW$newMember\fR that is a
member of the zip being modified.
.Sp
.Vb 4
\&    my $member1 = $zip\->removeMember( \*(Aqxyz\*(Aq );
\&    my $member2 = $zip\->replaceMember( \*(Aqabc\*(Aq, $member1 );
\&    # now, $member2 (named \*(Aqabc\*(Aq) is not in $zip,
\&    # and $member1 (named \*(Aqxyz\*(Aq) is, having taken $member2\*(Aqs place.
.Ve
.ie n .IP "extractMember( $memberOrName\fR [, \f(CW$extractedName ] )" 4
.el .IP "extractMember( \f(CW$memberOrName\fR [, \f(CW$extractedName\fR ] )" 4
.IX Item "extractMember( $memberOrName [, $extractedName ] )"
Extract the given member, or match its name and extract it.
Returns undef if member doesn't exist in this Zip. If
optional second arg is given, use it as the name of the
extracted member. Otherwise, the internal filename of the
member is used as the name of the extracted file or
directory.
If you pass \f(CW$extractedName\fR, it should be in the local file
system's format.
All necessary directories will be created. Returns \f(CW\*(C`AZ_OK\*(C'\fR
on success.
.ie n .IP "extractMemberWithoutPaths( $memberOrName\fR [, \f(CW$extractedName ] )" 4
.el .IP "extractMemberWithoutPaths( \f(CW$memberOrName\fR [, \f(CW$extractedName\fR ] )" 4
.IX Item "extractMemberWithoutPaths( $memberOrName [, $extractedName ] )"
Extract the given member, or match its name and extract it.
Does not use path information (extracts into the current
directory). Returns undef if member doesn't exist in this
Zip.
If optional second arg is given, use it as the name of the
extracted member (its paths will be deleted too). Otherwise,
the internal filename of the member (minus paths) is used as
the name of the extracted file or directory. Returns \f(CW\*(C`AZ_OK\*(C'\fR
on success.
.ie n .IP "addMember( $member )" 4
.el .IP "addMember( \f(CW$member\fR )" 4
.IX Item "addMember( $member )"
Append a member (possibly from another zip file) to the zip
file. Returns the new member. Generally, you will use
\&\fIaddFile()\fR, \fIaddDirectory()\fR, \fIaddFileOrDirectory()\fR, \fIaddString()\fR,
or \fIread()\fR to add members.
.Sp
.Vb 3
\&    # Move member named \*(Aqabc\*(Aq to end of zip:
\&    my $member = $zip\->removeMember( \*(Aqabc\*(Aq );
\&    $zip\->addMember( $member );
.Ve
.ie n .IP "updateMember( $memberOrName\fR, \f(CW$fileName )" 4
.el .IP "updateMember( \f(CW$memberOrName\fR, \f(CW$fileName\fR )" 4
.IX Item "updateMember( $memberOrName, $fileName )"
Update a single member from the file or directory named \f(CW$fileName\fR.
Returns the (possibly added or updated) member, if any; \f(CW\*(C`undef\*(C'\fR on
errors.
The comparison is based on \f(CW\*(C`lastModTime()\*(C'\fR and (in the case of a
non-directory) the size of the file.
.ie n .IP "addFile( $fileName\fR [, \f(CW$newName ] )" 4
.el .IP "addFile( \f(CW$fileName\fR [, \f(CW$newName\fR ] )" 4
.IX Item "addFile( $fileName [, $newName ] )"
Append a member whose data comes from an external file,
returning the member or undef. The member will have its file
name set to the name of the external file, and its
desiredCompressionMethod set to \s-1COMPRESSION_DEFLATED\s0. The
file attributes and last modification time will be set from
the file.
If the name given does not represent a readable plain file or
symbolic link, undef will be returned. \f(CW$fileName\fR must be
in the format required for the local file system.
The optional \f(CW$newName\fR argument sets the internal file name
to something different than the given \f(CW$fileName\fR. \f(CW$newName\fR,
if given, must be in Zip name format (i.e. Unix).
The text mode bit will be set if the contents appears to be
text (as returned by the \f(CW\*(C`\-T\*(C'\fR perl operator).
.Sp
\&\fI\s-1NOTE\s0\fR that you shouldn't (generally) use absolute path names
in zip member names, as this will cause problems with some zip
tools as well as introduce a security hole and make the zip
harder to use.
.ie n .IP "addDirectory( $directoryName\fR [, \f(CW$fileName ] )" 4
.el .IP "addDirectory( \f(CW$directoryName\fR [, \f(CW$fileName\fR ] )" 4
.IX Item "addDirectory( $directoryName [, $fileName ] )"
Append a member created from the given directory name. The
directory name does not have to name an existing directory.
If the named directory exists, the file modification time and
permissions are set from the existing directory, otherwise
they are set to now and permissive default permissions.
\&\f(CW$directoryName\fR must be in local file system format.
The optional second argument sets the name of the archive
member (which defaults to \f(CW$directoryName\fR). If given, it
must be in Zip (Unix) format.
Returns the new member.
.ie n .IP "addFileOrDirectory( $name\fR [, \f(CW$newName ] )" 4
.el .IP "addFileOrDirectory( \f(CW$name\fR [, \f(CW$newName\fR ] )" 4
.IX Item "addFileOrDirectory( $name [, $newName ] )"
Append a member from the file or directory named \f(CW$name\fR. If
\&\f(CW$newName\fR is given, use it for the name of the new member.
Will add or remove trailing slashes from \f(CW$newName\fR as needed.
\&\f(CW$name\fR must be in local file system format.
The optional second argument sets the name of the archive
member (which defaults to \f(CW$name\fR). If given, it must be in
Zip (Unix) format.
.ie n .IP "addString( $stringOrStringRef\fR, \f(CW$name )" 4
.el .IP "addString( \f(CW$stringOrStringRef\fR, \f(CW$name\fR )" 4
.IX Item "addString( $stringOrStringRef, $name )"
Append a member created from the given string or string
reference. The name is given by the second argument.
Returns the new member. The last modification time will be
set to now, and the file attributes will be set to permissive
defaults.
.Sp
.Vb 1
\&    my $member = $zip\->addString( \*(AqThis is a test\*(Aq, \*(Aqtest.txt\*(Aq );
.Ve
.ie n .IP "contents( $memberOrMemberName\fR [, \f(CW$newContents ] )" 4
.el .IP "contents( \f(CW$memberOrMemberName\fR [, \f(CW$newContents\fR ] )" 4
.IX Item "contents( $memberOrMemberName [, $newContents ] )"
Returns the uncompressed data for a particular member, or
undef.
.Sp
.Vb 1
\&    print "xyz.txt contains " . $zip\->contents( \*(Aqxyz.txt\*(Aq );
.Ve
.Sp
Also can change the contents of a member:
.Sp
.Vb 1
\&    $zip\->contents( \*(Aqxyz.txt\*(Aq, \*(AqThis is the new contents\*(Aq );
.Ve
.Sp
If called expecting an array as the return value, it will include
the status as the second value in the array.
.Sp
.Vb 1
\&    ($content, $status) = $zip\->contents( \*(Aqxyz.txt\*(Aq);
.Ve
.Sh "Zip Archive I/O operations"
.IX Subsection "Zip Archive I/O operations"
A Zip archive can be written to a file or file handle, or read from
one.
.ie n .IP "writeToFileNamed( $fileName )" 4
.el .IP "writeToFileNamed( \f(CW$fileName\fR )" 4
.IX Item "writeToFileNamed( $fileName )"
Write a zip archive to named file. Returns \f(CW\*(C`AZ_OK\*(C'\fR on
success.
.Sp
.Vb 2