DWFCore::DWFZipFileDescriptor Class Reference

#include "dwfcore/ZipFileDescriptor.h"

Inheritance diagram for DWFCore::DWFZipFileDescriptor:

Inheritance graph
[legend]
Collaboration diagram for DWFCore::DWFZipFileDescriptor:

Collaboration graph
[legend]
List of all members.

Detailed Description

A descriptor implementation for zip (INFOZIP/PKZIP) file archive access and control.

Since:
1.0.1
Warning:
This object is not thread safe. This is due to the underlying library implementation.
Todo:
Modify this class or derive another that provides thread-safe concurrent archive access.
Examples:

Files/Files.cpp.

Definition at line 88 of file ZipFileDescriptor.h.

Public Types

enum  teFileMode {
  eUnzip = -2, eZip = -1, eZipNone = 0, eZipFastest = 1,
  eZipFast = 3, eZipBlendFaster = 5, eZipBlendSmaller = 7, eZipSmaller = 8,
  eZipSmallest = 9
}
 Enumeration values that define the characteristics by which the archive will be opened and used. More...
enum  teEncryption { eEncrypted, eNotEncrypted, eEncryptionUnknown }
 Enumeration values that reflect the protection level of the archive. More...

Public Member Functions

_DWFCORE_API DWFZipFileDescriptor (const DWFFile &rFile, teFileMode eMode) throw ()
_DWFCORE_API DWFZipFileDescriptor (teFileMode eMode) throw ()
_DWFCORE_API DWFZipFileDescriptor (DWFInputStream &rStream) throw ()
virtual _DWFCORE_API ~DWFZipFileDescriptor () throw ()
virtual _DWFCORE_API void open () throw ( DWFException )
virtual _DWFCORE_API void openIndexed (DWFZipFileIndex *pIndex) throw ( DWFException )
_DWFCORE_API void close () throw ( DWFException )
_DWFCORE_API size_t size () throw ( DWFException )
_DWFCORE_API size_t read (void *pBuffer, size_t nBytesToRead) throw ( DWFException )
_DWFCORE_API off_t seek (int eOrigin, off_t nOffset) throw ( DWFException )
_DWFCORE_API bool locate (const DWFString &rArchivedFile) throw ( DWFException )
_DWFCORE_API DWFInputStreamunzip (const DWFString &zArchivedFile, const DWFString &zPassword=L"") throw ( DWFException )
_DWFCORE_API DWFOutputStreamzip (const DWFString &zArchiveFile, const DWFString &zPassword=L"", bool bPKZIPCompliantPassword=true) throw ( DWFException )
_DWFCORE_API DWFOutputStreamzip (const DWFString &zArchiveFile, teFileMode eZipMode, const DWFString &zPassword=L"", bool bPKZIPCompliantPassword=true) throw ( DWFException )
_DWFCORE_API teEncryption encryption () throw ( DWFException )
_DWFCORE_API const unsigned
char * 
buffer () throw ( DWFException )
_DWFCORE_API size_t buffer (unsigned char *&rpBuffer) throw ( DWFException )
_DWFCORE_API bool archiveCreatedInMemory () throw ()
_DWFCORE_API teFileMode mode () throw ()

Protected Attributes

teFileMode _eMode
teEncryption _eEncryption
zipFile _pZipStream
unzFile _pUnzipStream
DWFInputStream_pInputStream
bool _bCreateArchiveInMemory
DWFStreamOutputBufferDescriptor_pStreamOutputDescriptor
DWFZipFileIndex _oZipFileIndex


Member Enumeration Documentation

enum DWFCore::DWFZipFileDescriptor::teEncryption
 

Enumeration values that reflect the protection level of the archive.

Enumerator:
eEncrypted  The archive has been password protected.
eNotEncrypted  The archive has not been password protected.
eEncryptionUnknown  The archive protection status has not been or could not be determined.

Definition at line 172 of file ZipFileDescriptor.h.

enum DWFCore::DWFZipFileDescriptor::teFileMode
 

