Barracuda Application Server C/C++ Reference
IO related API's and implementation

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

Collaboration diagram for IO related API's and implementation:

Modules

 Standard I/O functions
 

Classes

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  DiskIo
 The DiskIo class makes it possible for the web-server to work with resources on a hard drive. 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  IoIntfCspReader
 The IoIntfCspReader, which implements the abstract CspReader interface, makes it possible to open a "CSP dat" file via a IoIntf. More...
 
struct  FileZipReader
 Example code that shows you how to write a ZipReader interface for the ZipIo class. More...
 

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...
 
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 DiskIo DiskIo
 The DiskIo class makes it possible for the web-server to work with resources on a hard drive. 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.
 
typedef IoIntfCspReader IoIntfCspReader
 The IoIntfCspReader, which implements the abstract CspReader interface, makes it possible to open a "CSP dat" file via a IoIntf.
 
typedef FileZipReader FileZipReader
 Example code that shows you how to write a ZipReader interface for the ZipIo class. More...
 

Functions

 ZipContainer::ZipContainer (ZipReader *reader, U8 *buf, U32 bufSize)
 
 ZipIo::ZipIo (ZipReader *reader, size_t size=256, AllocatorIntf *alloc=0)
 ZipIo constructor. More...
 
 ZipIo::~ZipIo ()
 ZipIo destructor.
 
ZipErr ZipIo::getECode ()
 Returns an error code if the ZipIo constructor failed.
 
 DiskIo::DiskIo ()
 Create a DiskIo instance and set the root directory to '/'. More...
 
 DiskIo::~DiskIo ()
 Terminate the DiskIo instance.
 
int DiskIo::setRootDir (const char *root)
 Set the root directory. More...
 
typedef ResIntfPtr(* IoIntf_InflateGzip) (IoIntfPtr io, const char *name, int *status, const char **ecode)
 Open a file for writing. More...
 
typedef ResIntfPtr(* IoIntf_DeflateGzip) (ResIntfPtr resPtr, const char *name, ThreadMutex *m, BaFileSize *size, BaBool *isCompressed)
 Deflate a file or portion of a file to temporary storage. More...
 
typedef int(* IoIntf_Property) (IoIntfPtr o, const char *name, void *a, void *b)
 Set or get properties. More...
 
typedef DirIntfPtr(* IoIntf_OpenDir) (IoIntfPtr o, const char *dirname, int *status, const char **ecode)
 Open a directory for reading. More...
 
typedef int(* IoIntf_Stat) (IoIntfPtr o, const char *name, IoStat *st)
 Fetch resource information.
 
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)
 Close an open directory iterator.
 
typedef ResIntfPtr(* IoIntf_OpenResGzip) (IoIntfPtr o, const char *name, ThreadMutex *m, BaFileSize *size, int *status, const char **ecode)
 Returns data as a compressed gzip file.
 
typedef int(* IoIntf_MkDir) (IoIntfPtr o, const char *name, const char **ecode)
 Create a new directory.
 
typedef int(* IoIntf_Rename) (IoIntfPtr o, const char *from, const char *to, const char **ecode)
 Close an open directory iterator.
 
typedef int(* IoIntf_Remove) (IoIntfPtr o, const char *name, const char **ecode)
 Delete a file.
 
typedef int(* IoIntf_RmDir) (IoIntfPtr o, const char *name, const char **ecode)
 delete an empty directory.
 
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)
 Iterate to next resource in directory.
 
typedef const char *(* DirIntf_GetName) (DirIntfPtr o)
 Returns the resource name.
 
typedef int(* DirIntf_Stat) (DirIntfPtr o, IoStat *st)
 Returns resource information.
 
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)
 Abstract Resource Interface.
 
typedef struct ResIntf ResIntf
 Resource handle for a directory opened with IoIntf_OpenRes.
 
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)
 wrapper for IoIntf_Property: 'type'. 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)
 Virtual destructor. More...
 
