IpatchFile

IpatchFile — File abstraction object

Stability Level

Stable, unless otherwise indicated

Functions

#define IPATCH_FILE_NEED_SWAP()
#define IPATCH_FILE_BIG_ENDIAN()
#define IPATCH_FILE_SWAP16()
#define IPATCH_FILE_SWAP32()
#define IPATCH_FILE_SWAP64()
IpatchFile * ipatch_file_new ()
IpatchFile * ipatch_file_pool_new ()
IpatchFile * ipatch_file_pool_lookup ()
void ipatch_file_ref_from_object ()
void ipatch_file_unref_from_object ()
gboolean ipatch_file_test_ref_object ()
IpatchList * ipatch_file_get_refs ()
IpatchList * ipatch_file_get_refs_by_type ()
void ipatch_file_set_name ()
char * ipatch_file_get_name ()
gboolean ipatch_file_rename ()
gboolean ipatch_file_unlink ()
gboolean ipatch_file_replace ()
IpatchFileHandle * ipatch_file_open ()
void ipatch_file_assign_fd ()
void ipatch_file_assign_io_channel ()
GIOChannel * ipatch_file_get_io_channel ()
int ipatch_file_get_fd ()
void ipatch_file_close ()
guint ipatch_file_get_position ()
void ipatch_file_update_position ()
gboolean ipatch_file_read ()
GIOStatus ipatch_file_read_eof ()
gboolean ipatch_file_write ()
#define ipatch_file_skip()
gboolean ipatch_file_seek ()
GIOStatus ipatch_file_seek_eof ()
int ipatch_file_get_size ()
GType ipatch_file_identify ()
GType ipatch_file_identify_name ()
GType ipatch_file_identify_by_ext ()
IpatchFileHandle * ipatch_file_identify_open ()
IpatchFile * ipatch_file_identify_new ()
void ipatch_file_set_little_endian ()
void ipatch_file_set_big_endian ()
gboolean ipatch_file_read_u8 ()
gboolean ipatch_file_read_u16 ()
gboolean ipatch_file_read_u32 ()
gboolean ipatch_file_read_u64 ()
gboolean ipatch_file_read_s8 ()
gboolean ipatch_file_read_s16 ()
gboolean ipatch_file_read_s32 ()
gboolean ipatch_file_read_s64 ()
gboolean ipatch_file_write_u8 ()
gboolean ipatch_file_write_u16 ()
gboolean ipatch_file_write_u32 ()
gboolean ipatch_file_write_u64 ()
gboolean ipatch_file_write_s8 ()
gboolean ipatch_file_write_s16 ()
gboolean ipatch_file_write_s32 ()
gboolean ipatch_file_write_s64 ()
gboolean ipatch_file_buf_load ()
void ipatch_file_buf_read ()
void ipatch_file_buf_write ()
#define ipatch_file_buf_zero()
void ipatch_file_buf_memset ()
void ipatch_file_buf_set_size ()
gboolean ipatch_file_buf_commit ()
#define ipatch_file_buf_skip()
void ipatch_file_buf_seek ()
guint8 ipatch_file_buf_read_u8 ()
guint16 ipatch_file_buf_read_u16 ()
guint32 ipatch_file_buf_read_u32 ()
guint64 ipatch_file_buf_read_u64 ()
gint8 ipatch_file_buf_read_s8 ()
gint16 ipatch_file_buf_read_s16 ()
gint32 ipatch_file_buf_read_s32 ()
gint64 ipatch_file_buf_read_s64 ()
void ipatch_file_buf_write_u8 ()
void ipatch_file_buf_write_u16 ()
void ipatch_file_buf_write_u32 ()
void ipatch_file_buf_write_u64 ()
void ipatch_file_buf_write_s8 ()
void ipatch_file_buf_write_s16 ()
void ipatch_file_buf_write_s32 ()
void ipatch_file_buf_write_s64 ()
void ipatch_file_set_iofuncs_static ()
void ipatch_file_set_iofuncs ()
void ipatch_file_get_iofuncs ()
void ipatch_file_set_iofuncs_null ()
gboolean ipatch_file_default_open_method ()
void ipatch_file_default_close_method ()
GIOStatus ipatch_file_default_read_method ()
GIOStatus ipatch_file_default_write_method ()
GIOStatus ipatch_file_default_seek_method ()
int ipatch_file_default_getfd_method ()
int ipatch_file_default_get_size_method ()

