Detailed Description

The I/O interface provides a common set of functions for working with files stored in various media types such as data stored on a standard file system, ZIP files, and network files.

Standard file system: DiskIo
ZIP files: ZipIo
Network file system: NetIo

The DiskIo, ZipIo, and NetIo are implementations for the abstract interface IoIntf, which is used by server objects such as HttpResRdr (Resource Reader), HttpResMgr (Web File Manager), and WebDAV.

An IoIntf instance provides common file operations such as iterating directories, reading files, and writing files.

An IoIntf can also be used by your application code and is not limited to web application code. The benefit of using an IoIntf is that it provides a common API for working with multiple media formats.

Use cases:

Configuration data can be stored and accessed in a ZIP file.
Firmware upgrades in embedded devices can be uploaded as ZIP files, mounted when uploaded, and extracted by the application.
The application can access remote data by using the NetIo.

Instances of the IoIntf such as DiskIo, ZipIo, and NetIo initialize the function pointers in the IoIntf.

I/O interfaces can be chained. For example, a ZIP file can be opened via a NetIo.

Example:
Application -> ZipIo -> NetIo client -> Network -> Web File Manager -> ZIP file.

In embedded devices without a file system, the ZipIo can be interfaced to ZIP files stored directly in read only memory – in other words, a file system is not needed. The directory examples/FileReader/ contains example code that shows how to interface a ZipIo to a ZIP file by using a standard file system. The example code can be changed to directly access data stored in read only memory.

DiskIo implementations are provided for multiple file systems in xrc/DiskIo. Choose the implementation for the target platform and consult its documented path, error, and filesystem limitations. A DiskIo is useful when resources must be read or updated on a writable filesystem. Applications stored in a ZipIo do not require DiskIo unless their backing archive or application data uses it.

Some of the functions in the IoIntf are optional. For example, a ZipIo does not implement the write function. The function pointer is NULL if the IoIntf implementation does not support the operation.

Here is a brief summary of the function pointer types found in IoIntf.h:

IoIntf_OpenDir: returns a directory iterator with the following methods:
- DirIntf_Read: iterate to the next resource.
- DirIntf_GetName: returns the resource name
- DirIntf_Stat: returns resource information such as size, date, etc.
IoIntf_CloseDir: closes a directory iterator.
IoIntf_Stat: returns resource information such as size, date, etc.
IoIntf_OpenRes: opens a file for reading or writing. Returns an object with the following methods:
IoIntf_OpenResGzip: Opens a file for reading in compressed mode. The ZipIo supports this method. Static HTML files, JavaScript files, etc. can be sent, via a HttpResRdr, in compressed format directly to a web browser that supports compression. The function pointer is NULL if the implementation does not support compression. The file xrc/zip/BaGzip.c is designed as a wrapper that can enable dynamic compression for media types such as a DiskIo, which does not support compressed files. The BaGzip file can be used by, for example, a WebDAV server to automatically compress files requested by the client.
ResIntf_Read: read data. Automatically un-compresses the data if the implementation is a ZipIo.
ResIntf_Write: writes data. Function pointer is NULL if not implemented.
ResIntf_Seek: file seek.
ResIntf_Flush: flush file.
ResIntf_Close: close file handle.
IoIntf_Property: set and get additional file or media properties. See below for detailed information.

The following methods are supported for media types that support 'write':

IoIntf_MkDir: Create directory.
IoIntf_Rename: Rename directory or file.
IoIntf_Remove: Remove (delete) file.
IoIntf_RmDir: Remove (delete) directory.

The IoIntf_Property function:

The property function allows additional properties to be fetched or set on a media and/or file. The implementation is media and platform dependent. Many of the properties can be accessed by using helper (wrapper) functions. See the IoIntf header file for more information.

The following properties are supported by all media types:

destructor: virtual destructor.
type: returns information about the media type such as "zip", "disk", etc.

The following optional properties are typically supported by all media types:

dupsize: returns the size needed for cloning the I/O.
dup: clone the I/O. The clone function is similar to a virtual constructor.

The ZipIo supports the following properties: pl, pp, aes. You do not directly access these properties using the property function. Instead the following helper (wrapper) functions are provided:

IoIntf_setPasswordProp
IoIntf_setPassword
IoIntf_isEncrypted

The following properties are supported by all DiskIo media types:

abs: returns the absolute (real) path to a resource.
movedir: indicates if the native file system allows moving directories with content.

The following property is supported by FAT like DiskIo media types:

hidden: set the file hidden attribute. Typically used by the WebDAV plugin.

Miscellaneous properties:

SeekAndRead: returns a function pointer if the IoIntf supports combined seek and read. See the header file for the SeekAndRead prototype. The method is used by IoIntfZipReader and IoIntfCspReader if supported. An I/O interface that releases the dispatcher mutex during read operations must implement this function. The NetIo implements this property.

Internationalization

All names are assumed to be either ASCII or UTF8. An IoIntf implementation may choose to store the names using wide characters. Such an implementation must translate the names from UTF8 to wide characters and vice versa. As an example, the Windows implementation of the DiskIo class translates to and from wide characters.

Collaboration diagram for IO related API's and implementation:

Modules
	Standard I/O functions
	The BaFile API specifies a number of standard I/O functions for working with files.

Classes
struct	DiskIo
	The DiskIo class makes it possible for the web server to work with resources on a hard drive. More...

struct	IoIntfCspReader
	The IoIntfCspReader, which implements the abstract CspReader interface, makes it possible to open a "CSP dat" file via a IoIntf. More...

struct	IoIntfZipReader
	The IoIntfZipReader, which implements the abstract ZipReader interface, makes it possible for a ZipIo to open a ZIP file via another IoInterface. More...

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

struct	ZipIo
	The ZipIo class makes it possible for the web server to work with resources in a ZIP file as if the ZIP file is a read-only file system. More...

struct	FileZipReader
	Example code that shows you how to write a ZipReader interface for the ZipIo class. More...

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

#define	ZipContainer_getECode(o) (o)->errCode

#define	ZipIo_getECode(o) (o)->ecode
	Query construction status without performing I/O. More...

Typedefs
typedef DiskIo	DiskIo
	The DiskIo class makes it possible for the web server to work with resources on a hard drive. More...

typedef IoIntfCspReader	IoIntfCspReader
	The IoIntfCspReader, which implements the abstract CspReader interface, makes it possible to open a "CSP dat" file via a IoIntf. More...

typedef IoIntfZipReader	IoIntfZipReader
	The IoIntfZipReader, which implements the abstract ZipReader interface, makes it possible for a ZipIo to open a ZIP file via another IoInterface. More...

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

typedef struct CentralDirIterator	CentralDirIterator
	Low level ZIP file central directory iterator. More...

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

typedef ZipIo	ZipIo
	The ZipIo class makes it possible for the web server to work with resources in a ZIP file as if the ZIP file is a read-only file system. More...