Enumeration values that define the characteristics by which the archive will be opened and used.

One of these values must be provided to the constructor to properly configure this descriptor. At this time, only two modes really exist, unzip (read-only) and zip (write-only). The values of the zip mode enumerations should always be kept in sync with the compression levels defined in zlib.h and used by zlib.

Enumerator:
eUnzip  Open the archive for extracting data only.
eZip  Open the archive for storing data only; using the default blend (by zlib) of speed and size.
eZipNone  Open the archive for storing data only; using no compression.
eZipFastest  Open the archive for storing data only; choosing maximum data deflation speed over file size.
eZipFast  Open the archive for storing data only; choosing data deflation speed over file size. This option will be slower and compress better than eZipFastest.
eZipBlendFaster  Open the archive for storing data only; choosing data data deflation speed over file size. This option will be slower and compress better than eZipFast.
eZipBlendSmaller  Open the archive for storing data only; choosing data file size over data deflation speed. This option will be slower and compress better than eZipBlendFaster.
eZipSmaller  Open the archive for storing data only; choosing data file size over data deflation speed. This option will be slower and compress better than eZipBlendSmaller.
eZipSmallest  Open the archive for storing data only; choosing data file size over data deflation speed. This option will be the slowest and compress the best.

Definition at line 107 of file ZipFileDescriptor.h.


Constructor & Destructor Documentation

_DWFCORE_API DWFCore::DWFZipFileDescriptor::DWFZipFileDescriptor const DWFFile rFile,
teFileMode  eMode
throw ()
 

Constructor

Use this constructor to open and manipulate an archive defined with a DWFFile object.

Parameters:
rFile The file on which this descriptor will operate.
eMode An enumeration value that determines how this descriptor will operate on the archive.
Exceptions:
None 

_DWFCORE_API DWFCore::DWFZipFileDescriptor::DWFZipFileDescriptor teFileMode  eMode  )  throw ()
 

Constructor

Use this constructor to write out an archive to a buffer in memory. After the archive is complete, use buffer() to access the data.

Parameters:
eMode An enumeration value that determines how this descriptor will operate on the archive.
Exceptions:
None 
Since:
1.3.0

_DWFCORE_API DWFCore::DWFZipFileDescriptor::DWFZipFileDescriptor DWFInputStream rStream  )  throw ()
 

Constructor

Use this constructor to attach an input stream that has been bound to or can act like a zip archive. This constructor is useful for bridging zip functionality and stream behavior. The zip library that ships with the core library has been modified to use the streaming interfaces defined by the library. This makes it possible expand the use and distribution of the archive itself.

Parameters:
rStream The stream to operate on as a zip archive.
Exceptions:
None 

virtual _DWFCORE_API DWFCore::DWFZipFileDescriptor::~DWFZipFileDescriptor  )  throw () [virtual]
 

Destructor

Exceptions:
None 


Member Function Documentation

_DWFCORE_API bool DWFCore::DWFZipFileDescriptor::archiveCreatedInMemory  )  throw () [inline]
 

Return whether or not the archive is being created in memory.

Returns:
True if this is an in-memory archive.
Exceptions:
None 

Definition at line 449 of file ZipFileDescriptor.h.

_DWFCORE_API size_t DWFCore::DWFZipFileDescriptor::buffer unsigned char *&  rpBuffer  )  throw ( DWFException )
 

If the archive is being created and manipulated in memory, this provides a copy of the buffer and returns the size. An exception is throw in all other cases.

Parameters:
rpBuffer The copied data will be returned via this pointer. The caller must free the memory using DWFCORE_FREE_MEMORY.
Returns:
Size of the buffer.
Exceptions:
DWFException 

_DWFCORE_API const unsigned char* DWFCore::DWFZipFileDescriptor::buffer  )  throw ( DWFException )
 

If the archive is being created and manipulated in memory, this gives direct read-only access to the buffer. An exception is throw in all other cases.

Returns:
A pointer to the buffer.
Exceptions:
DWFException 