Properties

char * file-name Read / Write

Types and Values

Object Hierarchy

    GBoxed
    ╰── IpatchFileHandle
    GObject
    ╰── IpatchItem
        ╰── IpatchFile
            ├── IpatchDLSFile
            ├── IpatchSF2File
            ├── IpatchSLIFile
            ╰── IpatchSndFile

Description

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

Functions

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_file_new ()

IpatchFile *
ipatch_file_new (void);

Create a new file object

Returns

The new file object


ipatch_file_pool_new ()

IpatchFile *
ipatch_file_pool_new (const char *file_name,
                      gboolean *created);

Lookup existing file object from file pool by file name or create a new one if not open.

Parameters

file_name

File name (converted to an absolute file name if it isn't already)

 

created

Location to store TRUE if file object was newly created, FALSE if not (NULL to ignore).

[out][optional]

Returns

File object with the assigned file_name and an added reference which the caller owns

Since: 1.1.0


ipatch_file_pool_lookup ()

IpatchFile *
ipatch_file_pool_lookup (const char *file_name);

Lookup an existing file object in the file pool, by file name. Does not create a new object, if not found, like ipatch_file_pool_new() does.

Parameters

file_name

File name to lookup existing file object for

 

Returns

Matching file object with a reference that the caller owns or NULL if not found.

[transfer full]

Since: 1.1.0


ipatch_file_ref_from_object ()

void
ipatch_file_ref_from_object (IpatchFile *file,
                             GObject *object);

Reference a file object from another object and keep track of the external reference (using a GWeakRef). References can be obtained with ipatch_file_get_refs(). Use ipatch_file_unref_from_object() to remove the reference, although the registration will be removed regardless at some point if object gets destroyed and ipatch_file_get_refs() or ipatch_file_get_refs_by_type() is called.

Parameters

file

File object to add a reference to (g_object_ref() called)

 

object

Object which is referencing the file

 

Since: 1.1.0


ipatch_file_unref_from_object ()

void
ipatch_file_unref_from_object (IpatchFile *file,
                               GObject *object);

Remove a reference previously registered with ipatch_file_ref_from_object(). This will get done eventually if object gets destroyed and ipatch_file_get_refs() or ipatch_file_get_refs_by_type() is called, however.

Parameters

file

File object to remove a reference from (g_object_unref() called)

 

object

Object which is unreferencing the file

 

Since: 1.1.0


ipatch_file_test_ref_object ()

gboolean
ipatch_file_test_ref_object (IpatchFile *file,
                             GObject *object);

Check if a given object is referencing file . Must have been referenced with ipatch_file_ref_from_object().

Parameters

file

File object to test reference to

 

object

Object to test for reference to file

 

Returns

TRUE if object references file , FALSE otherwise

Since: 1.1.0


ipatch_file_get_refs ()

IpatchList *
ipatch_file_get_refs (IpatchFile *file);

Get list of objects referencing a file object. NOTE: A side effect of calling this function is that any references from destroyed objects are removed (if ipatch_file_unref_from_object() was not used).

Parameters

file

File object to get external references of

 

Returns

New object list which caller owns a reference to, unreference when finished using it.

[transfer full]

Since: 1.1.0


ipatch_file_get_refs_by_type ()

IpatchList *
ipatch_file_get_refs_by_type (IpatchFile *file,
                              GType type);

Like ipatch_file_get_refs() but only returns objects matching a given type or a descendant thereof.

Parameters

file

File object to get external references of

 

type

Object type to match (or a descendant thereof) or G_TYPE_NONE to match any type

 

Returns

New object list which caller owns a reference to, unreference when finished using it.

[transfer full]

Since: 1.1.0


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.

Parameters

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.

Parameters

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_rename ()

gboolean
ipatch_file_rename (IpatchFile *file,
                    const char *new_name,
                    GError **err);

Physically rename the file referenced by a file object. The given file object must have a file name assigned and no file descriptor or I/O channel. On Windows, the file must also not have any open handles. If a file with new_name already exists, it will be replaced and should not be referenced by any file object.

Parameters

file

File object to rename

 

new_name

New file name (can be a full path to move the file)

 

err

Location to store error info or NULL to ignore

 

Returns

TRUE on success, FALSE otherwise (in which case err may be set)

Since: 1.1.0


ipatch_file_unlink ()

gboolean
ipatch_file_unlink (IpatchFile *file,
                    GError **err);

Physically delete the file referenced by a file object. The given file object must have a file name assigned and no file descriptor or I/O channel. On Windows, the file must also not have any open handles. The file object will remain alive, but the underlying file will be unlinked.

Parameters

file

File object to rename

 

err

Location to store error info or NULL to ignore

 

Returns

TRUE on success, FALSE otherwise (in which case err may be set)

Since: 1.1.0


ipatch_file_replace ()

gboolean
ipatch_file_replace (IpatchFile *newfile,
                     IpatchFile *oldfile,
                     GError **err);

Replace one file object with another. After successful execution of this function oldfile will have an unset file name, newfile will be assigned what was the oldfile name, and the file data of the old file on the filesystem will have been replaced by new file.

NOTE: On Windows both files must not have any open file handles.

NOTE: In the event an error occurs, recovery will be attempted, but may also fail, resulting in loss of oldfile data.

Parameters

newfile

New file to replace the oldfile with (must have an assigned “file-name” property)

 

oldfile

The old file to replace (must have an assigned “file-name” property)

 

err

Location to store error info or NULL to ignore

 

Returns

TRUE on success, FALSE otherwise (in which case err may be set)

Since: 1.1.0


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.

Parameters

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

[nullable]

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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.

Parameters

handle

File handle

 

buf

Buffer to read data into.

[out][array length=size][element-type guint8]

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.

Parameters

handle

File handle

 

buf

Buffer to read data into.

[out][array length=size][element-type guint8]

size

Amount of data to read, in bytes.

 

bytes_read

Pointer to store number of bytes actually read or NULL.

[out][optional]

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.

Parameters

handle

File handle

 

buf

Buffer of data to write.

[array length=size][element-type guint8]

size

Amount of data to write, in bytes.

 

err

A location to return an error of type GIOChannelError or NULL.

 

Returns

TRUE on success, FALSE otherwise


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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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_name ()

GType
ipatch_file_identify_name (const char *filename,
                           GError **err);

Like ipatch_file_identify() but uses a file name for convenience.

Parameters

filename

Name of file 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.

Since: 1.1.0


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.

Parameters

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.

Parameters

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.


ipatch_file_identify_new ()

IpatchFile *
ipatch_file_identify_new (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 returned.

Parameters

file_name

File name to identify and create file object for

 

err

Location to store error of type GIOChannelError

 

Returns

The new file of the identified type or NULL if unable to identify. Caller owns a reference and should remove it when done using it.

Since: 1.1.0


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.

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

handle

File handle

 

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.

Parameters

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. Buffer is expanded if necessary (since version 1.1.0). Data will not actually be written to file till ipatch_file_buf_commit() is called.

Parameters

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,
                        unsigned char c,
                        guint size);

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

Parameters

handle

File handle to set buffered data of

 

c

Character to write

 

size

Size of data to set

 

ipatch_file_buf_set_size ()

void
ipatch_file_buf_set_size (IpatchFileHandle *handle,
                          guint size);

Sets the size of the buffer of handle to size bytes. The buffer is expanded without initializing the newly allocated part or truncated as necessary discarding any content over the new size. The current position is updated to point to the end of the buffer if it would point outside the new size of the buffer after truncating it.

Parameters

handle

File handle to adjust buffer of

 

size

New size of buffer

 

Since: 1.1.0


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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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 .

Parameters

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.

Parameters

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.

[skip]

Parameters

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.

[skip]

Parameters

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.

[skip]

Parameters

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.

[skip]

Parameters

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.

[skip]

Parameters

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.

[skip]

Parameters

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.

[skip]

Parameters

file

File object

 

err

Error info

 

Returns

File size or -1 on error (in which case err may be set).

Types and Values

struct IpatchFileIOFuncs

struct IpatchFileIOFuncs {
    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 */
};

enum IpatchFileFlags

Members

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

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.

Members

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)

struct IpatchFileHandle

struct IpatchFileHandle {
    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 */
};

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

Property Details

The “file-name” property

  “file-name”                char *

File Name.

Owner: IpatchFile

Flags: Read / Write

Default value: NULL