typedef FileZipReader	FileZipReader
	Example code that shows you how to write a ZipReader interface for the ZipIo class. 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. More...

Functions
BA_API void	DiskIo_constructor (DiskIo *o)
	Initialize the platform DiskIo implementation. More...

BA_API void	DiskIo_destructor (DiskIo *o)
	Release configuration after dependent users and open handles have stopped. More...

BA_API int	DiskIo_setRootDir (DiskIo o, const char root)
	Select the filesystem location exposed as this I/O interface's root. More...

BA_API int	DiskIo_getRootDir (DiskIo o, char buf, int len)
	Copy the configured root representation. More...

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

BA_API void	ZipIo_constructor (ZipIo o, ZipReader reader, size_t size, AllocatorIntf *alloc)
	ZipIo constructor. More...

BA_API void	ZipIo_destructor (ZipIo *o)
	Notify an attached IoIntf, free the index/buffer/password storage, and leave the borrowed ZipReader and allocator alive. More...

	DiskIo::DiskIo ()
	Create a DiskIo instance and set the root directory to '/'. More...

	DiskIo::~DiskIo ()
	Release the root configuration and notify an attached I/O interface. More...

int	DiskIo::setRootDir (const char *root)
	Select the filesystem location exposed as this I/O interface's root. More...

int	DiskIo::getRootDir (char *buf, int len)
	Copy the configured root representation. 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 ()

	ZipIo::ZipIo (ZipReader reader, size_t size=256, AllocatorIntf alloc=0)
	ZipIo constructor. More...

	ZipIo::~ZipIo ()
	Notify an attached IoIntf, free the index/buffer/password storage, and leave the borrowed ZipReader and allocator alive. More...

ZipErr	ZipIo::getECode ()
	Query construction status without performing I/O. More...

typedef ResIntfPtr(*	IoIntf_InflateGzip) (IoIntfPtr io, const char name, int status, const char **ecode)
	Open a destination that accepts gzip bytes and stores decompressed data. More...

typedef ResIntfPtr(*	IoIntf_DeflateGzip) (ResIntfPtr resPtr, const char name, ThreadMutex m, BaFileSize size, BaBool isCompressed)
	Optionally compress an open resource or range into temporary gzip storage. More...

typedef int(*	IoIntf_Property) (IoIntfPtr o, const char name, void a, void *b)
	Implementation-specific property operation. More...

typedef DirIntfPtr(*	IoIntf_OpenDir) (IoIntfPtr o, const char dirname, int status, const char **ecode)
	Open a directory iterator before its first entry. More...

typedef int(*	IoIntf_Stat) (IoIntfPtr o, const char name, IoStat st)
	Fetch metadata for a file or directory. More...

typedef ResIntfPtr(*	IoIntf_OpenRes) (IoIntfPtr o, const char name, U32 mode, int status, const char **ecode)
	Open a file for reading or writing. More...

typedef int(*	IoIntf_CloseDir) (IoIntfPtr o, DirIntfPtr *dirIntf)
	Consume and close a directory iterator. More...

typedef ResIntfPtr(*	IoIntf_OpenResGzip) (IoIntfPtr o, const char name, ThreadMutex m, BaFileSize size, int status, const char **ecode)
	Open a gzip representation for reading when supported. More...

typedef int(*	IoIntf_MkDir) (IoIntfPtr o, const char name, const char *ecode)
	Create a directory. More...

typedef int(*	IoIntf_Rename) (IoIntfPtr o, const char from, const char to, const char **ecode)
	Rename or move a resource within this filesystem. More...

typedef int(*	IoIntf_Remove) (IoIntfPtr o, const char name, const char *ecode)
	Remove a file. More...

typedef int(*	IoIntf_RmDir) (IoIntfPtr o, const char name, const char *ecode)
	Remove an empty directory. More...

typedef int(*	IoIntf_SeekAndRead) (ResIntfPtr super, BaFileSize offset, void buf, size_t maxSize, size_t size)
	Perform a combined seek and read on a resource. More...

typedef void(*	IoIntf_OnTerminate) (IoIntfPtr o, IoIntfPtr io)
	Notify a filesystem attachment of termination/replacement. More...

typedef struct IoIntf	IoIntf
	The IoIntf class specifies an abstract file API, implementations include ZipIo, DiskIo, and NetIo. More...

typedef int(*	DirIntf_Read) (DirIntfPtr o)
	Advance to the next directory entry, including the first after open. More...

typedef const char (	DirIntf_GetName) (DirIntfPtr o)
	Access the current entry name after successful readFp. More...

typedef int(*	DirIntf_Stat) (DirIntfPtr o, IoStat *st)
	Fetch metadata for the current entry after successful readFp. More...

typedef struct DirIntf	DirIntf
	Directory handle for a directory opened with IoIntf_OpenDir. More...

typedef int(*	ResIntf_Read) (ResIntfPtr o, void buf, size_t maxSize, size_t size)
	Read binary bytes at the current resource position. More...

typedef int(*	ResIntf_Write) (ResIntfPtr o, const void *buf, size_t size)
	Write binary bytes at the current resource position. More...

typedef int(*	ResIntf_Seek) (ResIntfPtr o, BaFileSize offset)
	Set the resource position relative to its beginning. More...

typedef int(*	ResIntf_Flush) (ResIntfPtr o)
	Flush buffered writes through the implementation. More...

typedef int(*	ResIntf_Close) (ResIntfPtr o)
	Close and consume a resource handle. More...

typedef struct ResIntf	ResIntf
	Resource handle for a file opened with IoIntf_OpenRes. More...

BA_API int	IoIntf_setPassword (IoIntfPtr o, const char *password, size_t passwordLen)
	wrapper for IoIntf_Property: 'pl'. More...

BA_API int	IoIntf_setPasswordProp (IoIntfPtr o, BaBool passwordRequired, BaBool passwordBin)
	wrapper for IoIntf_Property: 'pp'. More...

BA_API char *	IoIntf_getAbspath (IoIntfPtr o, const char *path)
	wrapper for IoIntf_Property: 'abs'. More...

BA_API int	IoIntf_getType (IoIntfPtr o, const char type, const char platform)
	Query the implementation's type property. More...

BA_API int	IoIntf_isEncrypted (IoIntfPtr o, const char name, BaBool isEncrypted)
	wrapper for IoIntf_Property: 'aes'. More...

BA_API void	IoIntf_destructor (IoIntfPtr o)
	Invoke the implementation's "destructor" property. More...

#define	IOINTF_OK 0
	Error codes (status) More...

#define	IOINTF_EOF 1
	End of file from ResIntf_Read. More...

#define	IOINTF_INVALIDNAME -11
	Invalid name or name not accepted by IOINTF implementation. More...

#define	IOINTF_NOTFOUND -12
	Resource not found. More...

#define	IOINTF_EXIST -13
	Resource exists and cannot be overwritten. More...

#define	IOINTF_ENOENT -14
	Path (parent directory) not found. More...

#define	IOINTF_NOACCESS -15
	No access or resource locked by file system. More...

#define	IOINTF_NOTEMPTY -16
	A directory resource is not empty. More...

#define	IOINTF_NOSPACE -17
	No space left on device. More...

#define	IOINTF_IOERROR -18
	Some kind of IO error. More...

#define	IOINTF_MEM -19
	Memory allocation error when working with resource. More...

#define	IOINTF_NOIMPLEMENTATION -50
	Method not implemented. More...

#define	IOINTF_BUFTOOSMALL -51
	The provided buffer is too small. More...

#define	IOINTF_NOZIPLIB -100
	IoIntf_OpenRes cannot uncompress the file since no NO_ZLIB is defined. More...

#define	IOINTF_NOTCOMPRESSED -101
	IoIntf_OpenResGzip is not willing to compress the data. More...

#define	IOINTF_ZIPERROR -102
	Error in compressed data. More...

#define	IOINTF_NOAESLIB -200
	Encrypted ZIP file requires AES, but AES is not enabled in ZipIo.c. More...

#define	IOINTF_AES_NO_SUPPORT -201
	Unknown AES encryption or not an AES encrypted ZIP file. More...

#define	IOINTF_NO_PASSWORD -202
	File is AES encrypted, but password was not entered. More...

#define	IOINTF_WRONG_PASSWORD -203
	Wrong password for AES encrypted file. More...

#define	IOINTF_AES_WRONG_AUTH -204
	Password does not match password in the file being accessed in the ZIP file. More...

#define	IOINTF_AES_COMPROMISED -205
	The file being accessed in the ZIP file is changed from an AES encrypted file to a non-encrypted file. More...

#define	OpenRes_READ 1
	Open resource read. More...

#define	OpenRes_WRITE 2
	Open resource write. More...

#define	OpenRes_APPEND 4
	Open resource and append. More...

#define	IoIntf_constructorRW(o, property, closeDir, mkDir, rename, openDir, openRes, openResGzip, rm, rmDir, st)
	Initialize an I/O interface with caller-supplied callbacks. More...

#define	IoIntf_constructorR(o, property, closeDir, openDir, openRes, openResGzip, st)
	Initialize an I/O interface with caller-supplied callbacks. More...

#define	DirIntf_constructor(o, read, getName, st)
	Install directory handle callbacks; no allocation or return value. More...

#define	ResIntf_constructor(o, read, write, seek, flush, close)
	Install resource handle callbacks; no allocation or return value. More...

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.

◆ DirIntf_constructor

#define DirIntf_constructor	(	o,
		read,
		getName,
		st
	)

Value:

  do {\
  (o)->readFp=read;\
  (o)->getNameFp=getName;\
  (o)->statFp=st;\
}while(0)

Install directory handle callbacks; no allocation or return value.

Parameters

o	Required initialized implementation storage.
read	Read callback; directory iteration or resource bytes respectively.
getName	Current-entry name callback.
st	Current-entry metadata callback. Callback storage and code must outlive the handle.

◆ IOINTF_AES_COMPROMISED

#define IOINTF_AES_COMPROMISED -205

The file being accessed in the ZIP file is changed from an AES encrypted file to a non-encrypted file.

Detection for this error is enabled by the 'passwordRequired' argument to function IoIntf_setPassword.

◆ IOINTF_AES_NO_SUPPORT

#define IOINTF_AES_NO_SUPPORT -201

Unknown AES encryption or not an AES encrypted ZIP file.

◆ IOINTF_AES_WRONG_AUTH

#define IOINTF_AES_WRONG_AUTH -204

Password does not match password in the file being accessed in the ZIP file.

The most likely cause is corrupted ZIP file or a compromised ZIP file.

◆ IOINTF_BUFTOOSMALL

#define IOINTF_BUFTOOSMALL -51

The provided buffer is too small.

◆ IoIntf_constructorR

#define IoIntf_constructorR	(	o,
		property,
		closeDir,
		openDir,
		openRes,
		openResGzip,
		st
	)

Value:

   do {\
   (o)->propertyFp=property;\
   (o)->closeDirFp=closeDir;\
   (o)->mkDirFp=0;\
   (o)->renameFp=0;\
   (o)->openDirFp=openDir;\
   (o)->openResFp=openRes;\
   (o)->openResGzipFp=openResGzip;\
   (o)->removeFp=0;\
   (o)->rmDirFp=0;\
   (o)->statFp=st;\
   (o)->attachedIo=0;\
   (o)->onTerminate=0;\
} while(0)

Initialize an I/O interface with caller-supplied callbacks.

Parameters

o	Required caller-owned IoIntf storage.
property	IoIntf_Property callback for implementation-specific properties.
closeDir	IoIntf_CloseDir callback that consumes directory handles.
openDir	IoIntf_OpenDir callback.
openRes	IoIntf_OpenRes callback.
openResGzip	IoIntf_OpenResGzip callback, or NULL when unsupported.
st	IoIntf_Stat callback. No allocation or return value. Callbacks must remain callable throughout the interface lifetime. Attachment fields are cleared. Write/directory modification callbacks are set to NULL.

◆ IoIntf_constructorRW

#define IoIntf_constructorRW	(	o,
		property,
		closeDir,
		mkDir,
		rename,
		openDir,
		openRes,
		openResGzip,
		rm,
		rmDir,
		st
	)

Value:

   do {\
   (o)->propertyFp=property;\
   (o)->closeDirFp=closeDir;\
   (o)->mkDirFp=mkDir;\
   (o)->renameFp=rename;\
   (o)->openDirFp=openDir;\
   (o)->openResFp=openRes;\
   (o)->openResGzipFp=openResGzip;\
   (o)->removeFp=rm;\
   (o)->rmDirFp=rmDir;\
   (o)->statFp=st;\
   (o)->attachedIo=0;\
   (o)->onTerminate=0;\
} while(0)

Initialize an I/O interface with caller-supplied callbacks.

Parameters

o	Required caller-owned IoIntf storage.
property	IoIntf_Property callback for implementation-specific properties.
closeDir	IoIntf_CloseDir callback that consumes directory handles.
mkDir	IoIntf_MkDir callback, or NULL when unsupported.
rename	IoIntf_Rename callback, or NULL when unsupported.
openDir	IoIntf_OpenDir callback.
openRes	IoIntf_OpenRes callback.
openResGzip	IoIntf_OpenResGzip callback, or NULL when unsupported.
rm	IoIntf_Remove callback, or NULL when unsupported.
rmDir	IoIntf_RmDir callback, or NULL when unsupported.
st	IoIntf_Stat callback. No allocation or return value. Callbacks must remain callable throughout the interface lifetime. Attachment fields are cleared.

◆ IOINTF_ENOENT

#define IOINTF_ENOENT -14

Path (parent directory) not found.

