## IpatchFile IpatchFile — File abstraction object |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

                        IpatchFileIOFuncs;
                        IpatchFileHandle;
                        IpatchFile;
    enum                IpatchFileFlags;
    enum                IpatchFileIdentifyOrder;
    #define             IPATCH_FILE_UNUSED_FLAG_SHIFT
    #define             IPATCH_FILE_NEED_SWAP               (file)
    #define             IPATCH_FILE_BIG_ENDIAN              (file)
    #define             IPATCH_FILE_SWAP16                  (file, p16)
    #define             IPATCH_FILE_SWAP32                  (file, p32)
    #define             IPATCH_FILE_SWAP64                  (file, p64)
    #define             IPATCH_IS_FILE_HANDLE               (handle)
    IpatchFile *        ipatch_file_new                     (void);
    void                ipatch_file_set_name                (IpatchFile *file,
                                                             const char *file_name);
    char *              ipatch_file_get_name                (IpatchFile *file);
    IpatchFileHandle *  ipatch_file_open                    (IpatchFile *file,
                                                             const char *file_name,
                                                             const char *mode,
                                                             GError **err);
    void                ipatch_file_assign_fd               (IpatchFile *file,
                                                             int fd,
                                                             gboolean close_on_finalize);
    void                ipatch_file_assign_io_channel       (IpatchFile *file,
                                                             GIOChannel *iochan);
    GIOChannel *        ipatch_file_get_io_channel          (IpatchFileHandle *handle);
    int                 ipatch_file_get_fd                  (IpatchFileHandle *handle);
    void                ipatch_file_close                   (IpatchFileHandle *handle);
    guint               ipatch_file_get_position            (IpatchFileHandle *handle);
    void                ipatch_file_update_position         (IpatchFileHandle *handle,
                                                             guint offset);
    gboolean            ipatch_file_read                    (IpatchFileHandle *handle,
                                                             gpointer buf,
                                                             guint size,
                                                             GError **err);
    GIOStatus           ipatch_file_read_eof                (IpatchFileHandle *handle,
                                                             gpointer buf,
                                                             guint size,
                                                             guint *bytes_read,
                                                             GError **err);
    gboolean            ipatch_file_write                   (IpatchFileHandle *handle,
                                                             gconstpointer buf,
                                                             guint size,
                                                             GError **err);
    #define             ipatch_file_skip                    (handle, offset, err)
    gboolean            ipatch_file_seek                    (IpatchFileHandle *handle,
                                                             int offset,
                                                             GSeekType type,
                                                             GError **err);
    GIOStatus           ipatch_file_seek_eof                (IpatchFileHandle *handle,
                                                             int offset,
                                                             GSeekType type,
                                                             GError **err);
    int                 ipatch_file_get_size                (IpatchFile *file,
                                                             GError **err);
    GType               ipatch_file_identify                (IpatchFile *file,
                                                             GError **err);
    GType               ipatch_file_identify_by_ext         (IpatchFile *file);
    IpatchFileHandle *  ipatch_file_identify_open           (const char *file_name,
                                                             GError **err);
    void                ipatch_file_set_little_endian       (IpatchFile *file);
    void                ipatch_file_set_big_endian          (IpatchFile *file);
    gboolean            ipatch_file_read_u8                 (IpatchFileHandle *handle,
                                                             guint8 *val,
                                                             GError **err);
    gboolean            ipatch_file_read_u16                (IpatchFileHandle *handle,
                                                             guint16 *val,
                                                             GError **err);
    gboolean            ipatch_file_read_u32                (IpatchFileHandle *handle,
                                                             guint32 *val,
                                                             GError **err);
    gboolean            ipatch_file_read_u64                (IpatchFileHandle *handle,
                                                             guint64 *val,
                                                             GError **err);
    gboolean            ipatch_file_read_s8                 (IpatchFileHandle *handle,
                                                             gint8 *val,
                                                             GError **err);
    gboolean            ipatch_file_read_s16                (IpatchFileHandle *handle,
                                                             gint16 *val,
                                                             GError **err);
    gboolean            ipatch_file_read_s32                (IpatchFileHandle *handle,
                                                             gint32 *val,
                                                             GError **err);
    gboolean            ipatch_file_read_s64                (IpatchFileHandle *handle,
                                                             gint64 *val,
                                                             GError **err);
    gboolean            ipatch_file_write_u8                (IpatchFileHandle *handle,
                                                             guint8 val,
                                                             GError **err);
    gboolean            ipatch_file_write_u16               (IpatchFileHandle *handle,
                                                             guint16 val,
                                                             GError **err);
    gboolean            ipatch_file_write_u32               (IpatchFileHandle *handle,
                                                             guint32 val,
                                                             GError **err);
    gboolean            ipatch_file_write_u64               (IpatchFileHandle *handle,
                                                             guint64 val,
                                                             GError **err);
    gboolean            ipatch_file_write_s8                (IpatchFileHandle *handle,
                                                             gint8 val,
                                                             GError **err);
    gboolean            ipatch_file_write_s16               (IpatchFileHandle *handle,
                                                             gint16 val,
                                                             GError **err);
    gboolean            ipatch_file_write_s32               (IpatchFileHandle *handle,
                                                             gint32 val,
                                                             GError **err);
    gboolean            ipatch_file_write_s64               (IpatchFileHandle *handle,
                                                             gint64 val,
                                                             GError **err);
    gboolean            ipatch_file_buf_load                (IpatchFileHandle *handle,
                                                             guint size,
                                                             GError **err);
    void                ipatch_file_buf_read                (IpatchFileHandle *handle,
                                                             gpointer buf,
                                                             guint size);
    void                ipatch_file_buf_write               (IpatchFileHandle *handle,
                                                             gconstpointer buf,
                                                             guint size);
    #define             ipatch_file_buf_zero                (filebuf, size)
    void                ipatch_file_buf_memset              (IpatchFileHandle *handle,
                                                             char c,
                                                             guint size);
    gboolean            ipatch_file_buf_commit              (IpatchFileHandle *handle,
                                                             GError **err);
    #define             ipatch_file_buf_skip                (filebuf, offset)
    void                ipatch_file_buf_seek                (IpatchFileHandle *handle,
                                                             int offset,
                                                             GSeekType type);
    guint8              ipatch_file_buf_read_u8             (IpatchFileHandle *handle);
    guint16             ipatch_file_buf_read_u16            (IpatchFileHandle *handle);
    guint32             ipatch_file_buf_read_u32            (IpatchFileHandle *handle);
    guint64             ipatch_file_buf_read_u64            (IpatchFileHandle *handle);
    gint8               ipatch_file_buf_read_s8             (IpatchFileHandle *handle);
    gint16              ipatch_file_buf_read_s16            (IpatchFileHandle *handle);
    gint32              ipatch_file_buf_read_s32            (IpatchFileHandle *handle);
    gint64              ipatch_file_buf_read_s64            (IpatchFileHandle *handle);
    void                ipatch_file_buf_write_u8            (IpatchFileHandle *handle,
                                                             guint8 val);
    void                ipatch_file_buf_write_u16           (IpatchFileHandle *handle,
                                                             guint16 val);
    void                ipatch_file_buf_write_u32           (IpatchFileHandle *handle,
                                                             guint32 val);
    void                ipatch_file_buf_write_u64           (IpatchFileHandle *handle,
                                                             guint64 val);
    void                ipatch_file_buf_write_s8            (IpatchFileHandle *handle,
                                                             gint8 val);
    void                ipatch_file_buf_write_s16           (IpatchFileHandle *handle,
                                                             gint16 val);
    void                ipatch_file_buf_write_s32           (IpatchFileHandle *handle,
                                                             gint32 val);
    void                ipatch_file_buf_write_s64           (IpatchFileHandle *handle,
                                                             gint64 val);
    void                ipatch_file_set_iofuncs_static      (IpatchFile *file,
                                                             IpatchFileIOFuncs *funcs);
    void                ipatch_file_set_iofuncs             (IpatchFile *file,
                                                             const IpatchFileIOFuncs *funcs);
    void                ipatch_file_get_iofuncs             (IpatchFile *file,
                                                             IpatchFileIOFuncs *out_funcs);
    void                ipatch_file_set_iofuncs_null        (IpatchFile *file);
    gboolean            ipatch_file_default_open_method     (IpatchFileHandle *handle,
                                                             const char *mode,
                                                             GError **err);
    void                ipatch_file_default_close_method    (IpatchFileHandle *handle);
    GIOStatus           ipatch_file_default_read_method     (IpatchFileHandle *handle,
                                                             gpointer buf,
                                                             guint size,
                                                             guint *bytes_read,
                                                             GError **err);
    GIOStatus           ipatch_file_default_write_method    (IpatchFileHandle *handle,
                                                             gconstpointer buf,
                                                             guint size,
                                                             GError **err);
    GIOStatus           ipatch_file_default_seek_method     (IpatchFileHandle *handle,
                                                             int offset,
                                                             GSeekType type,
                                                             GError **err);
    int                 ipatch_file_default_getfd_method    (IpatchFileHandle *handle);
    int                 ipatch_file_default_get_size_method (IpatchFile *file,
                                                             GError **err);

