IM: Binary File Access

IM - An Imaging Tool

Binary File Access
[Utilities]


Detailed Description

These functions are very usefull 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 diferent 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


Data Structures

struct  _imBinMemoryFileName
 Memory File I/O Filename. More...

Typedefs

typedef _imBinMemoryFileName imBinMemoryFileName

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, char *format,...)
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)

Typedef Documentation

typedef struct _imBinMemoryFileName imBinMemoryFileName
 

Memory File I/O Filename.

Fake file name for the memory I/O module.


Enumeration Type Documentation

enum imBinFileModule
 

Predefined I/O Modules.

Enumerator:
IM_RAWFILE  System dependent file I/O Rotines.
IM_STREAM  Standard Ansi C Stream I/O Rotines.
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 Rotines, but FileName is a system file handle ("int" in UNIX and "HANDLE" in Windows).
IM_IOCUSTOM0  Other registered modules starts from here.
00102 {               
00103   IM_RAWFILE,   /**< System dependent file I/O Rotines. */
00104   IM_STREAM,    /**< Standard Ansi C Stream I/O Rotines. */
00105   IM_MEMFILE,   /**< Uses a memory buffer (see \ref imBinMemoryFileName). */
00106   IM_SUBFILE,   /**< It is a sub file. FileName is a imBinFile* pointer from any other module. */
00107   IM_FILEHANDLE,/**< System dependent file I/O Rotines, but FileName is a system file handle ("int" in UNIX and "HANDLE" in Windows). */
00108   IM_IOCUSTOM0  /**< Other registered modules starts from here. */
00109 };


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.

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 diferent from the CPU byte order.

unsigned long imBinFilePrintf imBinFile *  bfile,
char *  format,
  ...
 

Writes a string without the NULL terminator. The function uses sprintf to compose the string.
The internal buffer is fixed at 4096 bytes.

void imBinFileSeekTo imBinFile *  bfile,
unsigned long  pOffset
 

Moves the file pointer from the begining 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).