◆ IOINTF_EOF

#define IOINTF_EOF 1

End of file from ResIntf_Read.

◆ IOINTF_EXIST

#define IOINTF_EXIST -13

Resource exists and cannot be overwritten.

◆ IOINTF_INVALIDNAME

#define IOINTF_INVALIDNAME -11

Invalid name or name not accepted by IOINTF implementation.

A DOS 8.3 file system may return this code for long file names.

◆ IOINTF_IOERROR

#define IOINTF_IOERROR -18

Some kind of IO error.

The extra error code may contain more information.

◆ IOINTF_MEM

#define IOINTF_MEM -19

Memory allocation error when working with resource.

◆ IOINTF_NO_PASSWORD

#define IOINTF_NO_PASSWORD -202

File is AES encrypted, but password was not entered.

◆ IOINTF_NOACCESS

#define IOINTF_NOACCESS -15

No access or resource locked by file system.

◆ IOINTF_NOAESLIB

#define IOINTF_NOAESLIB -200

Encrypted ZIP file requires AES, but AES is not enabled in ZipIo.c.

Recompile without NO_SHARKSSL.

◆ IOINTF_NOIMPLEMENTATION

#define IOINTF_NOIMPLEMENTATION -50

Method not implemented.

◆ IOINTF_NOSPACE

#define IOINTF_NOSPACE -17

No space left on device.

◆ IOINTF_NOTCOMPRESSED

#define IOINTF_NOTCOMPRESSED -101

IoIntf_OpenResGzip is not willing to compress the data.

This informs the caller that IoIntf_OpenRes must be used instead.

◆ IOINTF_NOTEMPTY

#define IOINTF_NOTEMPTY -16

A directory resource is not empty.

◆ IOINTF_NOTFOUND

#define IOINTF_NOTFOUND -12

Resource not found.

◆ IOINTF_NOZIPLIB

#define IOINTF_NOZIPLIB -100

IoIntf_OpenRes cannot uncompress the file since no NO_ZLIB is defined.

◆ IOINTF_OK

#define IOINTF_OK 0

Error codes (status)

◆ IOINTF_WRONG_PASSWORD

#define IOINTF_WRONG_PASSWORD -203

Wrong password for AES encrypted file.

◆ IOINTF_ZIPERROR

#define IOINTF_ZIPERROR -102

Error in compressed data.

◆ OpenRes_APPEND

#define OpenRes_APPEND 4

Open resource and append.

Default is to truncate

◆ OpenRes_READ

#define OpenRes_READ 1

Open resource read.

◆ OpenRes_WRITE

#define OpenRes_WRITE 2

Open resource write.

◆ ResIntf_constructor

#define ResIntf_constructor	(	o,
		read,
		write,
		seek,
		flush,
		close
	)

Value:

  do {\
  (o)->readFp=read;\
  (o)->writeFp=write;\
  (o)->seekFp=seek;\
  (o)->flushFp=flush;\
  (o)->closeFp=close;\
}while(0)

Install resource handle callbacks; no allocation or return value.

Parameters

o	Required initialized implementation storage.
read	Read callback; directory iteration or resource bytes respectively.
write	Write callback, or NULL for a read-only resource.
seek	Seek callback, or NULL when unsupported.
flush	Flush callback, or NULL when unsupported.
close	Required close callback that releases the handle. Callback storage and code must outlive the handle.

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

◆ ZipIo_getECode

#define ZipIo_getECode ( o ) (o)->ecode

Query construction status without performing I/O.

Returns: ZipErr_NoError on success, or a ZipErr failure. ZipErr_Buf also represents allocation failures while constructing the buffer/index.

Parameters

o	Required initialized filesystem.

Typedef Documentation

◆ CentralDirIterator

typedef struct CentralDirIterator CentralDirIterator

Low level ZIP file central directory iterator.

◆ DirIntf

typedef struct DirIntf DirIntf

Directory handle for a directory opened with IoIntf_OpenDir.

Example:

int status;
DirIntfPtr dir = io->openDirFp(io, relPath, &status, 0);
if(dir)
{
   while((status = dir->readFp(dir)) == 0)
   {
      IoStat st;
      const char* name = dir->getNameFp(dir);
      int statStatus = dir->statFp(dir, &st);
      if(statStatus == 0)
      {
         // Process name/st here before advancing the iterator.
      }
   }
   // IOINTF_NOTFOUND is normal end-of-directory; other values are errors.
   int closeStatus = io->closeDirFp(io, &dir);
   // Handle closeStatus; dir has been consumed even if closing failed.
}

See also: IoIntf

◆ DirIntf_GetName

typedef const char *(* DirIntf_GetName) (DirIntfPtr o)

Access the current entry name after successful readFp.

Parameters

o	Required live iterator positioned on an entry.

Returns: Borrowed NUL-terminated entry name, valid until advance or close. Copy it if needed later; behavior outside a valid entry is not portable.

◆ DirIntf_Read

typedef int(* DirIntf_Read) (DirIntfPtr o)

Advance to the next directory entry, including the first after open.

Parameters

o	Required live iterator.

Returns: Zero when an entry is available, IOINTF_NOTFOUND at the end, or another nonzero I/O status on failure. Stop after a nonzero result. Ordering and whether special dot entries are exposed depend on the implementation.

◆ DirIntf_Stat

typedef int(* DirIntf_Stat) (DirIntfPtr o, IoStat *st)

Fetch metadata for the current entry after successful readFp.

Parameters

o	Required live iterator positioned on an entry.
st	Required output record, valid only on success.

Returns: Zero on success, nonzero I/O status on failure.

◆ DiskIo

typedef DiskIo DiskIo

The DiskIo class makes it possible for the web server to work with resources on a hard drive.

A directory separator is always '/'. DOS based file systems that cannot handle forward slash must internally convert to and from '/'.

A DiskIo instance can directly work on the root of the file system, but it is more common to give the DiskIo instance an offset value. The offset value is set with method DiskIo::setRootDir

Root syntax and default roots are platform-specific. Desktop ports accept absolute paths and selected relative paths; embedded ports may require a mounted volume or a platform-specific prefix. See xrc/DiskIo for the port selected by the build. Call setRootDir explicitly before serving files.

This generic interface does not mount media, enforce filesystem permissions, or replace the platform's path and symbolic-link rules. Stop dependent readers and serialize operations before changing its root or destroying it.

◆ FileZipReader

typedef FileZipReader FileZipReader

Example code that shows you how to write a ZipReader interface for the ZipIo class.

This example code shows you how to write a ZipReader driver object. The ZipIo class uses the ZipReader driver object when reading Zip-data from a Zip-File. See class ZipIo for more information.

This example code uses the file system for reading the Zip-File. The constructor opens the Zip-File and method "diskRead", see code, uses the Posix function fseek for setting the file pointer to the requested offset position and function fread for reading the actual data.

◆ IoIntf

