libmspack
 All Data Structures Files Functions Variables Macros
Data Fields
mspack_system Struct Reference

A structure which abstracts file I/O and memory management. More...

#include <mspack.h>

Data Fields

struct mspack_file *(* open )(struct mspack_system *self, const char *filename, int mode)
 Opens a file for reading, writing, appending or updating. More...
 
void(* close )(struct mspack_file *file)
 Closes a previously opened file. More...
 
int(* read )(struct mspack_file *file, void *buffer, int bytes)
 Reads a given number of bytes from an open file. More...
 
int(* write )(struct mspack_file *file, void *buffer, int bytes)
 Writes a given number of bytes to an open file. More...
 
int(* seek )(struct mspack_file *file, off_t offset, int mode)
 Seeks to a specific file offset within an open file. More...
 
off_t(* tell )(struct mspack_file *file)
 Returns the current file position (in bytes) of the given file. More...
 
void(* message )(struct mspack_file *file, const char *format,...)
 Used to send messages from the library to the user. More...
 
void *(* alloc )(struct mspack_system *self, size_t bytes)
 Allocates memory. More...
 
void(* free )(void *ptr)
 Frees memory. More...
 
void(* copy )(void *src, void *dest, size_t bytes)
 Copies from one region of memory to another. More...
 
void * null_ptr
 A null pointer to mark the end of mspack_system. More...
 

Detailed Description

A structure which abstracts file I/O and memory management.

The library always uses the mspack_system structure for interaction with the file system and to allocate, free and copy all memory. It also uses it to send literal messages to the library user.

When the library is compiled normally, passing NULL to a compressor or decompressor constructor will result in a default mspack_system being used, where all methods are implemented with the standard C library. However, all constructors support being given a custom created mspack_system structure, with the library user's own methods. This allows for more abstract interaction, such as reading and writing files directly to memory, or from a network socket or pipe.

Implementors of an mspack_system structure should read all documentation entries for every structure member, and write methods which conform to those standards.

Field Documentation

void*(* mspack_system::alloc)(struct mspack_system *self, size_t bytes)

Allocates memory.

Parameters
selfa self-referential pointer to the mspack_system structure whose alloc() method is being called.
bytesthe number of bytes to allocate
Returns
a pointer to the requested number of bytes, or NULL if not enough memory is available
See Also
free()
void(* mspack_system::close)(struct mspack_file *file)

Closes a previously opened file.

If any memory was allocated for this particular file handle, it should be freed at this time.

Parameters
filethe file to close
See Also
open()
void(* mspack_system::copy)(void *src, void *dest, size_t bytes)

Copies from one region of memory to another.

The regions of memory are guaranteed not to overlap, are usually less than 256 bytes, and may not be aligned. Please note that the source parameter comes before the destination parameter, unlike the standard C function memcpy().

Parameters
srcthe region of memory to copy from
destthe region of memory to copy to
bytesthe size of the memory region, in bytes
void(* mspack_system::free)(void *ptr)

Frees memory.

Parameters
ptrthe memory to be freed.
See Also
alloc()
void(* mspack_system::message)(struct mspack_file *file, const char *format,...)

Used to send messages from the library to the user.

Occasionally, the library generates warnings or other messages in plain english to inform the human user. These are informational only and can be ignored if not wanted.

Parameters
filemay be a file handle returned from open() if this message pertains to a specific open file, or NULL if not related to a specific file.
formata printf() style format string. It does NOT include a trailing newline.
See Also
open()
void* mspack_system::null_ptr

A null pointer to mark the end of mspack_system.

It must equal NULL.

Should the mspack_system structure extend in the future, this NULL will be seen, rather than have an invalid method pointer called.

struct mspack_file*(* mspack_system::open)(struct mspack_system *self, const char *filename, int mode)

Opens a file for reading, writing, appending or updating.

Parameters
selfa self-referential pointer to the mspack_system structure whose open() method is being called. If this pointer is required by close(), read(), write(), seek() or tell(), it should be stored in the result structure at this time.
filenamethe file to be opened. It is passed directly from the library caller without being modified, so it is up to the caller what this parameter actually represents.
modeone of MSPACK_SYS_OPEN_READ (open an existing file for reading), MSPACK_SYS_OPEN_WRITE (open a new file for writing), MSPACK_SYS_OPEN_UPDATE (open an existing file for reading/writing from the start of the file) or MSPACK_SYS_OPEN_APPEND (open an existing file for reading/writing from the end of the file)
Returns
a pointer to a mspack_file structure. This structure officially contains no members, its true contents are up to the mspack_system implementor. It should contain whatever is needed for other mspack_system methods to operate. Returning the NULL pointer indicates an error condition.
See Also
close(), read(), write(), seek(), tell(), message()
int(* mspack_system::read)(struct mspack_file *file, void *buffer, int bytes)

Reads a given number of bytes from an open file.

Parameters
filethe file to read from
bufferthe location where the read bytes should be stored
bytesthe number of bytes to read from the file.
Returns
the number of bytes successfully read (this can be less than the number requested), zero to mark the end of file, or less than zero to indicate an error.
See Also
open(), write()
int(* mspack_system::seek)(struct mspack_file *file, off_t offset, int mode)

Seeks to a specific file offset within an open file.

Sometimes the library needs to know the length of a file. It does this by seeking to the end of the file with seek(file, 0, MSPACK_SYS_SEEK_END), then calling tell(). Implementations may want to make a special case for this.

Due to the potentially varying 32/64 bit datatype off_t on some architectures, the MSPACK_SYS_SELFTEST macro MUST be used before using the library. If not, the error caused by the library passing an inappropriate stackframe to seek() is subtle and hard to trace.

Parameters
filethe file to be seeked
offsetan offset to seek, measured in bytes
modeone of MSPACK_SYS_SEEK_START (the offset should be measured from the start of the file), MSPACK_SYS_SEEK_CUR (the offset should be measured from the current file offset) or MSPACK_SYS_SEEK_END (the offset should be measured from the end of the file)
Returns
zero for success, non-zero for an error
See Also
open(), tell()
off_t(* mspack_system::tell)(struct mspack_file *file)

Returns the current file position (in bytes) of the given file.

Parameters
filethe file whose file position is wanted
Returns
the current file position of the file
See Also
open(), seek()
int(* mspack_system::write)(struct mspack_file *file, void *buffer, int bytes)

Writes a given number of bytes to an open file.

Parameters
filethe file to write to
bufferthe location where the written bytes should be read from
bytesthe number of bytes to write to the file.
Returns
the number of bytes successfully written, this can be less than the number requested. Zero or less can indicate an error where no bytes at all could be written. All cases where less bytes were written than requested are considered by the library to be an error.
See Also
open(), read()

The documentation for this struct was generated from the following file: