ZIP File System IO

Detailed Description

Barracuda Server ZIP file system I/O plugin.

Data Structures
struct	ZipReader
	Abstract interface class for reading a ZipFile. More...
struct	ZipFileInfo
	Low level ZIP file information used internally by the Zip File System. More...
struct	CentralDirIterator
	Low level ZIP file central directory iterator. More...
struct	ZipContainer
	A ZipContainer is a buffer used by a ZipIo when reading data from a ZipReader. More...

Macros
#define	CentralDirIterator_getECode(o)   (o)->err
	Query the iterator's last parsing result. More...
#define	ZipContainer_getECode(o)   (o)->errCode

Typedefs
typedef ZipReader	ZipReader
	Abstract interface class for reading a ZipFile. More...
typedef struct ZipFileInfo	ZipFileInfo
	Low level ZIP file information used internally by the Zip File System.
typedef struct CentralDirIterator	CentralDirIterator
	Low level ZIP file central directory iterator.
typedef struct ZipContainer	ZipContainer
	A ZipContainer is a buffer used by a ZipIo when reading data from a ZipReader. More...

Enumerations
enum	ZipErr {   ZipErr_Buf = -2000 , ZipErr_Reading , ZipErr_Spanned , ZipErr_Compression ,   ZipErr_Incompatible , ZipErr_NoError = 0 }
	ZIP metadata parsing result; zero is success, negative values are failures. More...
enum	ZipComprMethod
	ZIP compression-method identifiers used in entry metadata.

Functions
BA_API void	ZipReader_constructor (ZipReader *o, CspReader_Read r, U32 zipFileSize)
	Initialize a reader interface; no ZIP data is read yet. More...
BA_API void	CentralDirIterator_constructor (CentralDirIterator *o, struct ZipContainer *container)
	Initialize an iterator using the container's shared working buffer. More...
BA_API void	CentralDirIterator_constructorR (CentralDirIterator *o, struct ZipContainer *container, U8 *buf, U32 bufSize)
	Initialize an iterator with separate working storage. More...
BA_API ZipFileHeader *	CentralDirIterator_getElement (CentralDirIterator *o)
	Read the current central-directory entry. More...
BA_API BaBool	CentralDirIterator_nextElement (CentralDirIterator *o)
	Advance after a successful getElement(). More...
BA_API void	ZipContainer_constructor (ZipContainer *o, ZipReader *reader, U8 *buf, U32 bufSize)
	Create a ZipContainer instance. More...
	ZipReader::ZipReader (CspReader_Read r, U32 zipFileSize)
	Initialize a reader interface; no ZIP data is read yet. More...
	CentralDirIterator::CentralDirIterator (ZipContainer *container)
	Initialize an iterator using the container's shared working buffer. More...
	CentralDirIterator::CentralDirIterator (ZipContainer *container, U8 *buf, U32 bufSize)
	Initialize an iterator with separate working storage. More...
ZipErr	CentralDirIterator::getECode ()
	Query the iterator's last parsing result. More...
ZipFileHeader *	CentralDirIterator::getElement ()
	Read the current central-directory entry. More...
bool	CentralDirIterator::nextElement ()
	Advance after a successful getElement(). More...
	ZipContainer::ZipContainer (ZipReader *reader, U8 *buf, U32 bufSize)
	Create a ZipContainer instance. More...
ZipErr	ZipContainer::getECode ()

Macro Definition Documentation

CentralDirIterator_getECode

#define CentralDirIterator_getECode

(

o

)

(o)->err

Query the iterator's last parsing result.

Returns

ZipErr_NoError initially or after a successful getElement(), otherwise a ZipErr failure. A too-small private buffer sets ZipErr_Buf at construction.

Parameters

o	Required initialized iterator.

ZipContainer_getECode

#define ZipContainer_getECode

(

o

)

(o)->errCode

Returns

ZipErr_NoError on successful construction, otherwise the metadata/buffer/read error. This query performs no I/O.

Parameters

o	Required initialized container.

Typedef Documentation

ZipContainer

typedef struct ZipContainer ZipContainer

A ZipContainer is a buffer used by a ZipIo when reading data from a ZipReader.

You do not directly use a ZipContainer unless you use the internal ZIP CentralDirIterator class. See the ZipFileIterator.h header file for more information.

ZipReader

typedef ZipReader ZipReader

Abstract interface class for reading a ZipFile.

See the example code FileZipReader for more information. You can also use the bin2c tool if you want to embed the ZIP file in the application executable or firmware.

Enumeration Type Documentation

ZipErr

enum ZipErr

ZIP metadata parsing result; zero is success, negative values are failures.

Enumerator
ZipErr_Buf	The buffer is too small.
ZipErr_Reading	Reading failed.
ZipErr_Spanned	Spanned/Split archives not supported.
ZipErr_Compression	Unsupported compr. Can be one of Stored or Deflated
ZipErr_Incompatible	Unknown ZIP Central Directory Structure.

Function Documentation

CentralDirIterator() [1/2]

CentralDirIterator::CentralDirIterator

(

ZipContainer *

container

)

Initialize an iterator using the container's shared working buffer.

Parameters

container

Required successfully initialized container, which must outlive iteration. Do not interleave another user of its shared buffer.

CentralDirIterator() [2/2]

CentralDirIterator::CentralDirIterator	(	ZipContainer *	container,
		U8 *	buf,
		U32	bufSize
	)

Initialize an iterator with separate working storage.

Parameters

