MirageSession

MirageSession — Object representing a session.

Functions

gboolean (*MirageEnumLanguageCallback) ()
gboolean (*MirageEnumTrackCallback) ()
gboolean mirage_session_add_language ()
void mirage_session_add_track_by_index ()
gboolean mirage_session_add_track_by_number ()
gboolean mirage_session_enumerate_languages ()
gboolean mirage_session_enumerate_tracks ()
gboolean mirage_session_get_cdtext_data ()
MirageLanguage * mirage_session_get_language_by_code ()
MirageLanguage * mirage_session_get_language_by_index ()
gint mirage_session_get_leadout_length ()
const gchar * mirage_session_get_mcn ()
MirageSession * mirage_session_get_next ()
gint mirage_session_get_number_of_languages ()
gint mirage_session_get_number_of_tracks ()
MirageSession * mirage_session_get_prev ()
MirageSessionType mirage_session_get_session_type ()
MirageTrack * mirage_session_get_track_after ()
MirageTrack * mirage_session_get_track_before ()
MirageTrack * mirage_session_get_track_by_address ()
MirageTrack * mirage_session_get_track_by_index ()
MirageTrack * mirage_session_get_track_by_number ()
gboolean mirage_session_layout_contains_address ()
gint mirage_session_layout_get_first_track ()
gint mirage_session_layout_get_length ()
gint mirage_session_layout_get_session_number ()
gint mirage_session_layout_get_start_sector ()
void mirage_session_layout_set_first_track ()
void mirage_session_layout_set_session_number ()
void mirage_session_layout_set_start_sector ()
gboolean mirage_session_remove_language_by_code ()
gboolean mirage_session_remove_language_by_index ()
void mirage_session_remove_language_by_object ()
gboolean mirage_session_remove_track_by_index ()
gboolean mirage_session_remove_track_by_number ()
void mirage_session_remove_track_by_object ()
gboolean mirage_session_set_cdtext_data ()
void mirage_session_set_leadout_length ()
void mirage_session_set_mcn ()
void mirage_session_set_session_type ()

Signals

void layout-changed Run Last

Types and Values

Object Hierarchy

    GObject
    ╰── MirageObject
        ╰── MirageSession

Implemented Interfaces

MirageSession implements MirageContextual.

Includes

#include <mirage-session.h>

Description

MirageSession object represents a session in the disc layout. It provides functions for manipulating session layout; setting session type, adding and removing tracks and languages, setting CD-TEXT data and MCN, etc.

Functions

MirageEnumLanguageCallback ()

gboolean
(*MirageEnumLanguageCallback) (MirageLanguage *language,
                               gpointer user_data);

Callback function type used with mirage_session_enumerate_languages() and mirage_track_enumerate_languages(). A pointer to a language object is stored in language , without incrementing its reference counter. user_data is user data passed to enumeration function.

Parameters

language

language.

[in]

user_data

user data passed to enumeration function.

[in][closure]

Returns

TRUE on success, otherwise FALSE


MirageEnumTrackCallback ()

gboolean
(*MirageEnumTrackCallback) (MirageTrack *track,
                            gpointer user_data);

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

Parameters

track

track.

[in]

user_data

user data passed to enumeration function.

[in][closure]

Returns

TRUE on success, otherwise FALSE


mirage_session_add_language ()

gboolean
mirage_session_add_language (MirageSession *self,
                             gint code,
                             MirageLanguage *language,
                             GError **error);

Adds language to session.

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

Parameters

self

a MirageSession

 

code

language code for the added language.

[in]

language

a MirageLanguage to be added.

[in][transfer full]

error

location to store error, or NULL.

[out][allow-none]

Returns

TRUE on success, FALSE on failure


mirage_session_add_track_by_index ()

void
mirage_session_add_track_by_index (MirageSession *self,
                                   gint index,
                                   MirageTrack *track);

Adds track to session layout.

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

Causes bottom-up change.