typedef struct IoIntf IoIntf

The IoIntf class specifies an abstract file API, implementations include ZipIo, DiskIo, and NetIo.

References:

See also: IoIntf.h (Detailed information about the IoIntf methods and the arguments).; DirIntf (Iterate directories)

◆ IoIntf_CloseDir

typedef int(* IoIntf_CloseDir) (IoIntfPtr o, DirIntfPtr *dirIntf)

Consume and close a directory iterator.

Parameters

o	Required filesystem that opened the iterator.
dirIntf	Required pointer to a live non-NULL iterator. On completion the implementation releases it and clears the caller's pointer.

Returns: Zero on success or nonzero I/O status. Do not retry using a consumed handle; NULL-handle acceptance is not portable across implementations.

◆ IoIntf_DeflateGzip

typedef ResIntfPtr(* IoIntf_DeflateGzip) (ResIntfPtr resPtr, const char *name, ThreadMutex *m, BaFileSize *size, BaBool *isCompressed)

Optionally compress an open resource or range into temporary gzip storage.

Parameters

resPtr	Required readable resource at the start of the desired input.
name	Required NUL-terminated resource name used for compression policy.
m	Optional caller-owned, already-locked mutex, released/reacquired while producing temporary data.
size	Required input/output byte count: input amount selected by the caller, output gzip size when compressed. The adapter applies its size policy.
isCompressed	Required output: TRUE when compression was selected, FALSE when declined. TRUE alone does not indicate successful compression.

Returns: Original resource unchanged when declined, a new readable resource when compressed, or NULL on failure. Once compression is selected, the adapter closes resPtr even on failure. Close only the returned non-NULL resource.

◆ IoIntf_InflateGzip

typedef ResIntfPtr(* IoIntf_InflateGzip) (IoIntfPtr io, const char *name, int *status, const char **ecode)

Open a destination that accepts gzip bytes and stores decompressed data.

Parameters

io	Required writable filesystem, borrowed until the resource is closed.
name	Required NUL-terminated destination path, used during opening.
status	Required I/O status output.
ecode	Optional output for a borrowed implementation error string.

Returns: Owned writable resource, or NULL on failure. Check write and close results for gzip/data errors. Opening may create or truncate the destination. Supplied by the optional BaGzip adapter.

◆ IoIntf_MkDir

typedef int(* IoIntf_MkDir) (IoIntfPtr o, const char *name, const char **ecode)

Create a directory.

Parameters

o	Required initialized filesystem.
name	Required borrowed NUL-terminated path relative to this filesystem.
ecode	Optional output for a borrowed implementation error string; NULL omits it. Copy if needed beyond the operation and do not assume it is set.

Returns: Zero on success, nonzero I/O status on failure. Missing operations are represented by NULL function pointers on read-only filesystems.

◆ IoIntf_OnTerminate

typedef void(* IoIntf_OnTerminate) (IoIntfPtr o, IoIntfPtr io)

Notify a filesystem attachment of termination/replacement.

Parameters

o	Borrowed attached interface supplied by the "attach" property.
io	Filesystem delivering the notification. Its storage is still present during this callback but must not be retained for later use. No return value or ownership transfer is implied by the callback itself.

◆ IoIntf_OpenDir

typedef DirIntfPtr(* IoIntf_OpenDir) (IoIntfPtr o, const char *dirname, int *status, const char **ecode)

Open a directory iterator before its first entry.

Parameters

o	Required initialized filesystem.
dirname	Required borrowed NUL-terminated directory path.
status	Required output receiving zero on success or an I/O error.
ecode	Optional output for a borrowed implementation error string; NULL omits it. Copy if needed beyond the operation and do not assume it is set.

Returns: Owned iterator on success, NULL on failure. Advance with readFp before accessing an entry; close it through this filesystem's closeDirFp. Keep the filesystem alive until the iterator is closed.

◆ IoIntf_OpenRes

typedef ResIntfPtr(* IoIntf_OpenRes) (IoIntfPtr o, const char *name, U32 mode, int *status, const char **ecode)

Open a file for reading or writing.

The following compares POSIX mode with IoIntf mode flags. Note: Only the two first modes are guaranteed to work on all DiskIos Note2: The ZipIo only supports OpenRes_READ. +----------—+----------------------------------------------—+ | POSIX mode | IoIntf flags | +----------—+----------------------------------------------—+ | r | OpenRes_READ | +----------—+----------------------------------------------—+ | w | OpenRes_WRITE | +----------—+----------------------------------------------—+ | a | OpenRes_WRITE | OpenRes_APPEND | +----------—+----------------------------------------------—+ | w+ | OpenRes_READ | OpenRes_WRITE | +----------—+----------------------------------------------—+ | a+ | OpenRes_READ | OpenRes_WRITE | OpenRes_APPEND | +----------—+----------------------------------------------—+

Parameters

o	Required initialized filesystem.
name	Required borrowed NUL-terminated path relative to this filesystem.
mode	OpenRes_READ, OpenRes_WRITE, or a supported combination with OpenRes_APPEND. Query the implementation before relying on combined modes.
status	Required output receiving zero on success or an I/O error.
ecode	Optional output for a borrowed implementation error string; NULL omits it. Copy if needed beyond the operation and do not assume it is set.

Returns: Owned resource handle on success, NULL on failure. Close through its closeFp and keep the filesystem alive until all handles are closed. Check optional resource function pointers before calling them.

◆ IoIntf_OpenResGzip

typedef ResIntfPtr(* IoIntf_OpenResGzip) (IoIntfPtr o, const char *name, ThreadMutex *m, BaFileSize *size, int *status, const char **ecode)

Open a gzip representation for reading when supported.

Parameters

o	Required initialized filesystem.
name	Required borrowed NUL-terminated path relative to this filesystem.
m	Optional mutex already held by the caller. A compressing adapter may release it during work and reacquire it before returning.
size	Required input/output byte count: supply the original file size; on success receives the gzip representation size including framing.
status	Required I/O status output. IOINTF_NOTCOMPRESSED indicates that the implementation declines compression; opening can also fail for other reasons.
ecode	Optional output for a borrowed implementation error string; NULL omits it. Copy if needed beyond the operation and do not assume it is set.

Returns: Owned readable resource, or NULL on failure/declined compression. Always test the pointer; close a returned resource through closeFp.

◆ IoIntf_Property

typedef int(* IoIntf_Property) (IoIntfPtr o, const char *name, void *a, void *b)

Implementation-specific property operation.

Parameters

o	Required initialized filesystem.
name	Required NUL-terminated property name, borrowed for the call.
a	Property-specific pointer/value; see the contracts below.
b	Property-specific pointer/value, or NULL where unused/optional.

Returns: Zero when handled successfully, nonzero if unsupported or failed. Do not assume output arguments are initialized on failure.

Common properties:

"type": a is required const char** output; b is optional const char** platform output. Returned strings are borrowed.
"movedir": a is required U32* output, TRUE/FALSE for moving directories.
"hidden": a is a borrowed resource-name string; b is required U32* input, TRUE to set the hidden flag or FALSE to clear it.
"abs": a is a borrowed path string; b is char** output for a baFree-owned absolute path. Prefer IoIntf_getAbspath().
"destructor": a and b are NULL. Prefer IoIntf_destructor().
"SeekAndRead": a is IoIntf_SeekAndRead* output; b is unused.
"attach": a is a borrowed attached IoIntf; b points to an IoIntf_OnTerminate callback to copy. a=NULL detaches. Implementations may notify the previous attachment when replacing it. ZIP password/encryption properties have typed wrappers: IoIntf_setPassword(), IoIntf_setPasswordProp(), and IoIntf_isEncrypted(). Availability depends on the implementation; do not call optional operations through NULL pointers.

◆ IoIntf_Remove

typedef int(* IoIntf_Remove) (IoIntfPtr o, const char *name, const char **ecode)

Remove a file.

Parameters

o	Required initialized filesystem.
name	Required borrowed NUL-terminated path relative to this filesystem.
ecode	Optional output for a borrowed implementation error string; NULL omits it. Copy if needed beyond the operation and do not assume it is set.

Returns: Zero on success, nonzero I/O status on failure. Missing operations are represented by NULL function pointers on read-only filesystems.

◆ IoIntf_Rename

typedef int(* IoIntf_Rename) (IoIntfPtr o, const char *from, const char *to, const char **ecode)

Rename or move a resource within this filesystem.

Parameters

o	Required initialized writable filesystem.
from	Required borrowed NUL-terminated existing path.
to	Required borrowed NUL-terminated destination path.
ecode	Optional output for a borrowed implementation error string; NULL omits it. Copy if needed beyond the operation and do not assume it is set.

Returns: Zero on success, nonzero I/O status on failure. Replacement and nonempty-directory move behavior are implementation-specific; check "movedir".

◆ IoIntf_RmDir

typedef int(* IoIntf_RmDir) (IoIntfPtr o, const char *name, const char **ecode)

Remove an empty directory.

Parameters

o	Required initialized filesystem.
name	Required borrowed NUL-terminated path relative to this filesystem.
ecode	Optional output for a borrowed implementation error string; NULL omits it. Copy if needed beyond the operation and do not assume it is set.

Returns: Zero on success, nonzero I/O status on failure. Missing operations are represented by NULL function pointers on read-only filesystems.

◆ IoIntf_SeekAndRead

typedef int(* IoIntf_SeekAndRead) (ResIntfPtr super, BaFileSize offset, void *buf, size_t maxSize, size_t *size)

Perform a combined seek and read on a resource.

Parameters

super	Required live resource belonging to the implementation.
offset	Absolute byte position from the beginning of the resource.
buf	Required writable buffer for maxSize bytes.
maxSize	Positive maximum byte count.
size	Required output for the number of bytes read.

Returns: ResIntf_Read-style status and count. This combined operation is needed by readers whose I/O releases the dispatcher mutex between operations; obtain it through the filesystem's "SeekAndRead" property.

◆ IoIntf_Stat

typedef int(* IoIntf_Stat) (IoIntfPtr o, const char *name, IoStat *st)

Fetch metadata for a file or directory.

Parameters

o	Required initialized filesystem.
name	Required borrowed NUL-terminated path relative to this filesystem.
st	Required writable output record, valid only on success.

Returns: Zero on success, nonzero I/O status on failure.

◆ IoIntfCspReader

typedef IoIntfCspReader IoIntfCspReader

The IoIntfCspReader, which implements the abstract CspReader interface, makes it possible to open a "CSP dat" file via a IoIntf.

◆ IoIntfZipReader

typedef IoIntfZipReader IoIntfZipReader

The IoIntfZipReader, which implements the abstract ZipReader interface, makes it possible for a ZipIo to open a ZIP file via another IoInterface.

◆ ResIntf

typedef struct ResIntf ResIntf

Resource handle for a file opened with IoIntf_OpenRes.

◆ ResIntf_Close

typedef int(* ResIntf_Close) (ResIntfPtr o)

Close and consume a resource handle.

Parameters

o	Required live resource. Its storage is released by this call.

Returns: Zero on success, nonzero I/O status if finalization/close fails. The handle is no longer usable even on failure; do not retry close.

◆ ResIntf_Flush

typedef int(* ResIntf_Flush) (ResIntfPtr o)

Flush buffered writes through the implementation.

Parameters

o	Required live resource supporting flush.

Returns: Zero on success, nonzero I/O status on failure. Success is not a portable guarantee of physical-media durability.

◆ ResIntf_Read

typedef int(* ResIntf_Read) (ResIntfPtr o, void *buf, size_t maxSize, size_t *size)

Read binary bytes at the current resource position.

Parameters

o	Required live resource supporting reads.
buf	Required writable buffer for maxSize bytes.
maxSize	Positive capacity in bytes; zero-size behavior is not portable.
size	Required output receiving the byte count, no greater than maxSize.

Returns: Zero for a successful read, IOINTF_EOF for end-of-file, or another nonzero I/O status. A successful read can be short or have zero bytes depending on the implementation. Inspect both status and count; no NUL is appended. A failure may leave partial bytes/count, whose availability is implementation-specific.

◆ ResIntf_Seek

typedef int(* ResIntf_Seek) (ResIntfPtr o, BaFileSize offset)

Set the resource position relative to its beginning.

Parameters

o	Required live resource supporting seek.
offset	Nonnegative absolute byte offset. Supported range and seeking beyond the current end depend on the implementation.

Returns: Zero on success, nonzero I/O status on failure.

◆ ResIntf_Write

typedef int(* ResIntf_Write) (ResIntfPtr o, const void *buf, size_t size)

Write binary bytes at the current resource position.

Parameters

o	Required live resource supporting writes.
buf	Readable buffer, required when size is positive.
size	Number of bytes to write.

Returns: Zero for a complete write, nonzero I/O status on failure. No partial count is returned; failure may already have changed the file.

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

◆ ZipFileInfo

typedef struct ZipFileInfo ZipFileInfo

Low level ZIP file information used internally by the Zip File System.

◆ ZipIo

typedef ZipIo ZipIo

The ZipIo class makes it possible for the web server to work with resources in a ZIP file as if the ZIP file is a read-only file system.

The most common archive format, ZIP-File, is an "archive" that can contain one or more files. Usually the files "archived" in a ZIP-File are compressed to save space.

A ZIP-File contains a central repository, which stores the original directory structure that was archived. You can think of the central repository as a "read only" file system. The ZipIo class can decode and interpret the central repository in a ZIP-File.

The ZipIo class can automatically convert the internal ZIP data to a GZIP file without using an uncompressing library. Many browsers support the GZIP format and a file inside a ZIP-File can easily be transformed into a GZIP file.