_DWFCORE_API void DWFCore::DWFZipFileDescriptor::close  )  throw ( DWFException ) [virtual]
 

Closes the archive.

Exceptions:
None 

Implements DWFCore::DWFFileDescriptor.

_DWFCORE_API teEncryption DWFCore::DWFZipFileDescriptor::encryption  )  throw ( DWFException )
 

Returns the current encryption state. This is determined on file-by-file basis within the archive. Use this method in tandem with locate() to determine the encryption status of the archive and/or a file within.

Returns:
The current encryption state of the file or archive.
Exceptions:
DWFException 

_DWFCORE_API bool DWFCore::DWFZipFileDescriptor::locate const DWFString rArchivedFile  )  throw ( DWFException )
 

Verifies that a particular file exists in the archive and, if successful, positions the internal cursor on the file.

Note:
This method will always attempt to determine the encryption status of the archived file.
Parameters:
rArchivedFile The file in the archive to locate.
Exceptions:
DWFException 

_DWFCORE_API teFileMode DWFCore::DWFZipFileDescriptor::mode  )  throw () [inline]
 

Return the mode that was specified when the archive was opened.

Returns:
The mode that was specified when the archive was opened.
Exceptions:
None 

Definition at line 462 of file ZipFileDescriptor.h.

virtual _DWFCORE_API void DWFCore::DWFZipFileDescriptor::open  )  throw ( DWFException ) [virtual]
 

Opens the archive.

Exceptions:
DWFException 
DWFInvalidTypeException This indicates that a bad or malformed archive.

Implements DWFCore::DWFFileDescriptor.

virtual _DWFCORE_API void DWFCore::DWFZipFileDescriptor::openIndexed DWFZipFileIndex pIndex  )  throw ( DWFException ) [virtual]
 

Opens the archive, using an index.

Parameters:
pIndex A pointer to a DWFZipFileIndex object to be used as an index, or to receive a newly created index (if the structure is empty). If this parameter is NULL, no index will be created.
Exceptions:
DWFException 
DWFInvalidTypeException This indicates that a bad or malformed archive.

_DWFCORE_API size_t DWFCore::DWFZipFileDescriptor::read void *  pBuffer,
size_t  nBytesToRead
throw ( DWFException ) [virtual]
 

Performs a read operation on the archive.

This method is not generally used unless the archive is to be copied in whole or in part by the caller; Use unzip() to extract individual files from the archive.

Note:
This method will throw a DWFIOException if the descriptor was not opened in eUnzip mode.
Parameters:
pBuffer A pointer to a block of memory to receive the bytes.
nBytesToRead The number of bytes to copy into pBuffer. This value should not exceed the capacity of the memory block at pBuffer.
Returns:
The number of actual bytes read.
Exceptions:
DWFException 

Implements DWFCore::DWFFileDescriptor.

_DWFCORE_API off_t DWFCore::DWFZipFileDescriptor::seek int  eOrigin,
off_t  nOffset
throw ( DWFException ) [virtual]
 

Performs a seek operation on the archive.

Parameters:
eOrigin One of SEEK_SET, SEEK_CUR or SEEK_END.
nOffset The number of bytes from eOrigin to move the internal cursor.
Returns:
The previous cursor offset before the seek.
Exceptions:
DWFException 

Implements DWFCore::DWFFileDescriptor.

_DWFCORE_API size_t DWFCore::DWFZipFileDescriptor::size  )  throw ( DWFException ) [virtual]
 

Returns the size of the archive, in bytes. Currently this only returns the size if the archive is being created in memory, and throws an exception in all other cases.

Returns:
The size of the file, in bytes.
Exceptions:
DWFException 

Implements DWFCore::DWFFileDescriptor.

_DWFCORE_API DWFInputStream* DWFCore::DWFZipFileDescriptor::unzip const DWFString zArchivedFile,
const DWFString zPassword = L""
throw ( DWFException )
 

Returns a stream from which the specified file can be extracted from the archive.