#define IOINTF_OK   0
 Error codes (status)
 
#define IOINTF_EOF   1
 End of file from ResIntf_Read.
 
#define IOINTF_INVALIDNAME   -11
 Invalid name or name not accepted by IOINTF implementation. More...
 
#define IOINTF_NOTFOUND   -12
 Resource not found.
 
#define IOINTF_EXIST   -13
 Resource exists and cannot be overwritten.
 
#define IOINTF_ENOENT   -14
 Path (parent directory) not found.
 
#define IOINTF_NOACCESS   -15
 No access or resource locked by file system.
 
#define IOINTF_NOTEMPTY   -16
 A directory resource is not empty.
 
#define IOINTF_NOSPACE   -17
 No space left on device.
 
#define IOINTF_IOERROR   -18
 Some kind of IO error. More...
 
#define IOINTF_MEM   -19
 Memory allocation error when working with resource.
 
#define IOINTF_NOIMPLEMENTATION   -50
 Method not implemented.
 
#define IOINTF_BUFTOOSMALL   -51
 The provided buffer is too small.
 
#define IOINTF_NOZIPLIB   -100
 IoIntf_OpenRes cannot uncompress the file since no NO_ZLIB is defined.
 
#define IOINTF_NOTCOMPRESSED   -101
 IoIntf_OpenResGzip is not willing to compress the data. More...
 
#define IOINTF_ZIPERROR   -102
 Error in compressed data.
 
#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.
 
#define IOINTF_NO_PASSWORD   -202
 File is AES encrypted, but password was not entered.
 
#define IOINTF_WRONG_PASSWORD   -203
 Wrong password for AES encrypted file.
 
#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.
 
#define OpenRes_WRITE   2
 Open resource write.
 
#define OpenRes_APPEND   4
 Open resource and append. More...
 

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.

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:

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.

The DiskIo is not officially supported by us. We provide implementations for a number of file systems. See directory examples/BaFile/ for more information. A DiskIo is typically not needed by the web-server unless you use the web file manager or the WebDAV server. Deployed web applications are typically stored in a ZipIo.

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:

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

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:

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

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:

The following properties are supported by all DiskIo media types:

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

Miscellaneous properties:

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.

Macro Definition Documentation

◆ 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_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_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_NOAESLIB

#define IOINTF_NOAESLIB   -200

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

Recompile without NO_SHARKSSL.

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

◆ OpenRes_APPEND

#define OpenRes_APPEND   4

Open resource and append.

Default is to truncate

Typedef Documentation

◆ DirIntf

typedef struct DirIntf DirIntf

Directory handle for a directory opened with IoIntf_OpenDir.

Example:

DirIntfPtr dir = io->openDirFp(io, relPath, &status, 0);
if(dir)
{
while ( ! dir->readFp(dir) )
{
IoStat st;
const char* name = dir->getNameFp(dir);
dir->statFp(dir, &st);
}
}
io->closeDirFp(io, &dir);
See also
IoIntf

◆ 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

The setRootDir method can accept an absolute or relative path argument. As an example, all example programs compiled in 'debug' mode executes from the 'obj/debug' directory. All 'debug mode' examples opens a DiskIo and sets the root path to '../../html' and binds the DiskIo to a HttpResRdr instance. This makes it possible for the web-server to access the HTML files in the 'html' directory.

This is a generic header file for all file systems and platforms.

Barracuda does not officially support native file systems as Barracuda can easily work without using a file system. However, the xrc/DiskIo directory contains implementation for common file systems. This directory also contains the BaFile API used by some of the example code.

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

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

Deflate a file or portion of a file to temporary storage.

A ResIntfPtr is returned to the compressed file or file fragment Function pointer in HttpResRdr.c See BaGzip.c for more info.

◆ IoIntf_InflateGzip

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

Open a file for writing.

