zip.pm

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

addDirectory(), and addString() zip instance methods described above,
but they don't add the new members to a zip.

=over 4

=item Archive::Zip::Member->newFromString( $stringOrStringRef [, $fileName] )



Construct a new member from the given string. Returns undef
on error.

    my $member = Archive::Zip::Member->newFromString( 'This is a test',
                                                 'xyz.txt' );

=item newFromFile( $fileName )



Construct a new member from the given file. Returns undef on
error.

    my $member = Archive::Zip::Member->newFromFile( 'xyz.txt' );

=item newDirectoryNamed( $directoryName [, $zipname ] )



Construct a new member from the given directory.
C<$directoryName> must be a valid name on your file system; it doesn't
have to exist.


If given, C<$zipname> will be the name of the zip member; it must be a
valid Zip (Unix) name. If not given, it will be converted from
C<$directoryName>.


Returns undef on error.

    my $member = Archive::Zip::Member->newDirectoryNamed( 'CVS/' );

=back

=head2 Member Simple accessors


These methods get (and/or set) member attribute values.

=over 4

=item versionMadeBy()



Gets the field from the member header.

=item fileAttributeFormat( [$format] )



Gets or sets the field from the member header. These are
C<FA_*> values.

=item versionNeededToExtract()



Gets the field from the member header.

=item bitFlag()



Gets the general purpose bit field from the member header.
This is where the C<GPBF_*> bits live.

=item compressionMethod()



Returns the member compression method. This is the method
that is currently being used to compress the member data.
This will be COMPRESSION_STORED for added string or file
members, or any of the C<COMPRESSION_*> values for members
from a zip file. However, this module can only handle members
whose data is in COMPRESSION_STORED or COMPRESSION_DEFLATED
format.

=item desiredCompressionMethod( [$method] )



Get or set the member's C<desiredCompressionMethod>. This is
the compression method that will be used when the member is
written. Returns prior desiredCompressionMethod. Only
COMPRESSION_DEFLATED or COMPRESSION_STORED are valid
arguments. Changing to COMPRESSION_STORED will change the
member desiredCompressionLevel to 0; changing to
COMPRESSION_DEFLATED will change the member
desiredCompressionLevel to COMPRESSION_LEVEL_DEFAULT.

=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,
COMPRESSION_LEVEL_NONE, COMPRESSION_LEVEL_DEFAULT,
COMPRESSION_LEVEL_BEST_COMPRESSION, and
COMPRESSION_LEVEL_FASTEST. 0 or COMPRESSION_LEVEL_NONE will
change the desiredCompressionMethod to COMPRESSION_STORED.
All other arguments will change the desiredCompressionMethod
to COMPRESSION_DEFLATED.

=item externalFileName()



Return the member's external file name, if any, or undef.

=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.

=item lastModFileDateTime()



Return the member's last modification date/time stamp in
MS-DOS format.

=item lastModTime()



Return the member's last modification date/time stamp,
converted to unix localtime format.

    print "Mod Time: " . scalar( localtime( $member->lastModTime() ) );

=item setLastModFileDateTimeFromUnix()

Set the member's lastModFileDateTime from the given unix
time.

    $member->setLastModFileDateTimeFromUnix( time() );

=item internalFileAttributes()

Return the internal file attributes field from the zip
header. This is only set for members read from a zip file.

=item externalFileAttributes()

Return member attributes as read from the ZIP file. Note that
these are NOT UNIX!

=item unixFileAttributes( [$newAttributes] )

Get or set the member's file attributes using UNIX file
attributes. Returns old attributes.

    my $oldAttribs = $member->unixFileAttributes( 0666 );

Note that the return value has more than just the file
permissions, so you will have to mask off the lowest bits for
comparisions.

=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.

=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.

=item extraFields()

Return both local and CD extra fields, concatenated.

=item fileComment( [$newComment] )

Get or set the member's file comment.

=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.

=item crc32()

Return the CRC-32 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.

=item crc32String()

Return the CRC-32 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.

=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.

=item uncompressedSize()

Return the uncompressed size for this member.

=item isEncrypted()

Return true if this member is encrypted. The Archive::Zip
module does not currently create or extract encrypted
members.

=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.

=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.

=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 C<$fileName> argument should be a valid file name on your
file system.
Returns AZ_OK on success.

=item isDirectory()

Returns true if I am a directory.

=item writeLocalHeaderRelativeOffset()

Returns the file offset in bytes the last time I was written.

=item wasWritten()

Returns true if I was successfully written. Reset at the
beginning of a write attempt.

=back

=head2 Low-level member data reading

