IpatchFileIOFuncs

typedef struct {
  gboolean (*open)(IpatchFileHandle *handle, const char *mode, GError **err);
  void (*close)(IpatchFileHandle *handle);
  GIOStatus (*read)(IpatchFileHandle *handle, gpointer buf, guint size,
		    guint *bytes_read, GError **err);
  GIOStatus (*write)(IpatchFileHandle *handle, gconstpointer buf, guint size,
		     GError **err);
  GIOStatus (*seek)(IpatchFileHandle *handle, int offset, GSeekType type, GError **err);
  int (*getfd)(IpatchFileHandle *handle); /* optional get file descriptor method */
  int (*get_size)(IpatchFile *file, GError **err);  /* optional get size method */
} IpatchFileIOFuncs;

IpatchFileHandle

typedef struct {
  IpatchFile *file;		/* Parent file object */
  guint position;               /* Current file position */
  GByteArray *buf;              /* For buffered reads/writes */
  guint buf_position;           /* Current position in buffer */
  GIOChannel *iochan;		/* glib IO channel (default methods) */
  gpointer data;                /* iofuncs defined data */
} IpatchFileHandle;

IpatchFile handle for opening a file and reading/writing from/to it.

IpatchFile

typedef struct _IpatchFile IpatchFile;

enum IpatchFileFlags

typedef enum
{
  IPATCH_FILE_FLAG_SWAP = 1 << (IPATCH_ITEM_UNUSED_FLAG_SHIFT),
  IPATCH_FILE_FLAG_BIG_ENDIAN = 1 << (IPATCH_ITEM_UNUSED_FLAG_SHIFT + 1),
  IPATCH_FILE_FLAG_FREE_IOFUNCS = 1 << (IPATCH_ITEM_UNUSED_FLAG_SHIFT + 2)
} IpatchFileFlags;

enum IpatchFileIdentifyOrder

typedef enum
{
  IPATCH_FILE_IDENTIFY_ORDER_LAST = -10,
  IPATCH_FILE_IDENTIFY_ORDER_DEFAULT = 0,
  IPATCH_FILE_IDENTIFY_ORDER_FIRST = 10
} IpatchFileIdentifyOrder;

Some helpful constants for the identify_order IpatchFileClass field. Note that any value can be used and this enum just provides some helpful values. This value determines in what order file identification methods are called. Higher values are executed first.

IPATCH_FILE_UNUSED_FLAG_SHIFT

#define IPATCH_FILE_UNUSED_FLAG_SHIFT  (IPATCH_ITEM_UNUSED_FLAG_SHIFT + 6)

IPATCH_FILE_NEED_SWAP()

#define             IPATCH_FILE_NEED_SWAP(file)

IPATCH_FILE_BIG_ENDIAN()

#define             IPATCH_FILE_BIG_ENDIAN(file)

IPATCH_FILE_SWAP16()

#define             IPATCH_FILE_SWAP16(file, p16)

IPATCH_FILE_SWAP32()

#define             IPATCH_FILE_SWAP32(file, p32)

IPATCH_FILE_SWAP64()

#define             IPATCH_FILE_SWAP64(file, p64)

IPATCH_IS_FILE_HANDLE()

#define             IPATCH_IS_FILE_HANDLE(handle)

ipatch_file_new ()

IpatchFile *        ipatch_file_new                     (void);

Create a new file object

ipatch_file_set_name ()

void                ipatch_file_set_name                (IpatchFile *file,
                                                         const char *file_name);

Sets the file name of a file object. Assigning the file name of an IpatchFile object is optional, since a file descriptor could be assigned instead, but some subsystems depend on it.

ipatch_file_get_name ()

char *              ipatch_file_get_name                (IpatchFile *file);

Gets the assigned file name from a file object.

ipatch_file_open ()

IpatchFileHandle *  ipatch_file_open                    (IpatchFile *file,
                                                         const char *file_name,
                                                         const char *mode,
                                                         GError **err);

Opens a handle to a file object. If a I/O channel or file descriptor is already assigned (with ipatch_file_assign_fd() or ipatch_file_assign_io_channel()) then it is used instead of opening a file using file_name or the already assigned "file-name" property.

ipatch_file_assign_fd ()

void                ipatch_file_assign_fd               (IpatchFile *file,
                                                         int fd,
                                                         gboolean close_on_finalize);

Assigns a file descriptor to a file, which gets used for calls to ipatch_file_open(). Note that this means multiple opens will use the same file descriptor and will therefore conflict, so it should only be used in the case where the file object is used by a single exclusive handle.