Inflates the gzip file as it is saved. Function in BaGzip.c. Function pointer in HttpUpload.c See BaGzip.c for more info.

◆ IoIntf_OpenDir

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

Open a directory for reading.

Returns
DirIntfPtr directory iterator

◆ 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 | +----------—+----------------------------------------------—+

◆ IoIntf_Property

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

Set or get properties.

The method returns a non zero value if the property is not supported.

name: type a: pointer to 'const char**'. The type is returned as a string in 'a'. Common values: "disk", "zip". Variable 'b' contains a pointer to the platform type such as 'windows', 'POSIX', etc.

name: movedir a: Return value: pointer to U32 set to TRUE or FALSE. b: n/a

name: hidden a: pointer to 'const char*'. The resource name. b: Pointer to U32 is set to TRUE for hidden and FALSE if hidden attribute is to be cleared.

name: pwd a: pointer to 'const char*', the password.

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

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

Whenever a browser requests a file that is in a ZIP-File, the ZipIo class extracts the file, appends a GZIP header to the compressed data, and sends the file as a GZIP file to the browser.

A compression library is only needed if you have to support older browsers or if you plan to use method HttpResponse::include with Zip-Files. 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

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.

Function Documentation

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

◆ IoIntf_destructor()

BA_API void IoIntf_destructor ( IoIntfPtr  o)

Virtual destructor.

Releases dynamically allocated resources.

◆ 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
oa pointer to the IoIntf implementation.
paththe 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 
)

wrapper for IoIntf_Property: 'type'.

Parameters
oa pointer to the IoIntf implementation.
typeis where the type is stored. Common types are 'disk' and 'zip'.
platformis where the platform type is stored. Common types are 'windows' and 'POSIX'.

◆ IoIntf_isEncrypted()

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

wrapper for IoIntf_Property: 'aes'.

Parameters
oa pointer to the IoIntf implementation.
namethe file name.
isEncryptedreturn value set to TRUE or FALSE.
Returns
zero if found. Non-zero if not found.

◆ IoIntf_setPassword()

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

wrapper for IoIntf_Property: 'pl'.

Parameters
oa pointer to the IoIntf implementation.
passwordthe required password for accessing the resources.
passwordLenthe 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.
Returns
0 on success or a non zero value if setting password not implemeted by the IoIntf implementation.

◆ IoIntf_setPasswordProp()

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

wrapper for IoIntf_Property: 'pp'.

Parameters
oa pointer to the IoIntf implementation.
passwordRequiredSet 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.
passwordBinSet 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 implemeted by the IoIntf implementation.

◆ setRootDir()

int DiskIo::setRootDir ( const char *  root)

Set the root directory.

Parameters
rootis a UTF8 formated path using forward slash. The meaning of 'root' depends on the implementation. Please see the comments in the DiskIo implementation for your target platform for more information.
Returns
0 on success. A non zero value indicates failure.

◆ ZipContainer()

ZipContainer::ZipContainer ( ZipReader reader,
U8 *  buf,
U32  bufSize 
)
Parameters
readera ZipReader instance.
bufis a buffer with minimum size 256 bytes. You must make sure that this buffer is valid during the lifetime of the class instance.
bufSizesize of buffer.

◆ 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
readera ZipReader instance such as a FileZipReader.
sizeis the length of the longest directory and path name to resources in the ZIP file. Minimum value is 256. The ZipIo is internally passing this information to a ZipContainer.
allocThe ZipIo scans the ZIP file and builds a small virtual directory with information on the offset position to the internal data in the ZIP file. The allocator is used when building these data structures. The data structures are released when the ZipIo destructor is run.
ZipReader
Abstract interface class for reading a ZipFile.
Definition: ZipFileIterator.h:72
ZipIo
The ZipIo class makes it possible for the web-server to work with resources in a ZIP file as if the Z...
Definition: ZipIo.h:92
IoStat
Resource information.
Definition: IoIntf.h:168