Note:
This method will throw a DWFIOException if the descriptor was not opened in eUnzip mode.
Parameters:
zArchivedFile The file to extract from the archive.
zPassword The password required to access the protected zip archive.
Returns:
A pointer to a stream from which the file can be read. The caller must delete this pointer using the DWFCORE_FREE_OBJECT macro.
Exceptions:
DWFException 

_DWFCORE_API DWFOutputStream* DWFCore::DWFZipFileDescriptor::zip const DWFString zArchiveFile,
teFileMode  eZipMode,
const DWFString zPassword = L"",
bool  bPKZIPCompliantPassword = true
throw ( DWFException )
 

Returns a stream with which the specified file can be stored in the archive.

Note:
This method will throw a DWFIOException if the descriptor was not opened in one of the zipping modes.
Parameters:
zArchiveFile The file to store in the archive.
eZipMode Override the zip mode in descriptor and use this instead.
zPassword An optional password to protect the archive.
bPKZIPCompliantPassword An optional boolean to control whether passwording is PKZIP compliant, or if it should use a more secure, custom, form of passwording. The default is true, meaning compliant.
Returns:
A pointer to a stream with which the file can be stored. The caller must delete this pointer using the DWFCORE_FREE_OBJECT macro.
Exceptions:
DWFException 

_DWFCORE_API DWFOutputStream* DWFCore::DWFZipFileDescriptor::zip const DWFString zArchiveFile,
const DWFString zPassword = L"",
bool  bPKZIPCompliantPassword = true
throw ( DWFException )
 

Returns a stream with which the specified file can be stored in the archive.

Note:
This method will throw a DWFIOException if the descriptor was not opened in one of the zipping modes.
Parameters:
zArchiveFile The file to store in the archive.
zPassword An optional password to protect the archive.
bPKZIPCompliantPassword An optional boolean to control whether passwording is PKZIP compliant, or if it should use a more secure, custom, form of passwording. The default is true, meaning compliant.
Returns:
A pointer to a stream with which the file can be stored. The caller must delete this pointer using the DWFCORE_FREE_OBJECT macro.
Exceptions:
DWFException 


Member Data Documentation

bool DWFCore::DWFZipFileDescriptor::_bCreateArchiveInMemory [protected]
 

If true the data is being archived into a buffer.

Definition at line 498 of file ZipFileDescriptor.h.

teEncryption DWFCore::DWFZipFileDescriptor::_eEncryption [protected]
 

The encryption state of the last file processed by locate().

Definition at line 478 of file ZipFileDescriptor.h.

teFileMode DWFCore::DWFZipFileDescriptor::_eMode [protected]
 

The manner in which the archive was opened.

Definition at line 473 of file ZipFileDescriptor.h.

DWFZipFileIndex DWFCore::DWFZipFileDescriptor::_oZipFileIndex [protected]
 

The internal file index structure used if opened without an externally-provided index.

Definition at line 508 of file ZipFileDescriptor.h.

DWFInputStream* DWFCore::DWFZipFileDescriptor::_pInputStream [protected]
 

The external stream that provides read-access to a remote archive or something acting like one.

Definition at line 493 of file ZipFileDescriptor.h.

DWFStreamOutputBufferDescriptor* DWFCore::DWFZipFileDescriptor::_pStreamOutputDescriptor [protected]
 

This is used to write the archive to memory if _bCreateArchiveInMemory is true.

Definition at line 503 of file ZipFileDescriptor.h.

unzFile DWFCore::DWFZipFileDescriptor::_pUnzipStream [protected]
 

The data structure representing an archive reader stream (from the zip library.)

Definition at line 488 of file ZipFileDescriptor.h.

zipFile DWFCore::DWFZipFileDescriptor::_pZipStream [protected]
 

The data structure representing an archive creation/writer stream (from the zip library.)

Definition at line 483 of file ZipFileDescriptor.h.


The documentation for this class was generated from the following file:
Generated on Tue Jan 6 22:39:44 2009 for Autodesk DWF Core Library by  doxygen 1.4.5