## Object Hierarchy

      GObject
       +----IpatchItem
             +----IpatchFile
                   +----IpatchDLSFile
                   +----IpatchSF2File
                   +----IpatchSndFile

## Properties

      "file-name"                gchar*                : Read / Write

## Description

Provides an abstraction of file data sources and file type identification.

## Details

### 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;

`IPATCH_FILE_FLAG_SWAP` | Swap multi-byte numbers?
`IPATCH_FILE_FLAG_BIG_ENDIAN` | Big endian file?
`IPATCH_FILE_FLAG_FREE_IOFUNCS` | Should ->iofuncs be freed?

### 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_IDENTIFY_ORDER_LAST` | Execute last (toward the end of the list)
`IPATCH_FILE_IDENTIFY_ORDER_DEFAULT` | Default execution order (no preference)
`IPATCH_FILE_IDENTIFY_ORDER_FIRST` | Execute first (toward the start of the list)

### 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

Returns : | The 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.

`file` : | File object to assign file name to
`file_name` : | File name or `NULL` to unset the file name

### ipatch_file_get_name ()

    char *              ipatch_file_get_name                (IpatchFile *file);

Gets the assigned file name from a file object.

`file` : | File object to get file name from
Returns : | The file name of the file object or `NULL` if not set. String should be freed when finished with it.

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