ipatch_file_assign_io_channel ()

void                ipatch_file_assign_io_channel       (IpatchFile *file,
                                                         GIOChannel *iochan);

Assigns an I/O channel to a file, which gets used for calls to ipatch_file_open(). Note that this means multiple opens will use the same file descriptor and will therefore conflict, so it should only be used in the case where the file object is used by a single exclusive handle.

ipatch_file_get_io_channel ()

GIOChannel *        ipatch_file_get_io_channel          (IpatchFileHandle *handle);

Get the glib IO channel object from a file handle. The caller owns a reference to the returned io channel, and it should be unreferenced with g_io_channel_unref() when finished with it.

ipatch_file_get_fd ()

int                 ipatch_file_get_fd                  (IpatchFileHandle *handle);

Get the unix file descriptor associated with a file handle. Not all file handles have a real OS file descriptor.

ipatch_file_close ()

void                ipatch_file_close                   (IpatchFileHandle *handle);

Close a file handle and free it.

ipatch_file_get_position ()

guint               ipatch_file_get_position            (IpatchFileHandle *handle);

Gets the current position in a file handle. Note that this might not be the actual position in the file if the file handle was attached to an already open file or if ipatch_file_update_position() is used to set virtual positions.

ipatch_file_update_position ()

void                ipatch_file_update_position         (IpatchFileHandle *handle,
                                                         guint offset);

Adds an offset value to the position counter in a file handle. This can be used if one is operating directly on the underlying file descriptor (i.e., not using the IpatchFile functions) or to add virtual space to the counter. Adding virtual space is useful when a system uses the position counter to write data (such as the RIFF parser) to act as a place holder for data that isn't actually written (sample data for example).

ipatch_file_read ()

gboolean            ipatch_file_read                    (IpatchFileHandle *handle,
                                                         gpointer buf,
                                                         guint size,
                                                         GError **err);

Reads data from a file handle. An end of file encountered while trying to read the specified size of data is treated as an error. If this is undesirable use ipatch_file_read_eof() instead.

ipatch_file_read_eof ()

GIOStatus           ipatch_file_read_eof                (IpatchFileHandle *handle,
                                                         gpointer buf,
                                                         guint size,
                                                         guint *bytes_read,
                                                         GError **err);

Reads data from a file handle. This function does not treat end of file as an error and will return G_IO_STATUS_EOF with the number of bytes actually read in bytes_read. Use ipatch_file_read() for convenience to ensure actual number of requested bytes is read.

ipatch_file_write ()

gboolean            ipatch_file_write                   (IpatchFileHandle *handle,
                                                         gconstpointer buf,
                                                         guint size,
                                                         GError **err);

Writes data to a file object.

ipatch_file_skip()

#define             ipatch_file_skip(handle, offset, err)

ipatch_file_seek ()

gboolean            ipatch_file_seek                    (IpatchFileHandle *handle,
                                                         int offset,
                                                         GSeekType type,
                                                         GError **err);

Seek in a file handle. An end of file condition is treated as an error, use ipatch_file_seek_eof() if this is undesirable.

ipatch_file_seek_eof ()

GIOStatus           ipatch_file_seek_eof                (IpatchFileHandle *handle,
                                                         int offset,
                                                         GSeekType type,
                                                         GError **err);

Seek in a file object. Does not treat end of file as an error, use ipatch_file_seek() for convenience if this is desirable.

ipatch_file_get_size ()

int                 ipatch_file_get_size                (IpatchFile *file,
                                                         GError **err);

Get the size of a file object.

ipatch_file_identify ()

GType               ipatch_file_identify                (IpatchFile *file,
                                                         GError **err);

Attempts to identify the type of a file using the "identify" method of registered types derived from IpatchFile. The "file-name" property should already be assigned.

ipatch_file_identify_by_ext ()

GType               ipatch_file_identify_by_ext         (IpatchFile *file);

Attempts to identify the type of a file using the "identify" method of registered types derived from IpatchFile. The "file-name" property should already be assigned. Like ipatch_file_identify() but identifies a file by its file name extension only.

ipatch_file_identify_open ()

IpatchFileHandle *  ipatch_file_identify_open           (const char *file_name,
                                                         GError **err);

A convenience function which calls ipatch_file_identify() to determine the file type of file_name. If the type is identified a new file object, of the identified type, is created and the file is opened with ipatch_file_open() in read mode.

ipatch_file_set_little_endian ()

void                ipatch_file_set_little_endian       (IpatchFile *file);

