## IpatchRiff IpatchRiff — RIFF file parser/composer object |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

                        IpatchRiffChunk;
    enum                IpatchRiffStatus;
    enum                IpatchRiffMode;
                        IpatchRiff;
    #define             IPATCH_RIFF_NEED_SWAP               (riff)
    #define             IPATCH_RIFF_BIG_ENDIAN              (riff)
    enum                IpatchRiffChunkType;
    #define             IPATCH_RIFF_ERROR
    enum                IpatchRiffError;
    #define             IPATCH_FOURCC                       (c1, c2, c3, c4)
    #define             IPATCH_FOURCC_RIFF
    #define             IPATCH_FOURCC_RIFX
    #define             IPATCH_FOURCC_LIST
    #define             IPATCH_RIFF_HEADER_SIZE
    #define             IPATCH_RIFF_FOURCC_SIZE
    #define             IPATCH_RIFF_LIST_HEADER_SIZE
    #define             IPATCH_RIFF_WAVE_FMT_PCM
    #define             IPATCH_RIFF_WAVE_FMT_FLOAT
    GQuark              ipatch_riff_error_quark             (void);
    IpatchRiff *        ipatch_riff_new                     (IpatchFileHandle *handle);
    void                ipatch_riff_set_file_handle         (IpatchRiff *riff,
                                                             IpatchFileHandle *handle);
    IpatchFileHandle *  ipatch_riff_get_file_handle         (IpatchRiff *riff);
    int                 ipatch_riff_get_chunk_level         (IpatchRiff *riff);
    IpatchRiffChunk *   ipatch_riff_get_chunk_array         (IpatchRiff *riff,
                                                             int *count);
    IpatchRiffChunk *   ipatch_riff_get_chunk               (IpatchRiff *riff,
                                                             int level);
    guint32             ipatch_riff_get_total_size          (IpatchRiff *riff);
    guint32             ipatch_riff_get_position            (IpatchRiff *riff);
    void                ipatch_riff_push_state              (IpatchRiff *riff);
    gboolean            ipatch_riff_pop_state               (IpatchRiff *riff,
                                                             GError **err);
    IpatchRiffChunk *   ipatch_riff_start_read              (IpatchRiff *riff,
                                                             GError **err);
    IpatchRiffChunk *   ipatch_riff_start_read_chunk        (IpatchRiff *riff,
                                                             GError **err);
    IpatchRiffChunk *   ipatch_riff_read_chunk_verify       (IpatchRiff *riff,
                                                             IpatchRiffChunkType type,
                                                             guint32 id,
                                                             GError **err);
    IpatchRiffChunk *   ipatch_riff_read_chunk              (IpatchRiff *riff,
                                                             GError **err);
    #define             ipatch_riff_write_list_chunk        (parser, id, err)
    #define             ipatch_riff_write_sub_chunk         (parser, id, err)
    gboolean            ipatch_riff_write_chunk             (IpatchRiff *riff,
                                                             IpatchRiffChunkType type,
                                                             guint32 id,
                                                             GError **err);
    #define             ipatch_riff_end_chunk               (parser, err)
    gboolean            ipatch_riff_close_chunk             (IpatchRiff *riff,
                                                             int level,
                                                             GError **err);
    #define             ipatch_riff_skip_chunk              (parser, err)
    gboolean            ipatch_riff_skip_chunks             (IpatchRiff *riff,
                                                             guint count,
                                                             GError **err);
    gboolean            ipatch_riff_get_error               (IpatchRiff *riff,
                                                             GError **err);
    char *              ipatch_riff_message_detail          (IpatchRiff *riff,
                                                             int level,
                                                             const char *format,
                                                             ...);

## Object Hierarchy

      GObject
       +----IpatchRiff
             +----IpatchDLSReader
             +----IpatchDLSWriter
             +----IpatchSF2Reader
             +----IpatchSF2Writer

## Description

A RIFF file parser/composer. Used for DLS, SoundFont and GigaSampler files.

## Details

### IpatchRiffChunk

    typedef struct {
      IpatchRiffChunkType type;	/* type of chunk */
      guint32 id;	  /* chunk ID in integer format for easy comparison */
      char idstr[4];		/* four character chunk ID string */
      gint32 position; /* current position in chunk (read or write mode) */
      guint32 size;			/* size of chunk (read mode only) */
      guint32 filepos;              /* Position in file object of chunk data */
    } IpatchRiffChunk;

