MirageTrack: libMirage Reference Manual

## MirageTrack MirageTrack — Object representing a track. |

## Functions

gboolean | (*MirageEnumFragmentCallback) ()
gboolean | (*MirageEnumIndexCallback) ()
void | mirage_track_add_fragment ()
gboolean | mirage_track_add_index ()
gboolean | mirage_track_add_language ()
gboolean | mirage_track_enumerate_fragments ()
gboolean | mirage_track_enumerate_indices ()
gboolean | mirage_track_enumerate_languages ()
MirageFragment * | mirage_track_find_fragment_with_subchannel ()
gint | mirage_track_get_adr ()
gint | mirage_track_get_ctl ()
gint | mirage_track_get_flags ()
MirageFragment * | mirage_track_get_fragment_by_address ()
MirageFragment * | mirage_track_get_fragment_by_index ()
MirageIndex * | mirage_track_get_index_by_address ()
MirageIndex * | mirage_track_get_index_by_number ()
const gchar * | mirage_track_get_isrc ()
MirageLanguage * | mirage_track_get_language_by_code ()
MirageLanguage * | mirage_track_get_language_by_index ()
MirageTrack * | mirage_track_get_next ()
gint | mirage_track_get_number_of_fragments ()
gint | mirage_track_get_number_of_indices ()
gint | mirage_track_get_number_of_languages ()
MirageTrack * | mirage_track_get_prev ()
MirageSector * | mirage_track_get_sector ()
MirageSectorType | mirage_track_get_sector_type ()
gint | mirage_track_get_track_start ()
gboolean | mirage_track_layout_contains_address ()
gint | mirage_track_layout_get_length ()
gint | mirage_track_layout_get_session_number ()
gint | mirage_track_layout_get_start_sector ()
gint | mirage_track_layout_get_track_number ()
void | mirage_track_layout_set_start_sector ()
void | mirage_track_layout_set_track_number ()
gboolean | mirage_track_put_sector ()
gboolean | mirage_track_remove_fragment_by_index ()
void | mirage_track_remove_fragment_by_object ()
gboolean | mirage_track_remove_index_by_number ()
void | mirage_track_remove_index_by_object ()
gboolean | mirage_track_remove_language_by_code ()
gboolean | mirage_track_remove_language_by_index ()
void | mirage_track_remove_language_by_object ()
void | mirage_track_set_ctl ()
void | mirage_track_set_flags ()
void | mirage_track_set_isrc ()
void | mirage_track_set_sector_type ()
void | mirage_track_set_track_start ()

## Signals

void | layout-changed | Run Last

## Types and Values

#define | MIRAGE_ISRC_SIZE
| MirageTrack
struct | MirageTrackClass
enum | MirageTrackConstant
enum | MirageTrackFlag

## Object Hierarchy

        GObject
        ╰── MirageObject
            ╰── MirageTrack

## Implemented Interfaces

MirageTrack implements MirageContextual.

## Includes

    #include <mirage-track.h>

## Description

MirageTrack 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, read/write access to sectors, etc.

## Functions

### MirageEnumFragmentCallback ()

    gboolean
    (*MirageEnumFragmentCallback) (MirageFragment *fragment,
                                   gpointer user_data);

Callback function type used with `mirage_track_enumerate_fragments()`. A pointer to a fragment object is stored in `fragment` , without incrementing its reference counter. `user_data` is user data passed to enumeration function.

#### Parameters

fragment | fragment. | [in]
user_data | user data passed to enumeration function. | [in][closure]

#### Returns

`TRUE` on success, otherwise `FALSE`

### MirageEnumIndexCallback ()

    gboolean
    (*MirageEnumIndexCallback) (MirageIndex *index,
                                gpointer user_data);

Callback function type used with `mirage_track_enumerate_indices()`. A pointer to an index object is stored in `index` , without incrementing its reference counter. `user_data` is user data passed to enumeration function.

#### Parameters

index | index. | [in]
user_data | user data passed to enumeration function. | [in][closure]

#### Returns

`TRUE` on success, otherwise `FALSE`

### mirage_track_add_fragment ()

    void
    mirage_track_add_fragment (MirageTrack *self,
                               gint index,
                               MirageFragment *fragment);

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.

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.
Causes bottom-up change.

#### Parameters

self | a MirageTrack |
index | index at which fragment should be added. | [in]
fragment | a MirageFragment to be added. | [in]

### mirage_track_add_index ()

    gboolean
    mirage_track_add_index (MirageTrack *self,
                            gint address,
                            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 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.

#### Parameters

self | a MirageTrack |
address | address at which the index is to be added. | [in]
error | location to store error, or `NULL`. | [out][allow-none]

#### Returns

`TRUE` on success, `FALSE` on failure

### mirage_track_add_language ()

    gboolean
    mirage_track_add_language (MirageTrack *self,
                               gint code,
                               MirageLanguage *language,
                               GError **error);

Adds language to track.

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

#### Parameters

self | a MirageTrack |
code | language code for the added language. | [in]
language | a MirageLanguage to be added. | [in][transfer full][allow-none]
error | location to store error, or `NULL`. | [out][allow-none]

#### Returns

`TRUE` on success, `FALSE` on failure

### mirage_track_enumerate_fragments ()

    gboolean
    mirage_track_enumerate_fragments (MirageTrack *self,
                                      MirageEnumFragmentCallback func,
                                      gpointer user_data);

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

If `func` returns `FALSE`, the function immediately returns `FALSE`.

#### Parameters

self | a MirageTrack |
func | callback function. | [in][scope call]
user_data | data to be passed to callback function. | [in][closure]

#### Returns

`TRUE` on success, `FALSE` on failure

### mirage_track_enumerate_indices ()

    gboolean
    mirage_track_enumerate_indices (MirageTrack *self,
                                    MirageEnumIndexCallback func,
                                    gpointer user_data);

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

If `func` returns `FALSE`, the function immediately returns `FALSE`.

#### Parameters

self | a MirageTrack |
func | callback function. | [in][scope call]
user_data | user data to be passed to callback function. | [in][closure]

#### Returns

`TRUE` on success, `FALSE` on failure

### mirage_track_enumerate_languages ()

    gboolean
    mirage_track_enumerate_languages (MirageTrack *self,
                                      MirageEnumLanguageCallback func,
                                      gpointer user_data);

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

If `func` returns `FALSE`, the function immediately returns `FALSE`.

#### Parameters

self | a MirageTrack |
func | callback function. | [in][scope call]
user_data | data to be passed to callback function. | [in][closure]

#### Returns

`TRUE` on success, `FALSE` on failure

### mirage_track_find_fragment_with_subchannel ()

    MirageFragment *
    mirage_track_find_fragment_with_subchannel
                                   (MirageTrack *self,
                                    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.

Intended for internal use only.

#### Parameters

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

#### Returns

a MirageFragment on success, `NULL` on failure. The reference to the object should be released using `g_object_unref()` when no longer needed.

[transfer full]

### mirage_track_get_adr ()

    gint
    mirage_track_get_adr (MirageTrack *self);

Retrieves track's ADR.

At the moment, ADR is always returned as 1.

#### Parameters

self | a MirageTrack |

#### Returns

ADR value

### mirage_track_get_ctl ()

    gint
    mirage_track_get_ctl (MirageTrack *self);

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

#### Parameters

self | a MirageTrack |

#### Returns

CTL value

### mirage_track_get_flags ()

    gint
    mirage_track_get_flags (MirageTrack *self);

Retrieves track flags.

#### Parameters

self | a MirageTrack |

#### Returns

track flags

### mirage_track_get_fragment_by_address ()

    MirageFragment *
    mirage_track_get_fragment_by_address (MirageTrack *self,
                                          gint address,
                                          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).

#### Parameters

self | a MirageTrack |
address | address belonging to fragment to be retrieved. | [in]
error | location to store error, or `NULL`. | [out][allow-none]

#### Returns

a MirageFragment on success, `NULL` on failure. The reference to the object should be released using `g_object_unref()` when no longer needed.

[transfer full]

### mirage_track_get_fragment_by_index ()

    MirageFragment *
    mirage_track_get_fragment_by_index (MirageTrack *self,
                                        gint index,
                                        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.

#### Parameters

self | a MirageTrack |
index | index of fragment to be retrieved. | [in]
error | location to store error, or `NULL`. | [out][allow-none]

#### Returns

a MirageFragment on success, `NULL` on failure. The reference to the object should be released using `g_object_unref()` when no longer needed.

[transfer full]

### mirage_track_get_index_by_address ()

    MirageIndex *
    mirage_track_get_index_by_address (MirageTrack *self,
                                       gint address,
                                       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).

#### Parameters

self | a MirageTrack |
address | address belonging to index to be retrieved. | [in]
error | location to store error, or `NULL`. | [out][allow-none]

#### Returns

a MirageIndex on success, `NULL` on failure. The reference to the object should be released using `g_object_unref()` when no longer needed.

[transfer full]

### mirage_track_get_index_by_number ()

    MirageIndex *
    mirage_track_get_index_by_number (MirageTrack *self,
                                      gint number,
                                      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.

#### Parameters

self | a MirageTrack |
number | index number of index to be retrieved. | [in]
error | location to store error, or `NULL`. | [out][allow-none]

#### Returns

a MirageIndex on success, `NULL` on failure. The reference to the object should be released using `g_object_unref()` when no longer needed.

[transfer full]

### mirage_track_get_isrc ()

    const gchar *
    mirage_track_get_isrc (MirageTrack *self);

Retrieves ISRC.

#### Parameters

self | a MirageTrack |

#### Returns

pointer to ISRC string, or `NULL`. The string belongs to the object and should not be modified.

[transfer none]

### mirage_track_get_language_by_code ()

    MirageLanguage *
    mirage_track_get_language_by_code (MirageTrack *self,
                                       gint code,
                                       GError **error);

Retrieves language by language code.

#### Parameters

self | a MirageTrack |
code | language code of language to be retrieved. | [in]
error | location to store error, or `NULL`. | [out][allow-none]

#### Returns

a MirageLanguage on success, `NULL` on failure. The reference to the object should be released using `g_object_unref()` when no longer needed.

[transfer full]

### mirage_track_get_language_by_index ()

    MirageLanguage *
    mirage_track_get_language_by_index (MirageTrack *self,
                                        gint index,
                                        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.

#### Parameters

self | a MirageTrack |
index | index of language to be retrieved. | [in]
error | location to store error, or `NULL`. | [out][allow-none]

#### Returns

a MirageLanguage on success, `NULL` on failure. The reference to the object should be released using `g_object_unref()` when no longer needed.

[transfer full]

### mirage_track_get_next ()

    MirageTrack *
    mirage_track_get_next (MirageTrack *self,
                           GError **error);

Retrieves track that is placed after `self` in session layout

#### Parameters

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

#### Returns

a MirageTrack on success, `NULL` on failure. The reference to the object should be released using `g_object_unref()` when no longer needed.

[transfer full]

### mirage_track_get_number_of_fragments ()

    gint
    mirage_track_get_number_of_fragments (MirageTrack *self);

Retrieves number of fragments making up the track.

#### Parameters

self | a MirageTrack |

#### Returns

number of fragments

### mirage_track_get_number_of_indices ()

    gint
    mirage_track_get_number_of_indices (MirageTrack *self);

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

#### Parameters

self | a MirageTrack |

#### Returns

number of indices

### mirage_track_get_number_of_languages ()

    gint
    mirage_track_get_number_of_languages (MirageTrack *self);

Retrieves number of languages the track contains.

#### Parameters

self | a MirageTrack |

#### Returns

number of languages

### mirage_track_get_prev ()

    MirageTrack *
    mirage_track_get_prev (MirageTrack *self,
                           GError **error);

Retrieves track that is placed before `self` in session layout.

#### Parameters

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

#### Returns

a MirageTrack on success, `NULL` on failure. The reference to the object should be released using `g_object_unref()` when no longer needed.

[transfer full]

### mirage_track_get_sector ()

    MirageSector *
    mirage_track_get_sector (MirageTrack *self,
                             gint address,
                             gboolean abs,
                             GError **error);

Retrieves a sector. `address` is sector address for which a MirageSector 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.

#### Parameters

self | a MirageTrack |
address | sector address. | [in]
abs | absolute address. | [in]
error | location to store error, or `NULL`. | [out][allow-none]

#### Returns

sector object on success, `NULL` on failure. The sector object should be released with `g_object_unref()` when no longer needed.

[transfer full]

### mirage_track_get_sector_type ()

    MirageSectorType
    mirage_track_get_sector_type (MirageTrack *self);

Retrieves type of sectors comprising the track.

#### Parameters

self | a MirageTrack |

#### Returns

sector type

### mirage_track_get_track_start ()

    gint
    mirage_track_get_track_start (MirageTrack *self);

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

#### Parameters

self | a MirageTrack |

#### Returns

track start address

### mirage_track_layout_contains_address ()

    gboolean
    mirage_track_layout_contains_address (MirageTrack *self,
                                          gint address);

Checks whether the track contains the given address or not.

#### Parameters

self | a MirageTrack |
address | address to be checked |

#### Returns

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

### mirage_track_layout_get_length ()

    gint
    mirage_track_layout_get_length (MirageTrack *self);

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

#### Parameters

self | a MirageTrack |

#### Returns

track length

### mirage_track_layout_get_session_number ()

    gint
    mirage_track_layout_get_session_number
                                   (MirageTrack *self);

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

#### Parameters

self | a MirageTrack |

#### Returns

session number

### mirage_track_layout_get_start_sector ()

    gint
    mirage_track_layout_get_start_sector (MirageTrack *self);

Retrieves track's start sector.

#### Parameters

self | a MirageTrack |

#### Returns

start sector

### mirage_track_layout_get_track_number ()

    gint
    mirage_track_layout_get_track_number (MirageTrack *self);

Retrieves track's track number.

#### Parameters

self | a MirageTrack |

#### Returns

track number

### mirage_track_layout_set_start_sector ()

    void
    mirage_track_layout_set_start_sector (MirageTrack *self,
                                          gint start_sector);

Sets track's start sector.

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

#### Parameters

self | a MirageTrack |
start_sector | start sector. | [in]

### mirage_track_layout_set_track_number ()

    void
    mirage_track_layout_set_track_number (MirageTrack *self,
                                          gint track_number);

Set track's track number.

Intended for internal use only.

#### Parameters

self | a MirageTrack |
track_number | track number. | [in]

### mirage_track_put_sector ()

    gboolean
    mirage_track_put_sector (MirageTrack *self,
                             MirageSector *sector,
                             GError **error);

Writes the `sector` to track. The address at which sector is written is retrieved from sector's property; for this function to succeed, the address must either fall within track's layout (i.e., the track's fragment(s) must have sufficient length "reserved" to accept sector), or, alternatively, the sector address is allowed to equal track's current lenght plus one. In the latter case, the track's length is incremented when the sector is written (i.e., the corresponding track's fragment is extended before data is written to it).

#### Parameters

self | a MirageTrack |
sector | a MirageSector representing sector to be written. | [in]
error | location to store error, or `NULL`. | [out][allow-none]

#### Returns

`TRUE` on success, `FALSE` on failure.

### mirage_track_remove_fragment_by_index ()

    gboolean
    mirage_track_remove_fragment_by_index (MirageTrack *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.

Causes bottom-up change.

#### Parameters

self | a MirageTrack |
index | index of fragment to be removed. | [in]
error | location to store error, or `NULL`. | [out][allow-none]

#### Returns

`TRUE` on success, `FALSE` on failure

### mirage_track_remove_fragment_by_object ()

    void
    mirage_track_remove_fragment_by_object
                                   (MirageTrack *self,
                                    MirageFragment *fragment);

Removes fragment from track.

`fragment` is a MirageFragment object to be removed.

Causes bottom-up change.

#### Parameters

self | a MirageTrack |
fragment | fragment object to be removed. | [in]

### mirage_track_remove_index_by_number ()

    gboolean
    mirage_track_remove_index_by_number (MirageTrack *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.

#### Parameters

self | a MirageTrack |
number | index number of index to be removed. | [in]
error | location to store error, or `NULL`. | [out][allow-none]

#### Returns

`TRUE` on success, `FALSE` on failure

### mirage_track_remove_index_by_object ()

    void
    mirage_track_remove_index_by_object (MirageTrack *self,
                                         MirageIndex *index);

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

`index` is a MirageIndex object to be removed.

#### Parameters

self | a MirageTrack |
index | index object to be removed. | [in]

### mirage_track_remove_language_by_code ()

    gboolean
    mirage_track_remove_language_by_code (MirageTrack *self,
                                          gint code,
                                          GError **error);

Removes language from track.

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

#### Parameters

self | a MirageTrack |
code | language code of language to be removed. | [in]
error | location to store error, or `NULL`. | [out][allow-none]

#### Returns

`TRUE` on success, `FALSE` on failure

### mirage_track_remove_language_by_index ()

    gboolean
    mirage_track_remove_language_by_index (MirageTrack *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.

#### Parameters

self | a MirageTrack |
index | index of language to be removed. | [in]
error | location to store error, or `NULL`. | [out][allow-none]

#### Returns

`TRUE` on success, `FALSE` on failure

### mirage_track_remove_language_by_object ()

    void
    mirage_track_remove_language_by_object
                                   (MirageTrack *self,
                                    MirageLanguage *language);

Removes language from track.

`language` is a MirageLanguage object to be removed.

#### Parameters

self | a MirageTrack |
language | language object to be removed. | [in]

### mirage_track_set_ctl ()

    void
    mirage_track_set_ctl (MirageTrack *self,
                          gint ctl);

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.

#### Parameters

self | a MirageTrack |
ctl | track's CTL. | [in]

### mirage_track_set_flags ()

    void
    mirage_track_set_flags (MirageTrack *self,
                            gint flags);

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

#### Parameters

self | a MirageTrack |
flags | track flags. | [in]

### mirage_track_set_isrc ()

    void
    mirage_track_set_isrc (MirageTrack *self,
                           const gchar *isrc);

Sets MCN.

Because ISRC is stored in subchannel data, this function silently fails if track contains fragments with subchannel data provided.

#### Parameters

self | a MirageTrack |
isrc | ISRC. | [in]

### mirage_track_set_sector_type ()

    void
    mirage_track_set_sector_type (MirageTrack *self,
                                  MirageSectorType sector_type);

Sets sector type. `mode` must be one of MirageSectorType.

#### Parameters

self | a MirageTrack |
sector_type | type of sectors comprising the track. | [in]

### mirage_track_set_track_start ()

    void
    mirage_track_set_track_start (MirageTrack *self,
                                  gint track_start);

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

#### Parameters

self | a MirageTrack |
track_start | track start address. | [in]

## Types and Values

### MIRAGE_ISRC_SIZE

    #define MIRAGE_ISRC_SIZE 12

Length of ISRC string.

### MirageTrack

    typedef struct _MirageTrack MirageTrack;

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

### struct MirageTrackClass

    struct MirageTrackClass {
        MirageObjectClass parent_class;
    };

The class structure for the MirageTrack type.

#### Members

### enum MirageTrackConstant

Track constants.

#### Members

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

### enum MirageTrackFlag

Track flags.

#### Members

MIRAGE_TRACK_FLAG_FOURCHANNEL | four channel audio |
MIRAGE_TRACK_FLAG_COPYPERMITTED | copy permitted |
MIRAGE_TRACK_FLAG_PREEMPHASIS | pre-emphasis |

## Signal Details

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

    void
    user_function (MirageTrack *track,
                   gpointer     user_data)

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

#### Parameters

track | a MirageTrack |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

## See Also

MirageDisc, MirageSession, MirageLanguage, MirageSector