container	Required successfully initialized borrowed container.
buf	Required writable buffer, retained throughout iteration.
bufSize	Buffer capacity in bytes, at least 256 and large enough for each entry's header, name, and extra fields. Separate buffers avoid shared scratch storage but do not make the underlying reader thread-safe.

CentralDirIterator_constructor()

BA_API void CentralDirIterator_constructor	(	CentralDirIterator *	o,
		struct ZipContainer *	container
	)

Initialize an iterator using the container's shared working buffer.

Parameters

container	Required successfully initialized container, which must outlive iteration. Do not interleave another user of its shared buffer.
o	Required storage to initialize.

CentralDirIterator_constructorR()

BA_API void CentralDirIterator_constructorR	(	CentralDirIterator *	o,
		struct ZipContainer *	container,
		U8 *	buf,
		U32	bufSize
	)

Initialize an iterator with separate working storage.

Parameters

container	Required successfully initialized borrowed container.
buf	Required writable buffer, retained throughout iteration.
bufSize	Buffer capacity in bytes, at least 256 and large enough for each entry's header, name, and extra fields. Separate buffers avoid shared scratch storage but do not make the underlying reader thread-safe.
o	Required storage to initialize.

CentralDirIterator_getElement()

BA_API ZipFileHeader * CentralDirIterator_getElement

(

CentralDirIterator *

o

)

Read the current central-directory entry.

Returns

Borrowed header on success, or NULL on parsing/read failure; inspect getECode(). Read its values before advancing or reusing the working buffer. The file name is length-delimited, not NUL-terminated. Call only when a current entry exists; this function does not itself test the entry count.

Parameters

o	Required initialized iterator.

CentralDirIterator_nextElement()

BA_API BaBool CentralDirIterator_nextElement

(

CentralDirIterator *

o

)

Advance after a successful getElement().

Returns

True when another directory entry is expected, false at the end. This does not load or validate the next entry. Stop after false.

Parameters

o	Required initialized iterator.

getECode() [1/2]

ZipErr CentralDirIterator::getECode

(

)

Query the iterator's last parsing result.

Returns

ZipErr_NoError initially or after a successful getElement(), otherwise a ZipErr failure. A too-small private buffer sets ZipErr_Buf at construction.

getECode() [2/2]

ZipErr ZipContainer::getECode

(

)

Returns

ZipErr_NoError on successful construction, otherwise the metadata/buffer/read error. This query performs no I/O.

getElement()

ZipFileHeader * CentralDirIterator::getElement

(

)

Read the current central-directory entry.

Returns

Borrowed header on success, or NULL on parsing/read failure; inspect getECode(). Read its values before advancing or reusing the working buffer. The file name is length-delimited, not NUL-terminated. Call only when a current entry exists; this function does not itself test the entry count.

nextElement()

bool CentralDirIterator::nextElement

(

)

Advance after a successful getElement().

Returns

True when another directory entry is expected, false at the end. This does not load or validate the next entry. Stop after false.

ZipContainer()

ZipContainer::ZipContainer	(	ZipReader *	reader,
		U8 *	buf,
		U32	bufSize
	)

Create a ZipContainer instance.

Parameters

reader	Required valid borrowed ZipReader; keep it alive and its archive unchanged while the container is used. An invalid CspReader validity marker invokes baFatalE(FE_INVALID_CSPREADER, 0).
buf	is a buffer with minimum size 256 bytes. You must make sure that this buffer is valid during the lifetime of the class instance.
bufSize	Buffer capacity in bytes. The end-of-directory record must fall within this many bytes of the end of the archive. Long ZIP comments can require a larger buffer. Construction reads metadata; check getECode() before creating an iterator. No ownership is transferred.

ZipContainer_constructor()

BA_API void ZipContainer_constructor	(	ZipContainer *	o,
		ZipReader *	reader,
		U8 *	buf,
		U32	bufSize
	)

Create a ZipContainer instance.

Parameters

reader	Required valid borrowed ZipReader; keep it alive and its archive unchanged while the container is used. An invalid CspReader validity marker invokes baFatalE(FE_INVALID_CSPREADER, 0).
buf	is a buffer with minimum size 256 bytes. You must make sure that this buffer is valid during the lifetime of the class instance.
bufSize	Buffer capacity in bytes. The end-of-directory record must fall within this many bytes of the end of the archive. Long ZIP comments can require a larger buffer. Construction reads metadata; check getECode() before creating an iterator. No ownership is transferred.
o	Required storage to initialize.

ZipReader()

ZipReader::ZipReader	(	CspReader_Read	r,
		U32	zipFileSize
	)

Initialize a reader interface; no ZIP data is read yet.

Parameters

r	Required CspReader_Read callback, callable for the reader's lifetime.
zipFileSize	Complete archive length in bytes, representable in U32. The callback must support offset-based reads within that archive. Construction leaves the inherited validity marker unset; the implementation must call CspReader_setIsValid() after its backing data is ready.

ZipReader_constructor()

BA_API void ZipReader_constructor	(	ZipReader *	o,
		CspReader_Read	r,
		U32	zipFileSize
	)

Initialize a reader interface; no ZIP data is read yet.

Parameters

r	Required CspReader_Read callback, callable for the reader's lifetime.
zipFileSize	Complete archive length in bytes, representable in U32. The callback must support offset-based reads within that archive. Construction leaves the inherited validity marker unset; the implementation must call CspReader_setIsValid() after its backing data is ready.
o	Required reader storage.