It is possible to use lower-level routines to access member data
streams, rather than the extract* methods and contents(). For
instance, here is how to print the uncompressed contents of a member
in chunks using these methods:

    my ( $member, $status, $bufferRef );
    $member = $zip->memberNamed( 'xyz.txt' );
    $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();

=over 4

=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 AZ_OK on success until
the last chunk, where it returns AZ_STREAM_END. Returns C<(
\$bytes, $status)>.

    my ( $outRef, $status ) = $self->readChunk();
    print $$outRef if $status != AZ_OK && $status != AZ_STREAM_END;

=item rewindData()

Rewind data and set up for reading data streams or writing
zip files. Can take options for C<inflateInit()> or
C<deflateInit()>, but this isn't likely to be necessary.
Subclass overrides should call this method. Returns C<AZ_OK>
on success.

=item endRead()

Reset the read variables and free the inflater or deflater.
Must be called to close files, etc. Returns AZ_OK on success.

=item readIsDone()

Return true if the read has run out of data or errored out.

=item contents()

Return the entire uncompressed member data or undef in scalar
context. When called in array context, returns C<( $string,
$status )>; status will be AZ_OK on success:

    my $string = $member->contents();
    # or
    my ( $string, $status ) = $member->contents();
    die "error $status" unless $status == AZ_OK;

Can also be used to set the contents of a member (this may
change the class of the member):

    $member->contents( "this is my new contents" );

=item extractToFileHandle( $fh )

Extract (and uncompress, if necessary) the member's contents
to the given file handle. Return AZ_OK on success.

=back

=head1 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 C<externalFileName> and an C<fh> member to keep track of the external
file.

=over 4

=item externalFileName()

Return the member's external filename.

=item fh()

Return the member's read file handle. Automatically opens file if
necessary.

=back

=head1 Archive::Zip::ZipFileMember methods

The Archive::Zip::ZipFileMember class represents members that have been read
from external zip files.

=over 4

=item diskNumberStart()

Returns the disk number that the member's local header resides in.
Should be 0.

=item localHeaderRelativeOffset()

Returns the offset into the zip file where the member's local header
is.

=item dataOffset()

Returns the offset from the beginning of the zip file to the member's
data.

=back

=head1 REQUIRED MODULES

L<Archive::Zip> requires several other modules:

L<Carp>

L<Compress::Zlib>

L<Cwd>

L<File::Basename>

L<File::Copy>

L<File::Find>

L<File::Path>

L<File::Spec>

L<File::Spec>

L<IO::File>

L<IO::Seekable>

L<Time::Local>

=head1 BUGS AND CAVEATS

=head2 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 L<Archive::Extract> instead, as it is much
easier to use and factors out archive-specific functionality.

=head2 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 L<IO::Scalar> for this purpose.

Unfortunately, as of 1.11 this module no longer works with L<IO::Scalar>
as it incorrectly implements seeking.

Anybody using L<IO::Scalar> should consider porting to L<IO::String>,
which is smaller, lighter, and is implemented to be perfectly compatible
with regular seekable filehandles.

Support for L<IO::Scalar> most likely will B<not> be restored in the
future, as L<IO::Scalar> itself cannot change the way it is implemented
due to back-compatibility issues.

=head1 TO DO

* auto-choosing storing vs compression

* extra field hooks (see notes.txt)

* check for dups on addition/renaming?

* Text file extraction (line end translation)

* Reading zip files from non-seekable inputs
  (Perhaps by proxying through IO::String?)

* separate unused constants into separate module

* cookbook style docs

* Handle tainted paths correctly

* Work on better compatability with other IO:: modules

=head1 SUPPORT

Bugs should be reported via the CPAN bug tracker

L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Archive-Zip>

For other issues contact the maintainer

=head1 AUTHOR

Adam Kennedy E<lt>[e-mail]<gt>

Previously maintained by Steve Peters E<lt>[e-mail]<gt>.

File attributes code by Maurice Aubrey E<lt>[e-mail]<gt>.

Originally by Ned Konz E<lt>[e-mail]<gt>.

=head1 COPYRIGHT

Copyright 2000 - 2004 Ned Konz.

Some parts copyright 2005 Steve Peters.

Some parts copyright 2006 - 2007 Adam Kennedy.

This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

=head1 SEE ALSO

L<Compress::Zlib>, L<Archive::Tar>, L<Archive::Extract>

There is a Japanese translation of this
document at L<http://www.memb.jp/~deq/perl/doc-ja/Archive-Zip.html>
that was done by DEQ E<lt>[e-mail]<gt> . Thanks! 

=cut