An HTTP resource reader can use ZipIo's gzip resource interface to wrap deflated entries in gzip framing when the client accepts gzip. ZipIo itself provides file access; it does not send HTTP responses.

A decompression library is needed to read deflated entries as ordinary uncompressed bytes, including through HttpResponse::include. See Server Side Include files in the user manual for more information.

It is possible to create a non compressed ZIP file, which can be used without the aforementioned restrictions. A non compressed ZIP file is created by running: zip -0 args. See ZIP man page for more info. On windows, open a bash shell (Cygwin) and type one of:
info zip
zip -h

Directory and file names in the ZIP file must be stored as ASCII or UTF8.

A ZIP-File can be made plug-able; that is, you can add and remove a Zip-File from the virtual file system. The ZIP-File uses a ZipReader class, which inherits from CspReader, as the interface to the Zip-File. The example directory contains the FileZipReader which is an example implementation of a ZipReader.

◆ 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

◆ ZipComprMethod

enum ZipComprMethod

ZIP compression-method identifiers used in entry metadata.

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

◆ DiskIo()

DiskIo::DiskIo ( )

Create a DiskIo instance and set the root directory to '/'.

The meaning of '/' depends on the implementation. As an example, the Windows version of DiskIo interprets '/' as the root of everything and the C: drive will therefore be /c/. Please see the documentation in the example implementations for more information.

◆ DiskIo_constructor()

BA_API void DiskIo_constructor ( DiskIo * o )

Initialize the platform DiskIo implementation.

Parameters

[out] o Caller-owned instance; explicitly set its root before use.

See also: DiskIo::DiskIo

◆ DiskIo_destructor()

BA_API void DiskIo_destructor ( DiskIo * o )

Release configuration after dependent users and open handles have stopped.

Parameters

[in,out] o Initialized instance. Does not free o or unmount media.

See also: DiskIo::~DiskIo

◆ DiskIo_getRootDir()

BA_API int DiskIo_getRootDir	(	DiskIo *	o,
		char *	buf,
		int	len
	)

Copy the configured root representation.

Parameters

[out]	buf	Caller-owned writable buffer. On success it contains a NUL-terminated UTF-8 path, which may include a trailing slash.
[in]	len	Positive capacity in bytes, including the terminator. Allocate enough for the entire path plus NUL; do not use this function as a size query. Some ports do not check the terminator byte correctly.

Returns: Nonnegative on success, -1 on insufficient storage or conversion failure. Most ports return strlen(buf); HCC_UNICODE returns zero for a converted configured root. Use strlen(buf) when the length is needed. Output is unspecified on failure. This reports configuration, not filesystem existence or a universally canonical absolute path.

Parameters

[in] o Initialized instance with a valid root configuration.

◆ DiskIo_setRootDir()

BA_API int DiskIo_setRootDir	(	DiskIo *	o,
		const char *	root
	)

Select the filesystem location exposed as this I/O interface's root.

Parameters

[in] root NUL-terminated UTF-8 path using forward slashes. The path is copied. Accepted prefixes, relative paths, NULL, and empty strings vary by port; use an explicit valid path for portable code.

Returns: Zero on success, nonzero platform/I/O status on failure. Success does not universally verify that the directory exists. A failed change need not preserve the previous root. Stop using the instance until a valid root has been established again.

Parameters

[in,out] o Initialized instance, not concurrently in use.

◆ getECode() [1/3]

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/3]

ZipErr ZipContainer::getECode ( )

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

◆ getECode() [3/3]

ZipErr ZipIo::getECode ( )

Query construction status without performing I/O.

Returns: ZipErr_NoError on success, or a ZipErr failure. ZipErr_Buf also represents allocation failures while constructing the buffer/index.

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

◆ getRootDir()

int DiskIo::getRootDir	(	char *	buf,
		int	len
	)

Copy the configured root representation.

Parameters

[out]	buf	Caller-owned writable buffer. On success it contains a NUL-terminated UTF-8 path, which may include a trailing slash.
[in]	len	Positive capacity in bytes, including the terminator. Allocate enough for the entire path plus NUL; do not use this function as a size query. Some ports do not check the terminator byte correctly.

Returns: Nonnegative on success, -1 on insufficient storage or conversion failure. Most ports return strlen(buf); HCC_UNICODE returns zero for a converted configured root. Use strlen(buf) when the length is needed. Output is unspecified on failure. This reports configuration, not filesystem existence or a universally canonical absolute path.

◆ IoIntf_destructor()

BA_API void IoIntf_destructor ( IoIntfPtr o )

Invoke the implementation's "destructor" property.

Parameters

o	Required initialized filesystem implementing that property. Close resources/iterators and detach all users first. Implementation-owned storage is released; the caller still owns the IoIntf object itself. There is no error return; debug builds assert that the property succeeds.

◆ IoIntf_getAbspath()

BA_API char * IoIntf_getAbspath	(	IoIntfPtr	o,
		const char *	path
	)

wrapper for IoIntf_Property: 'abs'.

Returns the physical absolute path for argument 'path' if the underlying IoIntf implementation is a DiskIo.

Parameters

o	a pointer to the IoIntf implementation.
path	the path to convert.

Returns: the absolute path. The method returns NULL if the operation is not supported or if an error occurs. The returned pointer must be released by using baFree.

◆ IoIntf_getType()

BA_API int IoIntf_getType	(	IoIntfPtr	o,
		const char **	type,
		const char **	platform
	)

Query the implementation's type property.

Parameters

o	Required initialized filesystem with propertyFp.
type	Required output pointer for a borrowed NUL-terminated type string, such as "disk" or "zip". Do not free the returned string.
platform	Optional output pointer for a borrowed platform string; may equal the type where no separate platform is reported. NULL omits it.

Returns: Zero on success, nonzero if unsupported or failed. Outputs are valid only on success and should be copied before filesystem destruction.

◆ IoIntf_isEncrypted()

BA_API int IoIntf_isEncrypted	(	IoIntfPtr	o,
		const char *	name,
		BaBool *	isEncrypted
	)

wrapper for IoIntf_Property: 'aes'.

Parameters

o	a pointer to the IoIntf implementation.
name	the file name.
isEncrypted	Required output pointer receiving TRUE or FALSE on success.

Returns: Zero when the encryption flag was obtained. Nonzero when unsupported, not found, or another error occurs; do not use the output then.

◆ IoIntf_setPassword()

BA_API int IoIntf_setPassword	(	IoIntfPtr	o,
		const char *	password,
		size_t	passwordLen
	)

wrapper for IoIntf_Property: 'pl'.

Parameters

o	a pointer to the IoIntf implementation.
password	the required password for accessing the resources. ZipIo copies it; it must be non-NULL.
passwordLen	the length of the password (in bytes), can be zero when the password is ASCII format, and in this case, the length is calculated with strlen. ZipIo stores this length in U16, so keep the actual password at most 65535 bytes.