Sets the file object to little endian mode (the default mode). If the system is big endian, byte swapping will be enabled (see IPATCH_FILE_SWAPxx macros). The endian mode affects buffered read and write functions that operate on multi-byte integers.

ipatch_file_set_big_endian ()

void                ipatch_file_set_big_endian          (IpatchFile *file);

Sets the file object to big endian mode (the default is little endian). If the system is little endian, byte swapping will be enabled (see IPATCH_FILE_SWAPxx macros). The endian mode affects buffered read and write functions that operate on multi-byte integers.

ipatch_file_read_u8 ()

gboolean            ipatch_file_read_u8                 (IpatchFileHandle *handle,
                                                         guint8 *val,
                                                         GError **err);

Read an unsigned 8 bit integer from a file.

ipatch_file_read_u16 ()

gboolean            ipatch_file_read_u16                (IpatchFileHandle *handle,
                                                         guint16 *val,
                                                         GError **err);

Read an unsigned 16 bit integer from a file and performs endian byte swapping if necessary.

ipatch_file_read_u32 ()

gboolean            ipatch_file_read_u32                (IpatchFileHandle *handle,
                                                         guint32 *val,
                                                         GError **err);

Read an unsigned 32 bit integer from a file and performs endian byte swapping if necessary.

ipatch_file_read_u64 ()

gboolean            ipatch_file_read_u64                (IpatchFileHandle *handle,
                                                         guint64 *val,
                                                         GError **err);

Read an unsigned 64 bit integer from a file and performs endian byte swapping if necessary.

ipatch_file_read_s8 ()

gboolean            ipatch_file_read_s8                 (IpatchFileHandle *handle,
                                                         gint8 *val,
                                                         GError **err);

Read a signed 8 bit integer from a file.

ipatch_file_read_s16 ()

gboolean            ipatch_file_read_s16                (IpatchFileHandle *handle,
                                                         gint16 *val,
                                                         GError **err);

Read a signed 16 bit integer from a file and performs endian byte swapping if necessary.

ipatch_file_read_s32 ()

gboolean            ipatch_file_read_s32                (IpatchFileHandle *handle,
                                                         gint32 *val,
                                                         GError **err);

Read a signed 32 bit integer from a file and performs endian byte swapping if necessary.

ipatch_file_read_s64 ()

gboolean            ipatch_file_read_s64                (IpatchFileHandle *handle,
                                                         gint64 *val,
                                                         GError **err);

Read a signed 64 bit integer from a file and performs endian byte swapping if necessary.

ipatch_file_write_u8 ()

gboolean            ipatch_file_write_u8                (IpatchFileHandle *handle,
                                                         guint8 val,
                                                         GError **err);

Write an unsigned 8 bit integer to a file.

ipatch_file_write_u16 ()

gboolean            ipatch_file_write_u16               (IpatchFileHandle *handle,
                                                         guint16 val,
                                                         GError **err);

Write an unsigned 16 bit integer to a file and performs endian byte swapping if necessary.

ipatch_file_write_u32 ()

gboolean            ipatch_file_write_u32               (IpatchFileHandle *handle,
                                                         guint32 val,
                                                         GError **err);

Write an unsigned 32 bit integer to a file and performs endian byte swapping if necessary.

ipatch_file_write_u64 ()

gboolean            ipatch_file_write_u64               (IpatchFileHandle *handle,
                                                         guint64 val,
                                                         GError **err);

Write an unsigned 64 bit integer to a file and performs endian byte swapping if necessary.

ipatch_file_write_s8 ()

gboolean            ipatch_file_write_s8                (IpatchFileHandle *handle,
                                                         gint8 val,
                                                         GError **err);

Write a signed 8 bit integer to a file.

ipatch_file_write_s16 ()

gboolean            ipatch_file_write_s16               (IpatchFileHandle *handle,
                                                         gint16 val,
                                                         GError **err);

Write a signed 16 bit integer to a file and performs endian byte swapping if necessary.

ipatch_file_write_s32 ()

gboolean            ipatch_file_write_s32               (IpatchFileHandle *handle,
                                                         gint32 val,
                                                         GError **err);

Write a signed 32 bit integer to a file and performs endian byte swapping if necessary.

ipatch_file_write_s64 ()

gboolean            ipatch_file_write_s64               (IpatchFileHandle *handle,
                                                         gint64 val,
                                                         GError **err);

Write a signed 64 bit integer to a file and performs endian byte swapping if necessary.

ipatch_file_buf_load ()

gboolean            ipatch_file_buf_load                (IpatchFileHandle *handle,
                                                         guint size,
                                                         GError **err);