Parameters

self

a MirageSession

 

index

index at which track should be added.

[in]

track

a MirageTrack to be added.

[in][transfer full]

mirage_session_add_track_by_number ()

gboolean
mirage_session_add_track_by_number (MirageSession *self,
                                    gint number,
                                    MirageTrack *track,
                                    GError **error);

Adds track to session layout.

number is track number that should be assigned to added track. It determines track's position in the layout. If track with that number already exists in the layout, the function fails.

Causes bottom-up change.

Parameters

self

a MirageSession

 

number

track number for the added track.

[in]

track

a MirageTrack to be added.

[in][transfer full]

error

location to store error, or NULL.

[out][allow-none]

Returns

TRUE on success, FALSE on failure


mirage_session_enumerate_languages ()

gboolean
mirage_session_enumerate_languages (MirageSession *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 MirageSession

 

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

gboolean
mirage_session_enumerate_tracks (MirageSession *self,
                                 MirageEnumTrackCallback func,
                                 gpointer user_data);

Iterates over tracks list, calling func for each track in the layout.

If func returns FALSE, the function immediately returns FALSE.

Parameters

self

a MirageSession

 

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

gboolean
mirage_session_get_cdtext_data (MirageSession *self,
                                guint8 **data,
                                gint *len,
                                GError **error);

Returns CD-TEXT data for session. It internally creates and uses MirageCdTextCoder object as an encoder to encode data from MirageLanguage objects from both session and its tracks. Buffer with encoded data is stored in data ; it should be freed with g_free() when no longer needed.

Parameters

self

a MirageSession

 

data

location to return buffer with encoded CD-TEXT data.

[out callee-allocates][transfer full][array length=len]

len

location to return length of data in buffer.

[out]

error

location to store error, or NULL.

[out][allow-none]

Returns

TRUE on success, FALSE on failure


mirage_session_get_language_by_code ()

MirageLanguage *
mirage_session_get_language_by_code (MirageSession *self,
                                     gint code,
                                     GError **error);

Retrieves language by language code.

Parameters

self

a MirageSession

 

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

MirageLanguage *
mirage_session_get_language_by_index (MirageSession *self,
                                      gint index,
                                      GError **error);

Retrieves language by index. If index is negative, languages from the end of session 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 MirageSession

 

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

gint
mirage_session_get_leadout_length (MirageSession *self);

Retrieves session's leadout length. The returned length is given in sectors.

Intended for internal use only.

Parameters

self

a MirageSession

 

Returns

leadout length


mirage_session_get_mcn ()

const gchar *
mirage_session_get_mcn (MirageSession *self);

Retrieves MCN.

Parameters

self

a MirageSession

 

Returns

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

[transfer none]


mirage_session_get_next ()

MirageSession *
mirage_session_get_next (MirageSession *self,
                         GError **error);

Retrieves session that is placed after self in disc layout.

Parameters

self

a MirageSession

 

error

location to store error, or NULL.

[out][allow-none]

Returns

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

[transfer full]


mirage_session_get_number_of_languages ()

gint
mirage_session_get_number_of_languages
                               (MirageSession *self);

Retrieves number of languages the session contains.

Parameters

self

a MirageSession

 

Returns

number of languages


mirage_session_get_number_of_tracks ()

gint
mirage_session_get_number_of_tracks (MirageSession *self);

Retrieves number of tracks in the session layout.

Parameters

self

a MirageSession

 

Returns

number of tracks


mirage_session_get_prev ()

MirageSession *
mirage_session_get_prev (MirageSession *self,
                         GError **error);

Retrieves session that is placed before self in disc layout.

Parameters

self

a MirageSession

 

error

location to store error, or NULL.

[out][allow-none]

Returns

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

[transfer full]


mirage_session_get_session_type ()

MirageSessionType
mirage_session_get_session_type (MirageSession *self);

Retrieves session type.

Parameters

self

a MirageSession

 

Returns

session type


mirage_session_get_track_after ()

MirageTrack *
mirage_session_get_track_after (MirageSession *self,
                                MirageTrack *track,
                                GError **error);

Retrieves track that comes after track .

Parameters

self

a MirageSession

 

track

a track.

[in]

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

MirageTrack *
mirage_session_get_track_before (MirageSession *self,
                                 MirageTrack *track,
                                 GError **error);

Retrieves track that comes before track .

Parameters

self

a MirageSession

 

track

a track.

[in]

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

MirageTrack *
mirage_session_get_track_by_address (MirageSession *self,
                                     gint address,
                                     GError **error);

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

Parameters

self

a MirageSession

 

address

address belonging to track to be retrieved.

[in]

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

MirageTrack *
mirage_session_get_track_by_index (MirageSession *self,
                                   gint index,
                                   GError **error);

Retrieves track by index. If index is negative, tracks from the end of layout 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 MirageSession

 

index

index of track to be retrieved.

[in]

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

MirageTrack *
mirage_session_get_track_by_number (MirageSession *self,
                                    gint number,
                                    GError **error);

Retrieves track by track number.

Parameters

self

a MirageSession

 

number

number of track to be retrieved.

[in]

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

gboolean
mirage_session_layout_contains_address
                               (MirageSession *self,
                                gint address);

Checks whether the session contains the given address or not.

Parameters

self

a MirageSession

 

address

address to be checked

 

Returns

TRUE if address falls inside session, FALSE if it does not


mirage_session_layout_get_first_track ()

gint
mirage_session_layout_get_first_track (MirageSession *self);

Retrieves track number of the first track in the session layout.

Intended for internal use only.

Parameters

self

a MirageSession

 

Returns

first track number


mirage_session_layout_get_length ()

gint
mirage_session_layout_get_length (MirageSession *self);

Retrieves length of the session layout. This means the length of all tracks combined, including lead-in and lead-out tracks. The returned length is given in sectors.

Parameters

self

a MirageSession

 

Returns

session layout length


mirage_session_layout_get_session_number ()

gint
mirage_session_layout_get_session_number
                               (MirageSession *self);

Retrieves sessions's session number.

Parameters

self

a MirageSession

 

Returns

session number


mirage_session_layout_get_start_sector ()

gint
mirage_session_layout_get_start_sector
                               (MirageSession *self);

Retrieves start sector of the session layout.

Intended for internal use only.

Parameters

self

a MirageSession

 

Returns

start sector


mirage_session_layout_set_first_track ()

void
mirage_session_layout_set_first_track (MirageSession *self,
                                       gint first_track);

Sets first track number to first_track . This is a number that is assigned to the first track in the session layout.

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

Parameters

self

a MirageSession

 

first_track

first track number.

[in]

mirage_session_layout_set_session_number ()

void
mirage_session_layout_set_session_number
                               (MirageSession *self,
                                gint number);

Sets sessions's session number.

Intended for internal use only.

Parameters

self

a MirageSession

 

number

session number.

[in]

mirage_session_layout_set_start_sector ()

void
mirage_session_layout_set_start_sector
                               (MirageSession *self,
                                gint start_sector);

Sets start sector of the session layout to start_sector . This is a sector at which the first track in the session layout will start.

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

Parameters

self

a MirageSession

 

start_sector

start sector.

[in]

mirage_session_remove_language_by_code ()

gboolean
mirage_session_remove_language_by_code
                               (MirageSession *self,
                                gint code,
                                GError **error);

Removes language from session.

code is language code the language to be removed.

Parameters

self

a MirageSession

 

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

gboolean
mirage_session_remove_language_by_index
                               (MirageSession *self,
                                gint index,
                                GError **error);

Removes language from session.

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

Parameters

self

a MirageSession

 

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

void
mirage_session_remove_language_by_object
                               (MirageSession *self,
                                MirageLanguage *language);

Removes language from session.

language is a MirageLanguage object to be removed.

Parameters

self

a MirageSession

 

language

language object to be removed.

[in]

mirage_session_remove_track_by_index ()

gboolean
mirage_session_remove_track_by_index (MirageSession *self,
                                      gint index,
                                      GError **error);

Removes track from session layout.

index is the index of the track to be removed. This function calls mirage_session_get_track_by_index() so index behavior is determined by that function.

Causes bottom-up change.

Parameters

self

a MirageSession

 

index

index of track to be removed.

[in]

error

location to store error, or NULL.

[out][allow-none]

Returns

TRUE on success, FALSE on failure


mirage_session_remove_track_by_number ()

gboolean
mirage_session_remove_track_by_number (MirageSession *self,
                                       gint number,
                                       GError **error);

Removes track from session layout.

number is track number of the track to be removed.

Causes bottom-up change.

Parameters

self

a MirageSession

 

number

track number of track to be removed.

[in]

error

location to store error, or NULL.

[out][allow-none]

Returns

TRUE on success, FALSE on failure


mirage_session_remove_track_by_object ()

void
mirage_session_remove_track_by_object (MirageSession *self,
                                       MirageTrack *track);

Removes track from session layout.

track is a MirageTrack object to be removed.

Causes bottom-up change.

Parameters

self

a MirageSession

 

track

track object to be removed.

[in]

mirage_session_set_cdtext_data ()

gboolean
mirage_session_set_cdtext_data (MirageSession *self,
                                guint8 *data,
                                gint len,
                                GError **error);

Sets CD-TEXT data for session. It internally creates and uses MirageCdTextCoder object as a decoder to decode data in data . Decoded data is stored in MirageLanguage objects in both session and its tracks. Therefore session must have same number of tracks as the encoded CD-TEXT data.

Parameters

self

a MirageSession

 

data

buffer containing encoded CD-TEXT data.

[in][array length=len]

len

length of data in buffer.

[in]

error

location to store error, or NULL.

[out][allow-none]

Returns

TRUE on success, FALSE on failure


mirage_session_set_leadout_length ()

void
mirage_session_set_leadout_length (MirageSession *self,
                                   gint length);

Sets session's leadout length to length . It does so by creating NULL fragment and adding it to leadout. This function is internally used to properly handle multi-session disc layouts. The length is given in sectors.

Intended for internal use only.

Parameters

self

a MirageSession

 

length

leadout length.

[in]

mirage_session_set_mcn ()

void
mirage_session_set_mcn (MirageSession *self,
                        const gchar *mcn);

Sets MCN (Media Catalogue Number).

Because MCN is stored in subchannel data, this function silently fails if any of session's tracks contains fragments with subchannel data provided.

Intended for internal use only.

Parameters

self

a MirageSession

 

mcn

MCN.

[in]

mirage_session_set_session_type ()

void
mirage_session_set_session_type (MirageSession *self,
                                 MirageSessionType type);

Sets session type. type must be one of MirageSessionType.

Parameters

self

a MirageSession

 

type

session type.

[in]

Types and Values

MIRAGE_MCN_SIZE

#define MIRAGE_MCN_SIZE 13

Length of MCN string.


MirageSession

typedef struct _MirageSession MirageSession;

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


struct MirageSessionClass

struct MirageSessionClass {
    MirageObjectClass parent_class;
};

The class structure for the MirageSession type.

Members


enum MirageSessionType

Session type.

Members

MIRAGE_SESSION_CDDA

CD AUDIO

 

MIRAGE_SESSION_CDROM

CD-ROM

 

MIRAGE_SESSION_CDI

CD-I

 

MIRAGE_SESSION_CDROM_XA

CD-ROM XA

 

Signal Details

The “layout-changed” signal

void
user_function (MirageSession *session,
               gpointer       user_data)

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

Parameters

session

a MirageSession

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

See Also

MirageDisc, MirageTrack, MirageLanguage, MirageCdTextCoder