## MirageFragment MirageFragment — Fragment object. |

## Synopsis

    #include <mirage-fragment.h>

                        MirageFragment;
    struct              MirageFragmentClass;
    enum                MirageMainDataFormat;
    enum                MirageSubchannelDataFormat;
    gint                mirage_fragment_get_address         (MirageFragment *self);
    gint                mirage_fragment_get_length          (MirageFragment *self);
    const gchar *       mirage_fragment_main_data_get_filename
                                                            (MirageFragment *self);
    gint                mirage_fragment_main_data_get_format
                                                            (MirageFragment *self);
    guint64             mirage_fragment_main_data_get_offset
                                                            (MirageFragment *self);
    gint                mirage_fragment_main_data_get_size  (MirageFragment *self);
    void                mirage_fragment_main_data_set_format
                                                            (MirageFragment *self,
                                                             gint format);
    void                mirage_fragment_main_data_set_offset
                                                            (MirageFragment *self,
                                                             guint64 offset);
    void                mirage_fragment_main_data_set_size  (MirageFragment *self,
                                                             gint size);
    void                mirage_fragment_main_data_set_stream
                                                            (MirageFragment *self,
                                                             GInputStream *stream);
    gboolean            mirage_fragment_read_main_data      (MirageFragment *self,
                                                             gint address,
                                                             guint8 **buffer,
                                                             gint *length,
                                                             GError **error);
    gboolean            mirage_fragment_read_subchannel_data
                                                            (MirageFragment *self,
                                                             gint address,
                                                             guint8 **buffer,
                                                             gint *length,
                                                             GError **error);
    void                mirage_fragment_set_address         (MirageFragment *self,
                                                             gint address);
    void                mirage_fragment_set_length          (MirageFragment *self,
                                                             gint length);
    const gchar *       mirage_fragment_subchannel_data_get_filename
                                                            (MirageFragment *self);
    gint                mirage_fragment_subchannel_data_get_format
                                                            (MirageFragment *self);
    guint64             mirage_fragment_subchannel_data_get_offset
                                                            (MirageFragment *self);
    gint                mirage_fragment_subchannel_data_get_size
                                                            (MirageFragment *self);
    void                mirage_fragment_subchannel_data_set_format
                                                            (MirageFragment *self,
                                                             gint format);
    void                mirage_fragment_subchannel_data_set_offset
                                                            (MirageFragment *self,
                                                             guint64 offset);
    void                mirage_fragment_subchannel_data_set_size
                                                            (MirageFragment *self,
                                                             gint size);
    void                mirage_fragment_subchannel_data_set_stream
                                                            (MirageFragment *self,
                                                             GInputStream *stream);
    gboolean            mirage_fragment_use_the_rest_of_file
                                                            (MirageFragment *self,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----MirageObject
             +----MirageFragment

## Implemented Interfaces

MirageFragment implements MirageContextual.

## Signals

      "layout-changed"                                 : Run Last

## Description

MirageFragment object represents an interface between a MirageTrack and data stream(s) containing the data. It allows tracks to read main and subchannel data from the streams, which is then fed to sectors. When constructing a track, a parser will typically create and append at least one fragment.

A MirageFragment object is obtained using `g_object_new()` function. Both main data file stream and subchannel data file stream can be set using `mirage_fragment_main_data_set_stream()` and `mirage_fragment_subchannel_data_set_stream()` functions. If no streams are set, a fragment acts as a "NULL" fragment, and can be used to represent zero-filled pregaps and postgaps in tracks.

## Details

### MirageFragment

    typedef struct _MirageFragment MirageFragment;

All the fields in the MirageFragment structure are private to the MirageFragment implementation and should never be accessed directly.

### struct MirageFragmentClass

    struct MirageFragmentClass {
        MirageObjectClass parent_class;
    };

The class structure for the MirageFragment type.

MirageObjectClass `parent_class`; | the parent class

### enum MirageMainDataFormat

    typedef enum {
        MIRAGE_MAIN_DATA  = 0x01,
        MIRAGE_MAIN_AUDIO = 0x02,
        MIRAGE_MAIN_AUDIO_SWAP = 0x04,
    } MirageMainDataFormat;

Track file data formats.

`MIRAGE_MAIN_DATA` | binary data
`MIRAGE_MAIN_AUDIO` | audio data
`MIRAGE_MAIN_AUDIO_SWAP` | audio data that needs to be swapped

### enum MirageSubchannelDataFormat

    typedef enum {
        MIRAGE_SUBCHANNEL_INT = 0x01,
        MIRAGE_SUBCHANNEL_EXT = 0x02,

        MIRAGE_SUBCHANNEL_PW96_INT = 0x10,
        MIRAGE_SUBCHANNEL_PW96_LIN = 0x20,
        MIRAGE_SUBCHANNEL_RW96     = 0x40,
        MIRAGE_SUBCHANNEL_PQ16     = 0x80,
    } MirageSubchannelDataFormat;

Subchannel file data formats.

`MIRAGE_SUBCHANNEL_INT` | internal subchannel (i.e. included in track file)
`MIRAGE_SUBCHANNEL_EXT` | external subchannel (i.e. provided by separate file)
`MIRAGE_SUBCHANNEL_PW96_INT` | P-W subchannel, 96 bytes, interleaved
`MIRAGE_SUBCHANNEL_PW96_LIN` | P-W subchannel, 96 bytes, linear
`MIRAGE_SUBCHANNEL_RW96` | R-W subchannel, 96 bytes, deinterleaved
`MIRAGE_SUBCHANNEL_PQ16` | PQ subchannel, 16 bytes

### mirage_fragment_get_address ()

    gint                mirage_fragment_get_address         (MirageFragment *self);

Retrieves fragment's start address. The `address` is given in sectors.

### Note

Intended for internal use only.

`self` : | a MirageFragment
Returns : | start address

### mirage_fragment_get_length ()

    gint                mirage_fragment_get_length          (MirageFragment *self);

Retrieves fragment's length. The returned `length` is given in sectors.

### Note

Intended for internal use only.

`self` : | a MirageFragment
Returns : | length

### mirage_fragment_main_data_get_filename ()

    const gchar *       mirage_fragment_main_data_get_filename
                                                            (MirageFragment *self);

Retrieves filename of main data file.

`self` : | a MirageFragment
Returns : | pointer to main data file name string. The string belongs to object and should not be modified. [transfer none]

### mirage_fragment_main_data_get_format ()

    gint                mirage_fragment_main_data_get_format
                                                            (MirageFragment *self);

Retrieves main data file format.

`self` : | a MirageFragment
Returns : | main data file format

### mirage_fragment_main_data_get_offset ()

    guint64             mirage_fragment_main_data_get_offset
                                                            (MirageFragment *self);

Retrieves main data file offset.

`self` : | a MirageFragment
Returns : | main data file offset

### mirage_fragment_main_data_get_size ()

    gint                mirage_fragment_main_data_get_size  (MirageFragment *self);

Retrieves main data file sector size.

`self` : | a MirageFragment
Returns : | main data file sector size

### mirage_fragment_main_data_set_format ()

    void                mirage_fragment_main_data_set_format
                                                            (MirageFragment *self,
                                                             gint format);

Sets main data file format. `format` must be one of MirageMainDataFormat.

`self` : | a MirageFragment
`format` : | main data file format. [in]

### mirage_fragment_main_data_set_offset ()

    void                mirage_fragment_main_data_set_offset
                                                            (MirageFragment *self,
                                                             guint64 offset);

Sets main data file offset.

`self` : | a MirageFragment
`offset` : | main data file offset. [in]

### mirage_fragment_main_data_set_size ()

    void                mirage_fragment_main_data_set_size  (MirageFragment *self,
                                                             gint size);

Sets main data file sector size.

`self` : | a MirageFragment
`size` : | main data file sector size. [in]

### mirage_fragment_main_data_set_stream ()

    void                mirage_fragment_main_data_set_stream
                                                            (MirageFragment *self,
                                                             GInputStream *stream);

Sets main data stream.

`self` : | a MirageFragment
`stream` : | a GInputStream on main data file. [in][transfer full]

### mirage_fragment_read_main_data ()

    gboolean            mirage_fragment_read_main_data      (MirageFragment *self,
                                                             gint address,
                                                             guint8 **buffer,
                                                             gint *length,
                                                             GError **error);

Reads main channel data for sector at fragment-relative `address` (given in sectors). The buffer for reading data into is allocated by function and should be freed using `g_free()` when no longer needed. The pointer to buffer is stored into `buffer` and the length of read data is stored into `length`.

`self` : | a MirageFragment
`address` : | address. [in]
`buffer` : | location to store pointer to buffer with read data, or `NULL`. [out][allow-none][array length=length]
`length` : | location to store read data length. [out]
`error` : | location to store error, or `NULL`. [out][allow-none]
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_fragment_read_subchannel_data ()

    gboolean            mirage_fragment_read_subchannel_data
                                                            (MirageFragment *self,
                                                             gint address,
                                                             guint8 **buffer,
                                                             gint *length,
                                                             GError **error);

Reads subchannel data for sector at fragment-relative `address` (given in sectors). The buffer for reading data into is allocated by function and should be freed using `g_free()` when no longer needed. The pointer to buffer is stored into `buffer` and the length of read data is stored into `length`.

`self` : | a MirageFragment
`address` : | address. [in]
`buffer` : | location to store pointer to buffer with read data, or `NULL`. [out][allow-none][array length=length]
`length` : | location to store read data length. [out]
`error` : | location to store error, or `NULL`. [out][allow-none]
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_fragment_set_address ()

    void                mirage_fragment_set_address         (MirageFragment *self,
                                                             gint address);

Sets fragment's start address. The `address` is given in sectors.

### Note

Intended for internal use only.

### Note

Causes top-down change.

`self` : | a MirageFragment
`address` : | start address. [in]

### mirage_fragment_set_length ()

    void                mirage_fragment_set_length          (MirageFragment *self,
                                                             gint length);

Sets fragment's length. The `length` is given in sectors.

### Note

Intended for internal use only.

### Note

Causes bottom-up change.

`self` : | a MirageFragment
`length` : | length. [in]

### mirage_fragment_subchannel_data_get_filename ()

    const gchar *       mirage_fragment_subchannel_data_get_filename
                                                            (MirageFragment *self);

Retrieves subchannel data file name.

`self` : | a MirageFragment
Returns : | pointer to subchannel data file name string. The string belongs to object and should not be modified. [transfer none]

### mirage_fragment_subchannel_data_get_format ()

    gint                mirage_fragment_subchannel_data_get_format
                                                            (MirageFragment *self);

Retrieves subchannel data file format.

`self` : | a MirageFragment
Returns : | subchannel data file format

### mirage_fragment_subchannel_data_get_offset ()

    guint64             mirage_fragment_subchannel_data_get_offset
                                                            (MirageFragment *self);

Retrieves subchannel data file offset.

`self` : | a MirageFragment
Returns : | subchannel data file offset

### mirage_fragment_subchannel_data_get_size ()

    gint                mirage_fragment_subchannel_data_get_size
                                                            (MirageFragment *self);

Retrieves subchannel data file sector size.

`self` : | a MirageFragment
Returns : | subchannel data file sector size

### mirage_fragment_subchannel_data_set_format ()

    void                mirage_fragment_subchannel_data_set_format
                                                            (MirageFragment *self,
                                                             gint format);

Sets subchannel data file format. `format` must be a combination of MirageSubchannelDataFormat.

`self` : | a MirageFragment
`format` : | subchannel data file format. [in]

### mirage_fragment_subchannel_data_set_offset ()

    void                mirage_fragment_subchannel_data_set_offset
                                                            (MirageFragment *self,
                                                             guint64 offset);

Sets subchannel data file offset.

`self` : | a MirageFragment
`offset` : | subchannel data file offset. [in]

### mirage_fragment_subchannel_data_set_size ()

    void                mirage_fragment_subchannel_data_set_size
                                                            (MirageFragment *self,
                                                             gint size);

Sets subchannel data file sector size.

`self` : | a MirageFragment
`size` : | subchannel data file sector size. [in]

### mirage_fragment_subchannel_data_set_stream ()

    void                mirage_fragment_subchannel_data_set_stream
                                                            (MirageFragment *self,
                                                             GInputStream *stream);

Sets subchannel data stream.

`self` : | a MirageFragment
`stream` : | a GInputStream on subchannel data file. [in][transfer full]

### mirage_fragment_use_the_rest_of_file ()

    gboolean            mirage_fragment_use_the_rest_of_file
                                                            (MirageFragment *self,
                                                             GError **error);

Uses the rest of data file. It automatically calculates and sets fragment's length.

`self` : | a MirageFragment
`error` : | location to store error, or `NULL`. [out][allow-none]
Returns : | `TRUE` on success, `FALSE` on failure

## Signal Details

### The `"layout-changed"` signal

    void                user_function                      (MirageFragment *fragment,
                                                            gpointer        user_data)      : Run Last

Emitted when a layout of MirageFragment changed in a way that causes a bottom-up change.

`fragment` : | a MirageFragment
`user_data` : | user data set when the signal handler was connected.