Binary File Access [Utilities]

Collaboration diagram for Binary File Access:

Data Structures
struct	_imBinMemoryFileName
	Memory File Filename Parameter Structure. More...
class	imBinFileBase
	Binary File I/O Base Class. More...
Typedefs
typedef struct _imBinFile	imBinFile
typedef struct _imBinMemoryFileName	imBinMemoryFileName
typedef imBinFileBase *(*	imBinFileNewFunc )()
Enumerations
enum	imBinFileModule {   IM_RAWFILE, IM_STREAM, IM_MEMFILE, IM_SUBFILE,   IM_FILEHANDLE, IM_IOCUSTOM0 }
Functions
imBinFile *	imBinFileOpen (const char *pFileName)
imBinFile *	imBinFileNew (const char *pFileName)
void	imBinFileClose (imBinFile *bfile)
int	imBinFileError (imBinFile *bfile)
unsigned long	imBinFileSize (imBinFile *bfile)
int	imBinFileByteOrder (imBinFile *bfile, int pByteOrder)
unsigned long	imBinFileRead (imBinFile *bfile, void *pValues, unsigned long pCount, int pSizeOf)
unsigned long	imBinFileWrite (imBinFile *bfile, void *pValues, unsigned long pCount, int pSizeOf)
unsigned long	imBinFilePrintf (imBinFile *bfile, const char *format,...)
int	imBinFileReadLine (imBinFile *handle, char *comment, int *size)
int	imBinFileSkipLine (imBinFile *handle)
int	imBinFileReadInteger (imBinFile *handle, int *value)
int	imBinFileReadReal (imBinFile *handle, double *value)
void	imBinFileSeekTo (imBinFile *bfile, unsigned long pOffset)
void	imBinFileSeekOffset (imBinFile *bfile, long pOffset)
void	imBinFileSeekFrom (imBinFile *bfile, long pOffset)
unsigned long	imBinFileTell (imBinFile *bfile)
int	imBinFileEndOfFile (imBinFile *bfile)
int	imBinFileSetCurrentModule (int pModule)
void	imBinMemoryRelease (unsigned char *buffer)
int	imBinFileRegisterModule (imBinFileNewFunc pNewFunc)

---

Detailed Description

These functions are very useful for reading/writing binary files that have headers or data that have to be converted depending on the current CPU byte order. It can invert 2, 4 or 8 bytes numbers to/from little/big-endian orders.

It will process the data only if the file format is different from the current CPU.

Can read from disk or memory. In case of a memory buffer, the file name must be the imBinMemoryFileName structure.

See im_binfile.h

---

Typedef Documentation

typedef struct _imBinMemoryFileName imBinMemoryFileName

Memory File Filename Parameter Structure.

Fake file name for the memory I/O module.

typedef imBinFileBase*(* imBinFileNewFunc)()

File I/O module creation callback.

---

Enumeration Type Documentation

enum imBinFileModule

Predefined I/O Modules.

Enumerator:

IM_RAWFILE	System dependent file I/O Routines.
IM_STREAM	Standard Ansi C Stream I/O Routines.
IM_MEMFILE	Uses a memory buffer (see imBinMemoryFileName).
IM_SUBFILE	It is a sub file. FileName is a imBinFile* pointer from any other module.
IM_FILEHANDLE	System dependent file I/O Routines, but FileName is a system file handle ("int" in UNIX and "HANDLE" in Windows).
IM_IOCUSTOM0	Other registered modules starts from here.

---

Function Documentation

imBinFile* imBinFileOpen

(

const char *

pFileName

)

Opens an existant binary file for reading. The default file byte order is the CPU byte order. Returns NULL if failed.

imBinFile* imBinFileNew

(

const char *

pFileName

)

Creates a new binary file for writing. The default file byte order is the CPU byte order. Returns NULL if failed.

void imBinFileClose

(

imBinFile *

bfile

)

Closes the file.

int imBinFileError

(

imBinFile *

bfile

)

Indicates that was an error on the last operation.

unsigned long imBinFileSize

(

imBinFile *

bfile

)

Returns the file size in bytes.

int imBinFileByteOrder	(	imBinFile *	bfile,
		int	pByteOrder
	)

Changes the file byte order. Returns the old one.

unsigned long imBinFileRead	(	imBinFile *	bfile,
		void *	pValues,
		unsigned long	pCount,
		int	pSizeOf
	)

Reads an array of count values with byte sizes: 1, 2, 4, or 8. And invert the byte order if necessary after read.
Returns the actual count of values read.

unsigned long imBinFileWrite	(	imBinFile *	bfile,
		void *	pValues,
		unsigned long	pCount,
		int	pSizeOf
	)

Writes an array of values with sizes: 1, 2, 4, or 8. And invert the byte order if necessary before write.
ATENTION: The function will not make a temporary copy of the values to invert the byte order.
So after the call the values will be invalid, if the file byte order is different from the CPU byte order.
Returns the actual count of values written.

unsigned long imBinFilePrintf	(	imBinFile *	bfile,
		const char *	format,
			...
	)

Writes a string without the NULL terminator. The function uses sprintf to compose the string.
The internal buffer is fixed at 10240 bytes.
Returns the actual count of values written.

int imBinFileReadLine	(	imBinFile *	handle,
		char *	comment,
		int *	size
	)

Reads a line until line break.
Returns the line in array, must have room enough. Line break is discarded.
Use *size to inform buffer size. *size return the actual number os characters read.

int imBinFileSkipLine

(

imBinFile *

handle

)

Skips a line, including line break.

int imBinFileReadInteger	(	imBinFile *	handle,
		int *	value
	)

Reads an integer number from the current position until found a non integer character. Returns a non zero value if successful.

int imBinFileReadReal	(	imBinFile *	handle,
		double *	value
	)

Reads an floating point number from the current position until found a non number character. Returns a non zero value if successful.

void imBinFileSeekTo	(	imBinFile *	bfile,
		unsigned long	pOffset
	)

Moves the file pointer from the beginning of the file.
When writing to a file seeking can go beyond the end of the file.

void imBinFileSeekOffset	(	imBinFile *	bfile,
		long	pOffset
	)

Moves the file pointer from current position.
If the offset is a negative value the pointer moves backwards.

void imBinFileSeekFrom	(	imBinFile *	bfile,
		long	pOffset
	)

Moves the file pointer from the end of the file.
The offset is usually a negative value.

unsigned long imBinFileTell

(

imBinFile *

bfile

)

Returns the current offset position.

int imBinFileEndOfFile

(

imBinFile *

bfile

)

Indicates that the file pointer is at the end of the file.

int imBinFileSetCurrentModule

(

int

pModule

)

Sets the current I/O module.

Returns:

the previous function set, or -1 if failed. See also imBinFileModule.

void imBinMemoryRelease

(

unsigned char *

buffer

)

Release the internal memory allocated when writing a Memory File (see imBinMemoryFileName).

int imBinFileRegisterModule

(

imBinFileNewFunc

pNewFunc

)

Register a user I/O module.
Returns the new function set id.
Accepts up to 10 modules.