Load data from a file into a buffer for error checking convenience. I/O errors need only be checked on this function and not on the subsequent buffered read function calls. It is an error if an end of file is encountered before all the requested data is read.

ipatch_file_buf_read ()

void                ipatch_file_buf_read                (IpatchFileHandle *handle,
                                                         gpointer buf,
                                                         guint size);

Read data from a file handle's buffer and advance the buffer's current position. A call to ipatch_file_buf_load() must have been previously executed and there must be enough remaining data in the buffer for the read.

ipatch_file_buf_write ()

void                ipatch_file_buf_write               (IpatchFileHandle *handle,
                                                         gconstpointer buf,
                                                         guint size);

Write data to a file handle's buffer and advance the buffer's current position. Data will not actually be written to file till ipatch_file_buf_commit() is called.

ipatch_file_buf_zero()

#define             ipatch_file_buf_zero(filebuf, size)

ipatch_file_buf_memset ()

void                ipatch_file_buf_memset              (IpatchFileHandle *handle,
                                                         char c,
                                                         guint size);

Sets the given size in bytes to the character c and advances the current position. Buffer is expanded if necessary.

ipatch_file_buf_commit ()

gboolean            ipatch_file_buf_commit              (IpatchFileHandle *handle,
                                                         GError **err);

Writes all data in a file handle's buffer to the file and resets the buffer to empty.

ipatch_file_buf_skip()

#define             ipatch_file_buf_skip(filebuf, offset)

ipatch_file_buf_seek ()

void                ipatch_file_buf_seek                (IpatchFileHandle *handle,
                                                         int offset,
                                                         GSeekType type);

Seeks the current position in a file handle's buffer specified by an offset and seek type. It is an error to seek outside of the current size of buffered data (loaded or written). The offset is relative to the buffer, not the file position.

ipatch_file_buf_read_u8 ()

guint8              ipatch_file_buf_read_u8             (IpatchFileHandle *handle);

Reads an unsigned byte from a file buffer and advances the buffer's current position.

ipatch_file_buf_read_u16 ()

guint16             ipatch_file_buf_read_u16            (IpatchFileHandle *handle);

Reads an unsigned 16 bit word from a file buffer and advances the buffer's current position. Performs endian byte swapping if necessary.

ipatch_file_buf_read_u32 ()

guint32             ipatch_file_buf_read_u32            (IpatchFileHandle *handle);

Reads an unsigned 32 bit word from a file buffer and advances the buffer's current position. Performs endian byte swapping if necessary.

ipatch_file_buf_read_u64 ()

guint64             ipatch_file_buf_read_u64            (IpatchFileHandle *handle);

Reads an unsigned 64 bit word from a file buffer and advances the buffer's current position. Performs endian byte swapping if necessary.

ipatch_file_buf_read_s8 ()

gint8               ipatch_file_buf_read_s8             (IpatchFileHandle *handle);

Reads a signed byte from a file buffer and advances the buffer's current position.

ipatch_file_buf_read_s16 ()

gint16              ipatch_file_buf_read_s16            (IpatchFileHandle *handle);

Reads a signed 16 bit word from a file buffer and advances the buffer's current position. Performs endian byte swapping if necessary.

ipatch_file_buf_read_s32 ()

gint32              ipatch_file_buf_read_s32            (IpatchFileHandle *handle);

Reads a signed 32 bit word from a file buffer and advances the buffer's current position. Performs endian byte swapping if necessary.

ipatch_file_buf_read_s64 ()

gint64              ipatch_file_buf_read_s64            (IpatchFileHandle *handle);

Reads a signed 64 bit word from a file buffer and advances the buffer's current position. Performs endian byte swapping if necessary.

ipatch_file_buf_write_u8 ()

void                ipatch_file_buf_write_u8            (IpatchFileHandle *handle,
                                                         guint8 val);

Writes an unsigned byte to a file buffer and advances the buffer's current position. The file buffer is expanded if needed.

ipatch_file_buf_write_u16 ()

void                ipatch_file_buf_write_u16           (IpatchFileHandle *handle,
                                                         guint16 val);

Writes an unsigned 16 bit word to a file buffer and advances the buffer's current position. Performs endian byte swapping if necessary. The file buffer is expanded if needed.

ipatch_file_buf_write_u32 ()

void                ipatch_file_buf_write_u32           (IpatchFileHandle *handle,
                                                         guint32 val);

Writes an unsigned 32 bit word to a file buffer and advances the buffer's current position. Performs endian byte swapping if necessary. The file buffer is expanded if needed.

ipatch_file_buf_write_u64 ()

void                ipatch_file_buf_write_u64           (IpatchFileHandle *handle,
                                                         guint64 val);

Writes an unsigned 64 bit word to a file buffer and advances the buffer's current position. Performs endian byte swapping if necessary. The file buffer is expanded if needed.

ipatch_file_buf_write_s8 ()

void                ipatch_file_buf_write_s8            (IpatchFileHandle *handle,
                                                         gint8 val);

Writes a signed byte to a file buffer and advances the buffer's current position. The file buffer is expanded if needed.

ipatch_file_buf_write_s16 ()

void                ipatch_file_buf_write_s16           (IpatchFileHandle *handle,
                                                         gint16 val);

Writes a signed 16 bit word to a file buffer and advances the buffer's current position. Performs endian byte swapping if necessary. The file buffer is expanded if needed.

ipatch_file_buf_write_s32 ()

void                ipatch_file_buf_write_s32           (IpatchFileHandle *handle,
                                                         gint32 val);

Writes a signed 32 bit word to a file buffer and advances the buffer's current position. Performs endian byte swapping if necessary. The file buffer is expanded if needed.

ipatch_file_buf_write_s64 ()

void                ipatch_file_buf_write_s64           (IpatchFileHandle *handle,
                                                         gint64 val);

Writes a signed 64 bit word to a file buffer and advances the buffer's current position. Performs endian byte swapping if necessary. The file buffer is expanded if needed.

ipatch_file_set_iofuncs_static ()

void                ipatch_file_set_iofuncs_static      (IpatchFile *file,
                                                         IpatchFileIOFuncs *funcs);

Sets the input/output functions of a file object using a statically allocated (guaranteed to exist for lifetime of file) functions structure. Setting these functions allows one to write custom data sources or hook into other file functions.

ipatch_file_set_iofuncs ()

void                ipatch_file_set_iofuncs             (IpatchFile *file,
                                                         const IpatchFileIOFuncs *funcs);

Sets the input/output functions of a file object. The funcs structure is duplicated so as not to use the original, see ipatch_file_set_iofuncs_static() for using a static structure. Setting these functions allows one to write custom data sources or hook into other file functions.

ipatch_file_get_iofuncs ()

void                ipatch_file_get_iofuncs             (IpatchFile *file,
                                                         IpatchFileIOFuncs *out_funcs);

Get the current IO functions from a file object. The function pointers are stored in a user supplied structure pointed to by out_funcs.

ipatch_file_set_iofuncs_null ()

void                ipatch_file_set_iofuncs_null        (IpatchFile *file);

Sets the I/O functions of a file object to /dev/null like methods. Reading from the file will return 0s, writing/seeking will do nothing.

ipatch_file_default_open_method ()

gboolean            ipatch_file_default_open_method     (IpatchFileHandle *handle,
                                                         const char *mode,
                                                         GError **err);

Default "open" method for IpatchFileIOFuncs. Useful when overriding only some I/O functions.

ipatch_file_default_close_method ()

void                ipatch_file_default_close_method    (IpatchFileHandle *handle);

Default "close" method for IpatchFileIOFuncs. Useful when overriding only some I/O functions.

ipatch_file_default_read_method ()

GIOStatus           ipatch_file_default_read_method     (IpatchFileHandle *handle,
                                                         gpointer buf,
                                                         guint size,
                                                         guint *bytes_read,
                                                         GError **err);

Default "read" method for IpatchFileIOFuncs. Useful when overriding only some I/O functions.

ipatch_file_default_write_method ()

GIOStatus           ipatch_file_default_write_method    (IpatchFileHandle *handle,
                                                         gconstpointer buf,
                                                         guint size,
                                                         GError **err);

Default "write" method for IpatchFileIOFuncs. Useful when overriding only some I/O functions.

ipatch_file_default_seek_method ()

GIOStatus           ipatch_file_default_seek_method     (IpatchFileHandle *handle,
                                                         int offset,
                                                         GSeekType type,
                                                         GError **err);

Default "seek" method for IpatchFileIOFuncs. Useful when overriding only some I/O functions.

ipatch_file_default_getfd_method ()

int                 ipatch_file_default_getfd_method    (IpatchFileHandle *handle);

Default "getfd" method for IpatchFileIOFuncs. Useful when overriding only some I/O functions. This method gets a unix file descriptor for the given file object, it is an optional method.

ipatch_file_default_get_size_method ()

int                 ipatch_file_default_get_size_method (IpatchFile *file,
                                                         GError **err);

Default get file size method, which is optional.

The "file-name" property

  "file-name"                gchar*                : Read / Write

File Name.

Default value: NULL