Returns: Zero when handled, nonzero if unsupported or failed. The current ZipIo text-password path does not report its copy-allocation failure.

◆ IoIntf_setPasswordProp()

BA_API int IoIntf_setPasswordProp	(	IoIntfPtr	o,
		BaBool	passwordRequired,
		BaBool	passwordBin
	)

wrapper for IoIntf_Property: 'pp'.

Parameters

o	a pointer to the IoIntf implementation.
passwordRequired	Set to TRUE if a password must be set on all files in the ZIP file. This prevents a hacker from replacing a password protected file with a non password protected file.
passwordBin	Set to TRUE if the password is binary; it will be translated to an ASCII string.

Returns: 0 on success or a non zero value if setting password properties not implemented by the IoIntf implementation.

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

◆ setRootDir()

int DiskIo::setRootDir ( const char * root )

Select the filesystem location exposed as this I/O interface's root.

Parameters

[in] root NUL-terminated UTF-8 path using forward slashes. The path is copied. Accepted prefixes, relative paths, NULL, and empty strings vary by port; use an explicit valid path for portable code.

Returns: Zero on success, nonzero platform/I/O status on failure. Success does not universally verify that the directory exists. A failed change need not preserve the previous root. Stop using the instance until a valid root has been established again.

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

◆ ZipIo()

ZipIo::ZipIo	(	ZipReader *	reader,
		size_t	size = `256`,
		AllocatorIntf *	alloc = `0`
	)

ZipIo constructor.

Example

extern "C" ZipReader* getHtmlZipReader(void);
.
.
ZipIo io(getHtmlZipReader());

Function getHtmlZipReader in the above example is auto generated by using bin2c and the -z flag.

Parameters

reader	Required valid borrowed ZipReader. Keep the reader and archive alive and unchanged until all open resources and this ZipIo have been destroyed.
size	Working-buffer capacity in bytes, coerced to at least 256. It must accommodate ZIP entry metadata and the archive's end-of-directory search; long names, extra fields, or archive comments can require more. Use a capacity representable in U32, as required by ZipContainer.
alloc	Borrowed allocator for working storage and the directory index; NULL selects AllocatorIntf_getDefault(). Keep it alive through destruction. Construction scans the archive and allocates an index. Check getECode() before using the filesystem. ZIP64 and split/spanned archives are not supported by this 32-bit ZIP metadata interface. Close open resources and iterators before cleanup.

◆ ZipIo_constructor()

BA_API void ZipIo_constructor	(	ZipIo *	o,
		ZipReader *	reader,
		size_t	size,
		AllocatorIntf *	alloc
	)

ZipIo constructor.

Example

extern "C" ZipReader* getHtmlZipReader(void);
.
.
ZipIo io(getHtmlZipReader());

Function getHtmlZipReader in the above example is auto generated by using bin2c and the -z flag.

Parameters

reader	Required valid borrowed ZipReader. Keep the reader and archive alive and unchanged until all open resources and this ZipIo have been destroyed.
size	Working-buffer capacity in bytes, coerced to at least 256. It must accommodate ZIP entry metadata and the archive's end-of-directory search; long names, extra fields, or archive comments can require more. Use a capacity representable in U32, as required by ZipContainer.
alloc	Borrowed allocator for working storage and the directory index; NULL selects AllocatorIntf_getDefault(). Keep it alive through destruction. Construction scans the archive and allocates an index. Check getECode() before using the filesystem. ZIP64 and split/spanned archives are not supported by this 32-bit ZIP metadata interface. Close open resources and iterators before cleanup.
o	Required storage to initialize.

◆ ZipIo_destructor()

BA_API void ZipIo_destructor ( ZipIo * o )

Notify an attached IoIntf, free the index/buffer/password storage, and leave the borrowed ZipReader and allocator alive.

No open resource or directory iterator may still use this ZipIo.

Parameters

o	Required initialized filesystem.

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

◆ ~DiskIo()

DiskIo::~DiskIo ( )

Release the root configuration and notify an attached I/O interface.

Close resources and directory iterators, and stop dependent users, before destruction. Does not unmount media or free this object.

◆ ~ZipIo()

ZipIo::~ZipIo ( )

Notify an attached IoIntf, free the index/buffer/password storage, and leave the borrowed ZipReader and allocator alive.

No open resource or directory iterator may still use this ZipIo.

Detailed Description

Internationalization

Modules

Classes

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ CentralDirIterator_getECode

◆ DirIntf_constructor

◆ IOINTF_AES_COMPROMISED

◆ IOINTF_AES_NO_SUPPORT

◆ IOINTF_AES_WRONG_AUTH

◆ IOINTF_BUFTOOSMALL

◆ IoIntf_constructorR

◆ IoIntf_constructorRW

◆ IOINTF_ENOENT

◆ IOINTF_EOF

◆ IOINTF_EXIST

◆ IOINTF_INVALIDNAME

◆ IOINTF_IOERROR

◆ IOINTF_MEM

◆ IOINTF_NO_PASSWORD

◆ IOINTF_NOACCESS

◆ IOINTF_NOAESLIB

◆ IOINTF_NOIMPLEMENTATION

◆ IOINTF_NOSPACE

◆ IOINTF_NOTCOMPRESSED

◆ IOINTF_NOTEMPTY

◆ IOINTF_NOTFOUND

◆ IOINTF_NOZIPLIB

◆ IOINTF_OK

◆ IOINTF_WRONG_PASSWORD

◆ IOINTF_ZIPERROR

◆ OpenRes_APPEND

◆ OpenRes_READ

◆ OpenRes_WRITE

◆ ResIntf_constructor

◆ ZipContainer_getECode

◆ ZipIo_getECode

Typedef Documentation

◆ CentralDirIterator

◆ DirIntf

◆ DirIntf_GetName

◆ DirIntf_Read

◆ DirIntf_Stat

◆ DiskIo

◆ FileZipReader

◆ IoIntf

References:

◆ IoIntf_CloseDir

◆ IoIntf_DeflateGzip

◆ IoIntf_InflateGzip

◆ IoIntf_MkDir

◆ IoIntf_OnTerminate

◆ IoIntf_OpenDir

◆ IoIntf_OpenRes

◆ IoIntf_OpenResGzip

◆ IoIntf_Property

◆ IoIntf_Remove

◆ IoIntf_Rename

◆ IoIntf_RmDir

◆ IoIntf_SeekAndRead

◆ IoIntf_Stat

◆ IoIntfCspReader

◆ IoIntfZipReader

◆ ResIntf

◆ ResIntf_Close

◆ ResIntf_Flush

◆ ResIntf_Read

◆ ResIntf_Seek

◆ ResIntf_Write

◆ ZipContainer

◆ ZipFileInfo

◆ ZipIo

◆ ZipReader

Enumeration Type Documentation

◆ ZipComprMethod

◆ ZipErr