`file` : | File object to open from a file name.
`file_name` : | Name of file to open or `NULL` to use the file object's assigned file name (in which case it should not be `NULL`).
`mode` : | File open mode ("r" for read or "w" for write)
`err` : | Error information
Returns : | New file handle or `NULL` (in which case `err` may be set). The returned file handle is not multi-thread safe, but the file can be opened multiple times for this purpose.

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

`file` : | File object
`fd` : | File descriptor to assign to file object, or -1 to clear it
`close_on_finalize` : | `TRUE` if the descriptor should be closed when `file` is finalized, `FALSE` to leave it open

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

`file` : | File object
`iochan` : | IO channel to assign to `file` or `NULL` to clear it

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

`handle` : | File handle
Returns : | GIOChannel assigned to the `handle` or `NULL` if none (some derived IpatchFile types might not use io channels). Remember to unref it with `g_io_channel_unref()` when finished.

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

`handle` : | File handle
Returns : | File descriptor or -1 if not open or failed to get descriptor.

### ipatch_file_close ()

    void                ipatch_file_close                   (IpatchFileHandle *handle);

Close a file handle and free it.

`handle` : | File handle

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

`handle` : | File handle
Returns : | Position in file handle.

### 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).

`handle` : | File handle
`offset` : | Offset to add to the position counter (can be negative)

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

`handle` : | File handle
`buf` : | Buffer to read data into
`size` : | Amount of data to read, in bytes.
`err` : | A location to return an error of type GIOChannelError or `NULL`.
Returns : | `TRUE` on success (the requested `size` of data was read), `FALSE` otherwise

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

`handle` : | File handle
`buf` : | Buffer to read data into
`size` : | Amount of data to read, in bytes.
`bytes_read` : | Pointer to store number of bytes actually read or `NULL`.
`err` : | A location to return an error of type GIOChannelError or `NULL`.
Returns : | The status of the operation

### ipatch_file_write ()

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

Writes data to a file object.

`handle` : | File handle
`buf` : | Buffer of data to write
`size` : | Amount of data to write, in bytes.
`err` : | A location to return an error of type GIOChannelError or `NULL`.
Returns : | The status of the operation

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

`handle` : | File handle
`offset` : | Offset in bytes to seek from the position specified by `type`
`type` : | Position in file to seek from (see g_io_channel_seek_position for more details, only G_SEEK_CUR and G_SEEK_SET allowed).
`err` : | A location to return error info or `NULL`.
Returns : | `TRUE` on success, `FALSE` otherwise

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

`handle` : | File handle
`offset` : | Offset in bytes to seek from the position specified by `type`
`type` : | Position in file to seek from (see g_io_channel_seek_position for more details, only G_SEEK_CUR and G_SEEK_SET allowed).
`err` : | A location to return error info or `NULL`.
Returns : | The status of the operation

### ipatch_file_get_size ()

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

Get the size of a file object.

`file` : | File object to get size of
`err` : | Location to store error information
Returns : | File size or -1 on error or if operation unsupported by this file object (in which case `err` may be set)

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

`file` : | File object to identify type of
`err` : | Location to store error information
Returns : | The first IpatchFile derived type that had an "identify" method which returned `TRUE`, or 0 if unknown file type or error, in which case error information will be stored in `err` provided its not `NULL`.

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

`file` : | File object to identify type of
Returns : | The first IpatchFile derived type that had an "identify" method which returned `TRUE`, or 0 if unknown file type or error, in which case error information will be stored in `err` provided its not `NULL`.

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

`file_name` : | File name to identify and open
`err` : | Location to store error of type GIOChannelError
Returns : | The new opened handle of the identified type or `NULL` if unable to identify. Caller should free the handle with `ipatch_file_close()` when done using it, at which point the parent IpatchFile will be destroyed if no other reference is held (by calling `ipatch_file_handle_get_file()` for example).

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

`file` : | File object

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

`file` : | File object

### ipatch_file_read_u8 ()

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

Read an unsigned 8 bit integer from a file.

`file` : | File to read from
`val` : | Location to store value
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set).

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

`handle` : | File handle
`val` : | Location to store value
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set).

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

`handle` : | File handle
`val` : | Location to store value
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set).

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

`handle` : | File handle
`val` : | Location to store value
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set).

### ipatch_file_read_s8 ()

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

Read a signed 8 bit integer from a file.

`handle` : | File handle
`val` : | Location to store value
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set).

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

`handle` : | File handle
`val` : | Location to store value
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set).

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

`handle` : | File handle
`val` : | Location to store value
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set).

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

`handle` : | File handle
`val` : | Location to store value
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set).

### ipatch_file_write_u8 ()

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

Write an unsigned 8 bit integer to a file.

`handle` : | File handle
`val` : | Value to store
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set).

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

`handle` : | File handle
`val` : | Value to store
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set).

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

`handle` : | File handle
`val` : | Value to store
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set).

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

`handle` : | File handle
`val` : | Value to store
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set).

### ipatch_file_write_s8 ()

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

Write a signed 8 bit integer to a file.

`handle` : | File handle
`val` : | Value to store
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set).

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

`handle` : | File handle
`val` : | Value to store
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set).

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

`handle` : | File handle
`val` : | Value to store
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set).

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

`handle` : | File handle
`val` : | Value to store
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set).

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

`filebuf` : | Initialized file buffer structure
`size` : | Size of data to load
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` on error.

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

`handle` : | File handle with loaded data to read from
`buf` : | Buffer to copy data to
`size` : | Amount of data to copy in bytes

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

`handle` : | File handle to append buffered data to
`buf` : | Buffer to copy data from
`size` : | Amount of data to copy in bytes

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

`handle` : | File handle to append buffered data to
`c` : | Character to write
`size` : | Size of data to set

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

`handle` : | File handle with buffered data to write
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise

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

`handle` : | File handle
`offset` : | Offset to seek
`type` : | Seek type

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

`handle` : | File handle with loaded data
Returns : | The value.

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

`handle` : | File handle with loaded data
Returns : | The value.

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

`handle` : | File handle with loaded data
Returns : | The value.

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

`handle` : | File handle with loaded data
Returns : | The value.

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

`handle` : | File handle with loaded data
Returns : | The value.

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

`handle` : | File handle with loaded data
Returns : | The value.

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

`handle` : | File handle with loaded data
Returns : | The value.

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

`handle` : | File handle with loaded data
Returns : | The value.

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

`handle` : | File handle
`val` : | Value to write into file buffer

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

`handle` : | File handle
`val` : | Value to write into file buffer

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

`handle` : | File handle
`val` : | Value to write into file buffer

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

`handle` : | File handle
`val` : | Value to write into file buffer

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

`handle` : | File handle
`val` : | Value to write into file buffer

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

`handle` : | File handle
`val` : | Value to write into file buffer

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

`handle` : | File handle
`val` : | Value to write into file buffer

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

`handle` : | File handle
`val` : | Value to write into file buffer

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

`file` : | File object
`funcs` : | Static IO functions structure or `NULL` to set to defaults

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

`file` : | File object
`funcs` : | IO functions structure or `NULL` to set to defaults

### 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`.

`file` : | File object
`out_funcs` : | Location to store current IO functions to

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

`file` : | File object

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

`handle` : | File handle
`mode` : | File open mode
`err` : | Error info
Returns : | `TRUE` on success, `FALSE` otherwise

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

`handle` : | File handle

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

`handle` : | File handle
`buf` : | Buffer to store data to
`size` : | Size of data
`bytes_read` : | Number of bytes actually read
`err` : | Error info
Returns : | The status of the operation.

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

`handle` : | File handle
`buf` : | Buffer to read data from
`size` : | Size of data
`err` : | Error info
Returns : | The status of the operation.

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

`handle` : | File handle
`offset` : | Offset (depends on seek `type`)
`type` : | Seek type
`err` : | Error info
Returns : | The status of the operation.

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

`handle` : | File handle
Returns : | Unix file descriptor or -1 if no file descriptor or error.

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

`file` : | File object
`err` : | Error info
Returns : | File size or -1 on error (in which case `err` may be set).

## Property Details

### The `"file-name"` property

      "file-name"                gchar*                : Read / Write

File Name.

Default value: NULL