MirageFragment: libMirage Reference Manual

## MirageFragment MirageFragment — Fragment object. |

## Functions

gboolean | mirage_fragment_contains_address ()
gint | mirage_fragment_get_address ()
gint | mirage_fragment_get_length ()
gboolean | mirage_fragment_is_writable ()
const gchar * | mirage_fragment_main_data_get_filename ()
gint | mirage_fragment_main_data_get_format ()
guint64 | mirage_fragment_main_data_get_offset ()
gint | mirage_fragment_main_data_get_size ()
void | mirage_fragment_main_data_set_format ()
void | mirage_fragment_main_data_set_offset ()
void | mirage_fragment_main_data_set_size ()
void | mirage_fragment_main_data_set_stream ()
gboolean | mirage_fragment_read_main_data ()
gboolean | mirage_fragment_write_main_data ()
gboolean | mirage_fragment_read_subchannel_data ()
gboolean | mirage_fragment_write_subchannel_data ()
void | mirage_fragment_set_address ()
void | mirage_fragment_set_length ()
const gchar * | mirage_fragment_subchannel_data_get_filename ()
gint | mirage_fragment_subchannel_data_get_format ()
guint64 | mirage_fragment_subchannel_data_get_offset ()
gint | mirage_fragment_subchannel_data_get_size ()
void | mirage_fragment_subchannel_data_set_format ()
void | mirage_fragment_subchannel_data_set_offset ()
void | mirage_fragment_subchannel_data_set_size ()
void | mirage_fragment_subchannel_data_set_stream ()
gboolean | mirage_fragment_use_the_rest_of_file ()

## Signals

void | layout-changed | Run Last

## Types and Values

| MirageFragment
struct | MirageFragmentClass
enum | MirageMainDataFormat
enum | MirageSubchannelDataFormat

## Object Hierarchy

        GObject
        ╰── MirageObject
            ╰── MirageFragment

## Implemented Interfaces

MirageFragment implements MirageContextual.

## Includes

    #include <mirage-fragment.h>

## Description

MirageFragment object represents an interface between a MirageTrack and I/O stream(s) containing the data. It allows tracks to read and/or write both sectors' main channel and subchannel data. When constructing a track, an image parser will typically create and append at least one fragment. Similarly, during image conversion and writing process, at least one fragment will be requested from image writer and written to.

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

## Functions

### mirage_fragment_contains_address ()

    gboolean
    mirage_fragment_contains_address (MirageFragment *self,
                                      gint address);

Checks whether the fragment contains the given address or not.

#### Parameters

self | a MirageFragment |
address | address to be checked |

#### Returns

`TRUE` if `address` falls inside fragment, `FALSE` if it does not

### mirage_fragment_get_address ()

    gint
    mirage_fragment_get_address (MirageFragment *self);

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

Intended for internal use only.

#### Parameters

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.

Intended for internal use only.

#### Parameters

self | a MirageFragment |

#### Returns

length

### mirage_fragment_is_writable ()

    gboolean
    mirage_fragment_is_writable (MirageFragment *self);

Checks if fragment is writable, i.e., whether it has main channel data stream set and this stream is writable.

#### Parameters

self | a MirageFragment |

#### Returns

`TRUE` if fragment is writable, `FALSE` if it is not.

### mirage_fragment_main_data_get_filename ()

    const gchar *
    mirage_fragment_main_data_get_filename
                                   (MirageFragment *self);

Retrieves filename of main channel data stream.

#### Parameters

self | a MirageFragment |

#### Returns

pointer to main channel 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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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,
                                          MirageStream *stream);

Sets main channel data stream.

#### Parameters

self | a MirageFragment |
stream | a MirageStream on main channel 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` .

#### Parameters

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

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

Writes main channel data for sector at fragment-relative `address` (given in sectors).

#### Parameters

self | a MirageFragment |
address | address. | [in]
buffer | buffer with data to write, or `NULL`. | [in][allow-none][array length=length]
length | length of data to write. | [in]
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);

Writes subchannel data for sector at fragment-relative `address` (given in sectors).

#### Parameters

self | a MirageFragment |
address | address. | [in]
buffer | buffer with data to write, or `NULL`. | [in][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_write_subchannel_data ()

    gboolean
    mirage_fragment_write_subchannel_data (MirageFragment *self,
                                           gint address,
                                           const 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` .

#### Parameters

self | a MirageFragment |
address | address. | [in]
buffer | buffer with read data, or `NULL`. | [in][allow-none][array length=length]
length | length of data to write. | [in]
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.

Intended for internal use only.
Causes top-down change.

#### Parameters

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.

Intended for internal use only.
Causes bottom-up change.

#### Parameters

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

### mirage_fragment_subchannel_data_get_filename ()

    const gchar *
    mirage_fragment_subchannel_data_get_filename
                                   (MirageFragment *self);

Retrieves filename of subchannel data input stream.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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,
                                    MirageStream *stream);

Sets subchannel data stream.

#### Parameters

self | a MirageFragment |
stream | a MirageStream 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.

#### Parameters

self | a MirageFragment |
error | location to store error, or `NULL`. | [out][allow-none]

#### Returns

`TRUE` on success, `FALSE` on failure

## Types and Values

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

#### Members

### enum MirageMainDataFormat

Track file data formats.

#### Members

MIRAGE_MAIN_DATA_FORMAT_DATA | binary data |
MIRAGE_MAIN_DATA_FORMAT_AUDIO | audio data |
MIRAGE_MAIN_DATA_FORMAT_AUDIO_SWAP | audio data that needs to be swapped |

### enum MirageSubchannelDataFormat

Subchannel file data formats.

#### Members

MIRAGE_SUBCHANNEL_DATA_FORMAT_INTERNAL | internal subchannel (i.e. included in track file) |
MIRAGE_SUBCHANNEL_DATA_FORMAT_EXTERNAL | external subchannel (i.e. provided by separate file) |
MIRAGE_SUBCHANNEL_DATA_FORMAT_PW96_INTERLEAVED | P-W subchannel, 96 bytes, interleaved |
MIRAGE_SUBCHANNEL_DATA_FORMAT_PW96_LINEAR | P-W subchannel, 96 bytes, linear |
MIRAGE_SUBCHANNEL_DATA_FORMAT_RW96 | R-W subchannel, 96 bytes, cooked |
MIRAGE_SUBCHANNEL_DATA_FORMAT_Q16 | Q subchannel, 16 bytes |

## Signal Details

### The `“layout-changed”` signal

    void
    user_function (MirageFragment *fragment,
                   gpointer        user_data)

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

#### Parameters

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

Flags: Run Last

## See Also

MirageStream, MirageTrack