MIRAGE_Track object

## MIRAGE_Track object MIRAGE_Track object — Object representing a track |

## Synopsis

    #include <mirage.h>

    #define             MIRAGE_ISRC_SIZE
    enum                MIRAGE_TrackFlags;
    enum                MIRAGE_TrackModes;
    enum                MIRAGE_TrackConstants;
                        MIRAGE_Track;
    gboolean            mirage_track_set_flags              (MIRAGE_Track *self,
                                                             gint flags,
                                                             GError **error);
    gboolean            mirage_track_get_flags              (MIRAGE_Track *self,
                                                             gint *flags,
                                                             GError **error);
    gboolean            mirage_track_set_mode               (MIRAGE_Track *self,
                                                             gint mode,
                                                             GError **error);
    gboolean            mirage_track_get_mode               (MIRAGE_Track *self,
                                                             gint *mode,
                                                             GError **error);
    gboolean            mirage_track_get_adr                (MIRAGE_Track *self,
                                                             gint *adr,
                                                             GError **error);
    gboolean            mirage_track_set_ctl                (MIRAGE_Track *self,
                                                             gint ctl,
                                                             GError **error);
    gboolean            mirage_track_get_ctl                (MIRAGE_Track *self,
                                                             gint *ctl,
                                                             GError **error);
    gboolean            mirage_track_set_isrc               (MIRAGE_Track *self,
                                                             gchar *isrc,
                                                             GError **error);
    gboolean            mirage_track_get_isrc               (MIRAGE_Track *self,
                                                             gchar **isrc,
                                                             GError **error);
    gboolean            mirage_track_get_sector             (MIRAGE_Track *self,
                                                             gint address,
                                                             gboolean abs,
                                                             GObject **sector,
                                                             GError **error);
    gboolean            mirage_track_read_sector            (MIRAGE_Track *self,
                                                             gint address,
                                                             gboolean abs,
                                                             guint8 main_sel,
                                                             guint8 subc_sel,
                                                             guint8 *ret_buf,
                                                             gint *ret_len,
                                                             GError **error);
    gboolean            mirage_track_layout_get_session_number
                                                            (MIRAGE_Track *self,
                                                             gint *session_number,
                                                             GError **error);
    gboolean            mirage_track_layout_set_track_number
                                                            (MIRAGE_Track *self,
                                                             gint track_number,
                                                             GError **error);
    gboolean            mirage_track_layout_get_track_number
                                                            (MIRAGE_Track *self,
                                                             gint *track_number,
                                                             GError **error);
    gboolean            mirage_track_layout_set_start_sector
                                                            (MIRAGE_Track *self,
                                                             gint start_sector,
                                                             GError **error);
    gboolean            mirage_track_layout_get_start_sector
                                                            (MIRAGE_Track *self,
                                                             gint *start_sector,
                                                             GError **error);
    gboolean            mirage_track_layout_get_length      (MIRAGE_Track *self,
                                                             gint *length,
                                                             GError **error);
    gboolean            mirage_track_get_number_of_fragments
                                                            (MIRAGE_Track *self,
                                                             gint *number_of_fragments,
                                                             GError **error);
    gboolean            mirage_track_add_fragment           (MIRAGE_Track *self,
                                                             gint index,
                                                             GObject **fragment,
                                                             GError **error);
    gboolean            mirage_track_remove_fragment_by_index
                                                            (MIRAGE_Track *self,
                                                             gint index,
                                                             GError **error);
    gboolean            mirage_track_remove_fragment_by_object
                                                            (MIRAGE_Track *self,
                                                             GObject *fragment,
                                                             GError **error);
    gboolean            mirage_track_get_fragment_by_index  (MIRAGE_Track *self,
                                                             gint index,
                                                             GObject **fragment,
                                                             GError **error);
    gboolean            mirage_track_get_fragment_by_address
                                                            (MIRAGE_Track *self,
                                                             gint address,
                                                             GObject **fragment,
                                                             GError **error);
    gboolean            mirage_track_for_each_fragment      (MIRAGE_Track *self,
                                                             MIRAGE_CallbackFunction func,
                                                             gpointer user_data,
                                                             GError **error);
    gboolean            mirage_track_find_fragment_with_subchannel
                                                            (MIRAGE_Track *self,
                                                             GObject **fragment,
                                                             GError **error);
    gboolean            mirage_track_set_track_start        (MIRAGE_Track *self,
                                                             gint track_start,
                                                             GError **error);
    gboolean            mirage_track_get_track_start        (MIRAGE_Track *self,
                                                             gint *track_start,
                                                             GError **error);
    gboolean            mirage_track_get_number_of_indices  (MIRAGE_Track *self,
                                                             gint *number_of_indices,
                                                             GError **error);
    gboolean            mirage_track_add_index              (MIRAGE_Track *self,
                                                             gint address,
                                                             GObject **index,
                                                             GError **error);
    gboolean            mirage_track_remove_index_by_number (MIRAGE_Track *self,
                                                             gint number,
                                                             GError **error);
    gboolean            mirage_track_remove_index_by_object (MIRAGE_Track *self,
                                                             GObject *index,
                                                             GError **error);
    gboolean            mirage_track_get_index_by_number    (MIRAGE_Track *self,
                                                             gint number,
                                                             GObject **index,
                                                             GError **error);
    gboolean            mirage_track_get_index_by_address   (MIRAGE_Track *self,
                                                             gint address,
                                                             GObject **index,
                                                             GError **error);
    gboolean            mirage_track_for_each_index         (MIRAGE_Track *self,
                                                             MIRAGE_CallbackFunction func,
                                                             gpointer user_data,
                                                             GError **error);
    gboolean            mirage_track_get_number_of_languages
                                                            (MIRAGE_Track *self,
                                                             gint *number_of_languages,
                                                             GError **error);
    gboolean            mirage_track_add_language           (MIRAGE_Track *self,
                                                             gint langcode,
                                                             GObject **language,
                                                             GError **error);
    gboolean            mirage_track_remove_language_by_index
                                                            (MIRAGE_Track *self,
                                                             gint index,
                                                             GError **error);
    gboolean            mirage_track_remove_language_by_code
                                                            (MIRAGE_Track *self,
                                                             gint langcode,
                                                             GError **error);
    gboolean            mirage_track_remove_language_by_object
                                                            (MIRAGE_Track *self,
                                                             GObject *language,
                                                             GError **error);
    gboolean            mirage_track_get_language_by_index  (MIRAGE_Track *self,
                                                             gint index,
                                                             GObject **language,
                                                             GError **error);
    gboolean            mirage_track_get_language_by_code   (MIRAGE_Track *self,
                                                             gint langcode,
                                                             GObject **language,
                                                             GError **error);
    gboolean            mirage_track_for_each_language      (MIRAGE_Track *self,
                                                             MIRAGE_CallbackFunction func,
                                                             gpointer user_data,
                                                             GError **error);
    gboolean            mirage_track_get_prev               (MIRAGE_Track *self,
                                                             GObject **prev_track,
                                                             GError **error);
    gboolean            mirage_track_get_next               (MIRAGE_Track *self,
                                                             GObject **next_track,
                                                             GError **error);
    gboolean            mirage_track_has_iso9660            (MIRAGE_Track *self,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----MIRAGE_Object
             +----MIRAGE_Track

## Description

MIRAGE_Track object represents a track in the disc layout. It provides functions for manipulating track data and layout; setting track type and flags, adding and removing fragments, indices and languages, accessing and reading of sectors, etc.

## Details

### MIRAGE_ISRC_SIZE

    #define MIRAGE_ISRC_SIZE 12

Length of ISRC string.

### enum MIRAGE_TrackFlags

    typedef enum {
        MIRAGE_TRACKF_FOURCHANNEL   = 0x01,
        MIRAGE_TRACKF_COPYPERMITTED = 0x02,
        MIRAGE_TRACKF_PREEMPHASIS   = 0x04,
    } MIRAGE_TrackFlags;

Track flags.

`MIRAGE_TRACKF_FOURCHANNEL` | four channel audio
`MIRAGE_TRACKF_COPYPERMITTED` | copy permitted
`MIRAGE_TRACKF_PREEMPHASIS` | pre-emphasis

### enum MIRAGE_TrackModes

    typedef enum {
        MIRAGE_MODE_MODE0       = 0x00,
        MIRAGE_MODE_AUDIO       = 0x01,
        MIRAGE_MODE_MODE1       = 0x02,
        MIRAGE_MODE_MODE2       = 0x03,
        MIRAGE_MODE_MODE2_FORM1 = 0x04,
        MIRAGE_MODE_MODE2_FORM2 = 0x05,
        MIRAGE_MODE_MODE2_MIXED = 0x06,
    } MIRAGE_TrackModes;

Track modes.

`MIRAGE_MODE_MODE0` | Mode 0
`MIRAGE_MODE_AUDIO` | Audio
`MIRAGE_MODE_MODE1` | Mode 1
`MIRAGE_MODE_MODE2` | Mode 2 Formless
`MIRAGE_MODE_MODE2_FORM1` | Mode 2 Form 1
`MIRAGE_MODE_MODE2_FORM2` | Mode 2 Form 2
`MIRAGE_MODE_MODE2_MIXED` | Mode 2 Mixed

### enum MIRAGE_TrackConstants

    typedef enum {
        MIRAGE_TRACK_LEADIN  = 0x00,
        MIRAGE_TRACK_LEADOUT = 0xAA,
    } MIRAGE_TrackConstants;

Track constants.

`MIRAGE_TRACK_LEADIN` | Lead-in track
`MIRAGE_TRACK_LEADOUT` | Lead-out track

### MIRAGE_Track

    typedef struct _MIRAGE_Track MIRAGE_Track;

Contains private data only, and should be accessed using the functions below.

### mirage_track_set_flags ()

    gboolean            mirage_track_set_flags              (MIRAGE_Track *self,
                                                             gint flags,
                                                             GError **error);

Sets track flags. `flags` must be a combination of MIRAGE_TrackFlags.

`self` : | a MIRAGE_Track
`flags` : | track flags
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_get_flags ()

    gboolean            mirage_track_get_flags              (MIRAGE_Track *self,
                                                             gint *flags,
                                                             GError **error);

Retrieves track flags.

`self` : | a MIRAGE_Track
`flags` : | location to store track flags
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_set_mode ()

    gboolean            mirage_track_set_mode               (MIRAGE_Track *self,
                                                             gint mode,
                                                             GError **error);

Sets track mode. `mode` must be one of MIRAGE_TrackModes.

`self` : | a MIRAGE_Track
`mode` : | track mode
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_get_mode ()

    gboolean            mirage_track_get_mode               (MIRAGE_Track *self,
                                                             gint *mode,
                                                             GError **error);

Retrieves track mode.

`self` : | a MIRAGE_Track
`mode` : | location to store track mode
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_get_adr ()

    gboolean            mirage_track_get_adr                (MIRAGE_Track *self,
                                                             gint *adr,
                                                             GError **error);

Retrieves track's ADR.

### Note

At the moment, ADR is always returned as 1.

`self` : | a MIRAGE_Track
`adr` : | location to store ADR
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_set_ctl ()

    gboolean            mirage_track_set_ctl                (MIRAGE_Track *self,
                                                             gint ctl,
                                                             GError **error);

Sets track's CTL; the function translates CTL into track flags and sets them using `mirage_track_set_flags()`. Track mode set with CTL is ignored.

`self` : | a MIRAGE_Track
`ctl` : | track's CTL
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_get_ctl ()

    gboolean            mirage_track_get_ctl                (MIRAGE_Track *self,
                                                             gint *ctl,
                                                             GError **error);

Retrieves track's CTL. CTL is calculated on basis of track mode and track flags.

`self` : | a MIRAGE_Track
`ctl` : | location to store track's CTL
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_set_isrc ()

    gboolean            mirage_track_set_isrc               (MIRAGE_Track *self,
                                                             gchar *isrc,
                                                             GError **error);

Sets ISRC.

Because ISRC is stored in subchannel data, this function fails if track contains fragments with subchannel data provided. In that case error is set to `MIRAGE_E_DATAFIXED`.

`self` : | a MIRAGE_Track
`isrc` : | ISRC
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_get_isrc ()

    gboolean            mirage_track_get_isrc               (MIRAGE_Track *self,
                                                             gchar **isrc,
                                                             GError **error);

Retrieves ISRC.

A copy of ISRC string is stored in `isrc`; it should be freed with `g_free()` when no longer needed.

`self` : | a MIRAGE_Track
`isrc` : | location to store ISRC, or `NULL`
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_get_sector ()

    gboolean            mirage_track_get_sector             (MIRAGE_Track *self,
                                                             gint address,
                                                             gboolean abs,
                                                             GObject **sector,
                                                             GError **error);

Retrieves a sector. `address` is sector address for which a MIRAGE_Sector object representing sector should be returned. `abs` specifies whether `address` is absolute or relative; if `TRUE`, `address` is absolute (i.e. relative to start of the disc), if `FALSE`, it is relative (i.e. relative to start of the track).

A reference to sector is stored in `sector`; it should be released with `g_object_unref()` when no longer needed.

`self` : | a MIRAGE_Track
`address` : | sector address
`abs` : | absolute address
`sector` : | location to store sector
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_read_sector ()

    gboolean            mirage_track_read_sector            (MIRAGE_Track *self,
                                                             gint address,
                                                             gboolean abs,
                                                             guint8 main_sel,
                                                             guint8 subc_sel,
                                                             guint8 *ret_buf,
                                                             gint *ret_len,
                                                             GError **error);

Reads data from sector at address `address`. It internally acquires a MIRAGE_Sector object by passing `address` and `abs` to `mirage_track_get_sector()`; behavior of those two arguments is determined by that function.

If sector object is successfully acquired, its data is read using `mirage_sector_get_sync()`, `mirage_sector_get_header()`, `mirage_sector_get_data()`, `mirage_sector_get_edc_ecc()` and `mirage_sector_get_subchannel()`. in accord with main channel and subchannel selection flags. `main_sel` can be a combination of MIRAGE_SectorMCSB and `subc_sel` must be one of MIRAGE_SectorSubchannelType.

Data is written into buffer provided in `ret_buf`, and written data length is stored into `ret_len`.

### Note

If any of data fields specified in `main_sel` are inappropriate for the given track's mode, they are silently ignored (for example, if subheaders were requested in Mode 1 track).

`self` : | a MIRAGE_Track
`address` : | sector address
`abs` : | absolute address
`main_sel` : | main channel selection flags
`subc_sel` : | subchannel selection flags
`ret_buf` : | buffer to write data into, or `NULL`
`ret_len` : | location to store written data length, or `NULL`
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_layout_get_session_number ()

    gboolean            mirage_track_layout_get_session_number
                                                            (MIRAGE_Track *self,
                                                             gint *session_number,
                                                             GError **error);

Retrieves track's session number. If track is not part of disc layout, 0 is returned.

`self` : | a MIRAGE_Track
`session_number` : | location to store session number
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_layout_set_track_number ()

    gboolean            mirage_track_layout_set_track_number
                                                            (MIRAGE_Track *self,
                                                             gint track_number,
                                                             GError **error);

Set track's track number.

### Note

Intended for internal use only.

`self` : | a MIRAGE_Track
`track_number` : | track number
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_layout_get_track_number ()

    gboolean            mirage_track_layout_get_track_number
                                                            (MIRAGE_Track *self,
                                                             gint *track_number,
                                                             GError **error);

Retrieves track's track number.

`self` : | a MIRAGE_Track
`track_number` : | location to store track number
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_layout_set_start_sector ()

    gboolean            mirage_track_layout_set_start_sector
                                                            (MIRAGE_Track *self,
                                                             gint start_sector,
                                                             GError **error);

Sets track's start sector.

### Note

Intended for internal use only.

### Note

Causes top-down change.

`self` : | a MIRAGE_Track
`start_sector` : | start sector
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_layout_get_start_sector ()

    gboolean            mirage_track_layout_get_start_sector
                                                            (MIRAGE_Track *self,
                                                             gint *start_sector,
                                                             GError **error);

Retrieves track's start sector.

`self` : | a MIRAGE_Track
`start_sector` : | location to store start sector
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_layout_get_length ()

    gboolean            mirage_track_layout_get_length      (MIRAGE_Track *self,
                                                             gint *length,
                                                             GError **error);

Retrieves track's length. The returned length is given in sectors.

`self` : | a MIRAGE_Track
`length` : | location to store track length
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_get_number_of_fragments ()

    gboolean            mirage_track_get_number_of_fragments
                                                            (MIRAGE_Track *self,
                                                             gint *number_of_fragments,
                                                             GError **error);

Retrieves number of fragments making up the track.

`self` : | a MIRAGE_Track
`number_of_fragments` : | location to store number of fragments
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_add_fragment ()

    gboolean            mirage_track_add_fragment           (MIRAGE_Track *self,
                                                             gint index,
                                                             GObject **fragment,
                                                             GError **error);

Adds a fragment implementation to track. `index` is index at which fragment should be added. Negative index denotes index going backwards (i.e. -1 adds fragment at the end, -2 adds fragment second-to-last, etc.). If index, either negative or positive, is too big, fragment is respectively added at the beginning or at the end of the track.

### Note

Currently, unlike in most libMirage's *_add_* functions, `fragment` argument cannot be `NULL`. This is because specific fragment implementation is required and therefore must be provided by the caller.

### Note

Causes bottom-up change.

`self` : | a MIRAGE_Track
`index` : | index at which fragment should be added
`fragment` : | pointer to MIRAGE_Fragment implementation
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_remove_fragment_by_index ()

    gboolean            mirage_track_remove_fragment_by_index
                                                            (MIRAGE_Track *self,
                                                             gint index,
                                                             GError **error);

Removes fragment from track.

`index` is the index of the fragment to be removed. This function calls `mirage_track_get_fragment_by_index()` so `index` behavior is determined by that function.

### Note

Causes bottom-up change.

`self` : | a MIRAGE_Track
`index` : | index of fragment to be removed.
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_remove_fragment_by_object ()

    gboolean            mirage_track_remove_fragment_by_object
                                                            (MIRAGE_Track *self,
                                                             GObject *fragment,
                                                             GError **error);

Removes fragment from track.

`fragment` is a MIRAGE_Fragment object to be removed.

### Note

Causes bottom-up change.

`self` : | a MIRAGE_Track
`fragment` : | fragment object to be removed
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_get_fragment_by_index ()

    gboolean            mirage_track_get_fragment_by_index  (MIRAGE_Track *self,
                                                             gint index,
                                                             GObject **fragment,
                                                             GError **error);

Retrieves fragment by index. If `index` is negative, fragments from the end of track are retrieved (e.g. -1 is for last track, -2 for second-to-last track, etc.). If `index` is out of range, regardless of the sign, the function fails.

A reference to fragment is stored in `fragment`; it should be released with `g_object_unref()` when no longer needed.

`self` : | a MIRAGE_Track
`index` : | index of fragment to be retrieved
`fragment` : | location to store fragment, or `NULL`
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_get_fragment_by_address ()

    gboolean            mirage_track_get_fragment_by_address
                                                            (MIRAGE_Track *self,
                                                             gint address,
                                                             GObject **fragment,
                                                             GError **error);

Retrieves fragment by address. `address` must be valid (track-relative) sector address that is part of the fragment to be retrieved (i.e. lying between fragment's start and end address).

A reference to fragment is stored in `fragment`; it should be released with `g_object_unref()` when no longer needed.

`self` : | a MIRAGE_Track
`address` : | address belonging to fragment to be retrieved
`fragment` : | location to store fragment, or `NULL`
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_for_each_fragment ()

    gboolean            mirage_track_for_each_fragment      (MIRAGE_Track *self,
                                                             MIRAGE_CallbackFunction func,
                                                             gpointer user_data,
                                                             GError **error);

Iterates over fragments list, calling `func` for each fragment in the layout.

If `func` returns `FALSE`, the function immediately returns `FALSE` and `error` is set to `MIRAGE_E_ITERCANCELLED`.

`self` : | a MIRAGE_Track
`func` : | callback function
`user_data` : | data to be passed to callback function
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_find_fragment_with_subchannel ()

    gboolean            mirage_track_find_fragment_with_subchannel
                                                            (MIRAGE_Track *self,
                                                             GObject **fragment,
                                                             GError **error);

Retrieves first fragment that contains subchannel data. A reference to fragment is stored in `fragment`; it should be released with `g_object_unref()` when no longer needed.

### Note

Intended for internal use only.

`self` : | a MIRAGE_Track
`fragment` : | location to store fragment, or `NULL`
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_set_track_start ()

    gboolean            mirage_track_set_track_start        (MIRAGE_Track *self,
                                                             gint track_start,
                                                             GError **error);

Sets track start address. `track_start` is a track-relative address at which track's pregap ends and track "logically" starts (i.e. where index changes from 00 to 01). Note that this is not the same as start address that is set by `mirage_track_layout_set_start_sector()`; that one sets the address at which track "physically" starts (i.e. where index 00 starts).

`self` : | a MIRAGE_Track
`track_start` : | track start address
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_get_track_start ()

    gboolean            mirage_track_get_track_start        (MIRAGE_Track *self,
                                                             gint *track_start,
                                                             GError **error);

Retrieves track start address. This is track-relative address at which pregap ends and track "logically" starts (i.e. where index changes from 00 to 01).

`self` : | a MIRAGE_Track
`track_start` : | location to store track start address
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_get_number_of_indices ()

    gboolean            mirage_track_get_number_of_indices  (MIRAGE_Track *self,
                                                             gint *number_of_indices,
                                                             GError **error);

Retrieves number of indices the track contains. Note that this includes only indices greater than 01.

`self` : | a MIRAGE_Track
`number_of_indices` : | location to store number of indices
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_add_index ()

    gboolean            mirage_track_add_index              (MIRAGE_Track *self,
                                                             gint address,
                                                             GObject **index,
                                                             GError **error);

Adds index to track.

`address` is track-relative address at which index should be added. As it determines position of the index, it also determines the number index will be assigned.

If `index` contains pointer to existing MIRAGE_Index object, the object is added to track. Otherwise, a new MIRAGE_Index object is created. If `index` contains a `NULL` pointer, a reference to newly created object is stored in it; it should be released with `g_object_unref()` when no longer needed. If `index` is `NULL`, no reference is returned.

If address falls before index 01 (i.e. if it's less than address that was set using `mirage_track_set_track_start()`), the function fails.

`self` : | a MIRAGE_Track
`address` : | address at which the index is to be added
`index` : | pointer to MIRAGE_Index, `NULL` pointer or `NULL`
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_remove_index_by_number ()

    gboolean            mirage_track_remove_index_by_number (MIRAGE_Track *self,
                                                             gint number,
                                                             GError **error);

Removes index from track. This causes index numbers of remaining indices to be readjusted.

`number` is index number of index to be removed. It must be greater or equal than 2.

`self` : | a MIRAGE_Track
`number` : | index number of index to be removed
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_remove_index_by_object ()

    gboolean            mirage_track_remove_index_by_object (MIRAGE_Track *self,
                                                             GObject *index,
                                                             GError **error);

Removes index from track.This causes index numbers of remaining indices to be readjusted.

`index` is a MIRAGE_Index object to be removed.

`self` : | a MIRAGE_Track
`index` : | index object to be removed
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_get_index_by_number ()

    gboolean            mirage_track_get_index_by_number    (MIRAGE_Track *self,
                                                             gint number,
                                                             GObject **index,
                                                             GError **error);

Retrieves index by index number. If `number` is negative, indices from the end of track are retrieved (e.g. -1 is for index, -2 for second-to-last index, etc.). If `number` is out of range, regardless of the sign, the function fails.

A reference to index is stored in `index`; it should be released with `g_object_unref()` when no longer needed.

`self` : | a MIRAGE_Track
`number` : | index number of index to be retrieved
`index` : | location to store index, or `NULL`
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_get_index_by_address ()

    gboolean            mirage_track_get_index_by_address   (MIRAGE_Track *self,
                                                             gint address,
                                                             GObject **index,
                                                             GError **error);

Retrieves index by address. `address` must be valid (track-relative) sector address that is part of the index to be retrieved (i.e. lying between index's start and end sector).

A reference to index is stored in `index`; it should be released with `g_object_unref()` when no longer needed.

`self` : | a MIRAGE_Track
`address` : | address belonging to index to be retrieved
`index` : | location to store index, or `NULL`
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_for_each_index ()

    gboolean            mirage_track_for_each_index         (MIRAGE_Track *self,
                                                             MIRAGE_CallbackFunction func,
                                                             gpointer user_data,
                                                             GError **error);

Iterates over indices list, calling `func` for each index.

If `func` returns `FALSE`, the function immediately returns `FALSE` and `error` is set to `MIRAGE_E_ITERCANCELLED`.

`self` : | a MIRAGE_Track
`func` : | callback function
`user_data` : | user data to be passed to callback function
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_get_number_of_languages ()

    gboolean            mirage_track_get_number_of_languages
                                                            (MIRAGE_Track *self,
                                                             gint *number_of_languages,
                                                             GError **error);

Retrieves number of languages the track contains.

`self` : | a MIRAGE_Track
`number_of_languages` : | location to store number of languages
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_add_language ()

    gboolean            mirage_track_add_language           (MIRAGE_Track *self,
                                                             gint langcode,
                                                             GObject **language,
                                                             GError **error);

Adds language to track.

`langcode` is language code that should be assigned to added language. If language with that code is already present in the track, the function fails.

If `language` contains pointer to existing MIRAGE_Language object, the object is added to track. Otherwise, a new MIRAGE_Language object is created. If `language` contains a `NULL` pointer, a reference to newly created object is stored in it; it should be released with `g_object_unref()` when no longer needed. If `language` is `NULL`, no reference is returned.

`self` : | a MIRAGE_Track
`langcode` : | language code for the added language
`language` : | pointer to MIRAGE_Language, `NULL` pointer or `NULL`
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_remove_language_by_index ()

    gboolean            mirage_track_remove_language_by_index
                                                            (MIRAGE_Track *self,
                                                             gint index,
                                                             GError **error);

Removes language from track.

`index` is the index of the language to be removed. This function calls `mirage_track_get_language_by_index()` so `index` behavior is determined by that function.

`self` : | a MIRAGE_Track
`index` : | index of language to be removed
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_remove_language_by_code ()

    gboolean            mirage_track_remove_language_by_code
                                                            (MIRAGE_Track *self,
                                                             gint langcode,
                                                             GError **error);

Removes language from track.

`langcode` is language code the language to be removed.

`self` : | a MIRAGE_Track
`langcode` : | language code of language to be removed
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_remove_language_by_object ()

    gboolean            mirage_track_remove_language_by_object
                                                            (MIRAGE_Track *self,
                                                             GObject *language,
                                                             GError **error);

Removes language from track.

`language` is a MIRAGE_Language object to be removed.

`self` : | a MIRAGE_Track
`language` : | language object to be removed
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_get_language_by_index ()

    gboolean            mirage_track_get_language_by_index  (MIRAGE_Track *self,
                                                             gint index,
                                                             GObject **language,
                                                             GError **error);

Retrieves language by index. If `index` is negative, languages from the end of track are retrieved (e.g. -1 is for last language, -2 for second-to-last language, etc.). If `index` is out of range, regardless of the sign, the function fails.

A reference to language is stored in `language`; it should be released with `g_object_unref()` when no longer needed.

`self` : | a MIRAGE_Track
`index` : | index of language to be retrieved
`language` : | location to store language, or `NULL`
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_get_language_by_code ()

    gboolean            mirage_track_get_language_by_code   (MIRAGE_Track *self,
                                                             gint langcode,
                                                             GObject **language,
                                                             GError **error);

Retrieves language by language code.

A reference to language is stored in `language`; it should be released with `g_object_unref()` when no longer needed.

`self` : | a MIRAGE_Track
`langcode` : | language code of language to be retrieved
`language` : | location to store language, or `NULL`
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_for_each_language ()

    gboolean            mirage_track_for_each_language      (MIRAGE_Track *self,
                                                             MIRAGE_CallbackFunction func,
                                                             gpointer user_data,
                                                             GError **error);

Iterates over languages list, calling `func` for each language.

If `func` returns `FALSE`, the function immediately returns `FALSE` and `error` is set to `MIRAGE_E_ITERCANCELLED`.

`self` : | a MIRAGE_Track
`func` : | callback function
`user_data` : | data to be passed to callback function
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_get_prev ()

    gboolean            mirage_track_get_prev               (MIRAGE_Track *self,
                                                             GObject **prev_track,
                                                             GError **error);

Retrieves track that is placed before `self` in session layout. A reference to track is stored in `prev_track`; it should be released with `g_object_unref()` when no longer needed.

`self` : | a MIRAGE_Track
`prev_track` : | location to store previous track, or `NULL`
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_get_next ()

    gboolean            mirage_track_get_next               (MIRAGE_Track *self,
                                                             GObject **next_track,
                                                             GError **error);

Retrieves track that is placed after `self` in session layout. A reference to track is stored in `next_track`; it should be released with `g_object_unref()` when no longer needed.

`self` : | a MIRAGE_Track
`next_track` : | location to store next track, or `NULL`
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_track_has_iso9660 ()

    gboolean            mirage_track_has_iso9660            (MIRAGE_Track *self,
                                                             GError **error);

Checks that the track has valid ISO-9660 Volume Descriptors.

`self` : | reference to track object
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure