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 ()
MirageTrackModes mirage_track_get_mode ()
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 ()
gint mirage_track_get_track_start ()
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_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_mode ()
void mirage_track_set_track_start ()

Signals

void layout-changed Run Last

Types and Values

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, accessing and reading of 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_mode ()

MirageTrackModes
mirage_track_get_mode (MirageTrack *self);

Retrieves track mode.

Parameters

self

a MirageTrack

 

Returns

track mode


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

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_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_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_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_mode ()

void
mirage_track_set_mode (MirageTrack *self,
                       MirageTrackModes mode);

Sets track mode. mode must be one of MirageTrackModes.

Parameters

self

a MirageTrack

 

mode

track mode.

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


struct MirageTrack

struct 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;

    /* Signals */
    gint signal_layout_changed;
};

The class structure for the MirageTrack type.

Members

gint signal_layout_changed;

"layout-changed" signal identifier

 

enum MirageTrackConstants

Track constants.

Members

MIRAGE_TRACK_LEADIN

Lead-in track

 

MIRAGE_TRACK_LEADOUT

Lead-out track

 

enum MirageTrackFlags

Track flags.

Members

MIRAGE_TRACK_FLAG_FOURCHANNEL

four channel audio

 

MIRAGE_TRACK_FLAG_COPYPERMITTED

copy permitted

 

MIRAGE_TRACK_FLAG_PREEMPHASIS

pre-emphasis

 

enum MirageTrackModes

Track modes.

Members

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

 

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