### enum IpatchRiffStatus

    typedef enum
    {
      IPATCH_RIFF_STATUS_FAIL = 0,	/* error occured */
      IPATCH_RIFF_STATUS_BEGIN,	/* parsing has not yet began */
      IPATCH_RIFF_STATUS_FINISHED,	/* no more parsing to be done */
      IPATCH_RIFF_STATUS_NORMAL,	/* normal status */
      IPATCH_RIFF_STATUS_CHUNK_END	/* end of a chunk */
    } IpatchRiffStatus;

### enum IpatchRiffMode

    typedef enum
    {
      IPATCH_RIFF_READ,
      IPATCH_RIFF_WRITE
    } IpatchRiffMode;

### IpatchRiff

    typedef struct _IpatchRiff IpatchRiff;

### IPATCH_RIFF_NEED_SWAP()

    #define IPATCH_RIFF_NEED_SWAP(riff)  IPATCH_FILE_NEED_SWAP (riff->handle->file)

### IPATCH_RIFF_BIG_ENDIAN()

    #define IPATCH_RIFF_BIG_ENDIAN(riff) IPATCH_FILE_BIG_ENDIAN (riff->handle->file)

### enum IpatchRiffChunkType

    typedef enum
    {
      IPATCH_RIFF_CHUNK_RIFF,	/* toplevel "RIFF" (or "RIFX") list chunk */
      IPATCH_RIFF_CHUNK_LIST,	/* a "LIST" chunk */
      IPATCH_RIFF_CHUNK_SUB		/* a sub chunk */
    } IpatchRiffChunkType;

### IPATCH_RIFF_ERROR

    #define IPATCH_RIFF_ERROR  ipatch_riff_error_quark()

### enum IpatchRiffError

    typedef enum
    {
      IPATCH_RIFF_ERROR_NOT_RIFF,	/* not a RIFF file */
      IPATCH_RIFF_ERROR_UNEXPECTED_ID, /* unexpected chunk ID */
      IPATCH_RIFF_ERROR_UNEXPECTED_CHUNK_END,  /* unexpected LIST chunk end */
      IPATCH_RIFF_ERROR_INVALID_ID, /* invalid chunk FOURCC ID */
      IPATCH_RIFF_ERROR_ODD_SIZE,	/* chunk size is ODD */
      IPATCH_RIFF_ERROR_SIZE_EXCEEDED, /* chunk size exceeded */

      /* convenience errors - not used by the riff object itself */
      IPATCH_RIFF_ERROR_SIZE_MISMATCH, /* chunk size mismatch */
      IPATCH_RIFF_ERROR_INVALID_DATA /* generic invalid data error */
    } IpatchRiffError;

### IPATCH_FOURCC()

    #define             IPATCH_FOURCC(c1, c2, c3, c4)

### IPATCH_FOURCC_RIFF

    #define IPATCH_FOURCC_RIFF IPATCH_FOURCC ('R','I','F','F')

### IPATCH_FOURCC_RIFX

    #define IPATCH_FOURCC_RIFX IPATCH_FOURCC ('R','I','F','X') /* big endian */

### IPATCH_FOURCC_LIST

    #define IPATCH_FOURCC_LIST IPATCH_FOURCC ('L','I','S','T')

### IPATCH_RIFF_HEADER_SIZE

    #define IPATCH_RIFF_HEADER_SIZE 8 /* size of RIFF chunk headers (ID + size) */

### IPATCH_RIFF_FOURCC_SIZE

    #define IPATCH_RIFF_FOURCC_SIZE 4 /* RIFF FOURCC ID size */

### IPATCH_RIFF_LIST_HEADER_SIZE

    #define             IPATCH_RIFF_LIST_HEADER_SIZE

### IPATCH_RIFF_WAVE_FMT_PCM

    #define IPATCH_RIFF_WAVE_FMT_PCM   0x1

### IPATCH_RIFF_WAVE_FMT_FLOAT

    #define IPATCH_RIFF_WAVE_FMT_FLOAT 0x3

### ipatch_riff_error_quark ()

    GQuark              ipatch_riff_error_quark             (void);

### ipatch_riff_new ()

    IpatchRiff *        ipatch_riff_new                     (IpatchFileHandle *handle);

Create a new RIFF file riff/composer object

`handle` : | File object handle to parse or `NULL` to set later, the handle will be taken over by the riff object and closed when finalized.
Returns : | The RIFF object

### ipatch_riff_set_file_handle ()

    void                ipatch_riff_set_file_handle         (IpatchRiff *riff,
                                                             IpatchFileHandle *handle);

Set the file object handle of a RIFF object. The handle is taken over by the riff object and will be closed when finalized.

`riff` : | RIFF object
`handle` : | File object handle to assign

### ipatch_riff_get_file_handle ()

    IpatchFileHandle *  ipatch_riff_get_file_handle         (IpatchRiff *riff);

### ipatch_riff_get_chunk_level ()

    int                 ipatch_riff_get_chunk_level         (IpatchRiff *riff);

Gets the current chunk level count (number of embedded chunks) currently being processed in a RIFF file.

`riff` : | RIFF object
Returns : | Chunk level count (0 = no open chunks)

### ipatch_riff_get_chunk_array ()

    IpatchRiffChunk *   ipatch_riff_get_chunk_array         (IpatchRiff *riff,
                                                             int *count);

Gets the array of open chunk info structures.

`riff` : | RIFF object
`count` : | Location to store the number of elements in the returned array
Returns : | Array of IpatchRiffChunk structures or `NULL` if no chunks being processed (processing hasn't started). The returned array is internal and should not be modified or freed. Also note that the array is valid only while the chunk state is unchanged (riff object or file operations). The number of elements in the array is stored in `count`.

### ipatch_riff_get_chunk ()

    IpatchRiffChunk *   ipatch_riff_get_chunk               (IpatchRiff *riff,
                                                             int level);

Get the chunk at the specified `level` from a RIFF `riff` chunk state array.

`riff` : | RIFF object
`level` : | Level of chunk to get (-1 for current chunk)
Returns : | Pointer to the chunk or `NULL` if invalid level. The returned chunk is internal and should not be modified or freed. Also note that the chunk is valid only while the chunk state is unchanged (riff object or file operations).

### ipatch_riff_get_total_size ()

    guint32             ipatch_riff_get_total_size          (IpatchRiff *riff);

Get total size of toplevel chunk. This is a convenience function that just adds the size of the toplevel chunk and its header, the actual file object size is not checked.

`riff` : | RIFF object
Returns : | Size of toplevel chunk + header size, in bytes. Actual file size is not checked.

### ipatch_riff_get_position ()

    guint32             ipatch_riff_get_position            (IpatchRiff *riff);

Get current position in the toplevel RIFF chunk (including header, i.e., the file position).

`riff` : | RIFF object
Returns : | The current offset, in bytes, into the toplevel RIFF chunk (including header).

### ipatch_riff_push_state ()

    void                ipatch_riff_push_state              (IpatchRiff *riff);

Pushes the current file position and chunk state onto the state stack. This state can be later restored to return to the same position in a RIFF file.

`riff` : | RIFF object

### ipatch_riff_pop_state ()

    gboolean            ipatch_riff_pop_state               (IpatchRiff *riff,
                                                             GError **err);

Pops the most recent state pushed onto the state stack. This causes the position in the RIFF file stored by the state to be restored.

`riff` : | RIFF object
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise which is fatal

### ipatch_riff_start_read ()

    IpatchRiffChunk *   ipatch_riff_start_read              (IpatchRiff *riff,
                                                             GError **err);

Start parsing the `riff` file object as if it were at the beginning of a RIFF file. Clears any current chunk state, loads a chunk and ensures that it has the "RIFF" or "RIFX" ID. If this call is sucessful there will be one chunk on the chunk stack with the secondary ID of the RIFF chunk. If it is desirable to process a chunk that is not the beginning of a RIFF file, `ipatch_riff_start_read_chunk()` can be used. This function will also automatically enable byte order swapping if needed.

`riff` : | RIFF object
`err` : | Location to store error info or `NULL`
Returns : | Pointer to the opened RIFF chunk or `NULL` on error. The returned chunk is internal and should not be modified or freed. Also note that the chunk is valid only while the chunk state is unchanged (riff object or file operations).

### ipatch_riff_start_read_chunk ()

    IpatchRiffChunk *   ipatch_riff_start_read_chunk        (IpatchRiff *riff,
                                                             GError **err);

Start parsing the `riff` file object at an arbitrary chunk. Clears any current chunk state and loads a chunk. If this call is sucessful there will be one chunk on the chunk stack. If it is desirable to start processing from the beginning of a RIFF file `ipatch_riff_start_read()` should be used instead. An end of file condition is considered an error. Note that it is up to the caller to ensure byte order swapping is enabled, if needed.

`riff` : | RIFF object
`err` : | Location to store error info or `NULL`
Returns : | Pointer to the opened RIFF chunk or `NULL` on error. The returned chunk is internal and should not be modified or freed. Also note that the chunk is valid only while the chunk state is unchanged (riff object or file operations).

### ipatch_riff_read_chunk_verify ()

    IpatchRiffChunk *   ipatch_riff_read_chunk_verify       (IpatchRiff *riff,
                                                             IpatchRiffChunkType type,
                                                             guint32 id,
                                                             GError **err);

Like `ipatch_riff_read_chunk()` but ensures that the new chunk matches a specific type and ID. If the chunk is not the expected chunk or no more chunks in current list chunk, it is considered an error. `ipatch_riff_close_chunk()` should be called when finished parsing the opened chunk.

`riff` : | RIFF object
`type` : | Expected chunk type
`id` : | Expected chunk ID
`err` : | Location to store error info or `NULL`
Returns : | Pointer to new opened chunk or `NULL` if current chunk has ended or on error. Returned chunk pointer is internal and should not be modified or freed. Also note that the chunk is valid only while the chunk state is unchanged (riff object or file operations).

### ipatch_riff_read_chunk ()

    IpatchRiffChunk *   ipatch_riff_read_chunk              (IpatchRiff *riff,
                                                             GError **err);

Parse next RIFF chunk header. The `ipatch_riff_close_chunk()` function should be called at the end of parsing a chunk, otherwise this function will return NULL if the current chunk has ended. When the first RIFF chunk is read the IPATCH_RIFF_FLAG_BIG_ENDIAN flag is cleared or set depending on if its RIFF or RIFX respectively, endian swapping is also enabled if the file uses non-native endian format to the host.

`riff` : | RIFF object
`err` : | Location to store error info or `NULL`
Returns : | Pointer to new opened chunk or `NULL` if current chunk has ended or on error. Returned chunk pointer is internal and should not be modified or freed. Also note that the chunk is valid only while the chunk state is unchanged (riff object or file operations).

### ipatch_riff_write_list_chunk()

    #define             ipatch_riff_write_list_chunk(parser, id, err)

### ipatch_riff_write_sub_chunk()

    #define             ipatch_riff_write_sub_chunk(parser, id, err)

### ipatch_riff_write_chunk ()

    gboolean            ipatch_riff_write_chunk             (IpatchRiff *riff,
                                                             IpatchRiffChunkType type,
                                                             guint32 id,
                                                             GError **err);

Opens a new chunk and writes a chunk header to the file object in `riff`. The size field of the chunk is set to 0 and will be filled in when the chunk is closed (see `ipatch_riff_close_chunk()`).

`riff` : | RIFF object
`type` : | Chunk type (RIFF, LIST, or SUB)
`id` : | Chunk ID (secondary ID for RIFF and LIST chunks)
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise.

### ipatch_riff_end_chunk()

    #define             ipatch_riff_end_chunk(parser, err)

### ipatch_riff_close_chunk ()

    gboolean            ipatch_riff_close_chunk             (IpatchRiff *riff,
                                                             int level,
                                                             GError **err);

Closes the chunk specified by `level` and all its children (if any).

In write mode the chunk size is filled in for chunks that get closed and therefore the file object of `riff` must be seekable (anyone need non-seekable RIFF writing?). The chunk size is padded to an even number if necessary (by writing a NULL byte).

Upon successful completion the file position will be where it was prior to the call (write mode) or at the beginning of the next chunk (read mode). There will be `level` open chunks (or previous chunk count - 1 if `level` == -1). In read mode the status will be IPATCH_RIFF_STATUS_NORMAL if open chunks remain or IPATCH_RIFF_STATUS_FINISHED if toplevel chunk was closed. The status is not modified in write mode.

`riff` : | RIFF object
`level` : | Level of chunk to close (-1 for current chunk)
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise.

### ipatch_riff_skip_chunk()

    #define             ipatch_riff_skip_chunk(parser, err)

### ipatch_riff_skip_chunks ()

    gboolean            ipatch_riff_skip_chunks             (IpatchRiff *riff,
                                                             guint count,
                                                             GError **err);

Skips RIFF chunks at the current chunk level (children of the current chunk).

`riff` : | RIFF object
`count` : | Number of chunks to skip
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise

### ipatch_riff_get_error ()

    gboolean            ipatch_riff_get_error               (IpatchRiff *riff,
                                                             GError **err);

Gets error information from a RIFF object.

`riff` : | RIFF object
`err` : | Location to store error info
Returns : | `FALSE` if status is a IPATCH_RIFF_STATUS_FAIL condition and info can be found in `err`, `TRUE` if no error has occured.

### ipatch_riff_message_detail ()

    char *              ipatch_riff_message_detail          (IpatchRiff *riff,
                                                             int level,
                                                             const char *format,
                                                             ...);

Generates a detailed message, including current position in RIFF file and a chunk trace back. Useful for debugging purposes.

`riff` : | RIFF object
`level` : | Chunk level to generate detail for (-1 for current chunk)
`format` : | Printf style format string of message to display at beginning of riff detail
`...` : | Arguments for `msg` string
Returns : | Detailed message string which is internal to `riff` and should not be modified or freed. Also note that this string is only valid until the next call to this function.