MIRAGE_Session object

MIRAGE_Session object — Object representing a session

Synopsis

#include <mirage.h>

enum                MIRAGE_SessionTypes;
struct              MIRAGE_Session;
gboolean            mirage_session_set_session_type     (MIRAGE_Session *self,
                                                         gint type,
                                                         GError **error);
gboolean            mirage_session_get_session_type     (MIRAGE_Session *self,
                                                         gint *type,
                                                         GError **error);
gboolean            mirage_session_layout_set_session_number
                                                        (MIRAGE_Session *self,
                                                         gint number,
                                                         GError **error);
gboolean            mirage_session_layout_get_session_number
                                                        (MIRAGE_Session *self,
                                                         gint *number,
                                                         GError **error);
gboolean            mirage_session_layout_set_first_track
                                                        (MIRAGE_Session *self,
                                                         gint first_track,
                                                         GError **error);
gboolean            mirage_session_layout_get_first_track
                                                        (MIRAGE_Session *self,
                                                         gint *first_track,
                                                         GError **error);
gboolean            mirage_session_layout_set_start_sector
                                                        (MIRAGE_Session *self,
                                                         gint start_sector,
                                                         GError **error);
gboolean            mirage_session_layout_get_start_sector
                                                        (MIRAGE_Session *self,
                                                         gint *start_sector,
                                                         GError **error);
gboolean            mirage_session_layout_get_length    (MIRAGE_Session *self,
                                                         gint *length,
                                                         GError **error);
gboolean            mirage_session_set_leadout_length   (MIRAGE_Session *self,
                                                         gint length,
                                                         GError **error);
gboolean            mirage_session_get_leadout_length   (MIRAGE_Session *self,
                                                         gint *length,
                                                         GError **error);
gboolean            mirage_session_get_number_of_tracks (MIRAGE_Session *self,
                                                         gint *number_of_tracks,
                                                         GError **error);
gboolean            mirage_session_add_track_by_index   (MIRAGE_Session *self,
                                                         gint index,
                                                         GObject **track,
                                                         GError **error);
gboolean            mirage_session_add_track_by_number  (MIRAGE_Session *self,
                                                         gint number,
                                                         GObject **track,
                                                         GError **error);
gboolean            mirage_session_remove_track_by_index
                                                        (MIRAGE_Session *self,
                                                         gint index,
                                                         GError **error);
gboolean            mirage_session_remove_track_by_number
                                                        (MIRAGE_Session *self,
                                                         gint number,
                                                         GError **error);
gboolean            mirage_session_remove_track_by_object
                                                        (MIRAGE_Session *self,
                                                         GObject *track,
                                                         GError **error);
gboolean            mirage_session_get_track_by_index   (MIRAGE_Session *self,
                                                         gint index,
                                                         GObject **track,
                                                         GError **error);
gboolean            mirage_session_get_track_by_number  (MIRAGE_Session *self,
                                                         gint number,
                                                         GObject **track,
                                                         GError **error);
gboolean            mirage_session_get_track_by_address (MIRAGE_Session *self,
                                                         gint address,
                                                         GObject **track,
                                                         GError **error);
gboolean            mirage_session_for_each_track       (MIRAGE_Session *self,
                                                         MIRAGE_CallbackFunction func,
                                                         gpointer user_data,
                                                         GError **error);
gboolean            mirage_session_get_track_before     (MIRAGE_Session *self,
                                                         GObject *cur_track,
                                                         GObject **prev_track,
                                                         GError **error);
gboolean            mirage_session_get_track_after      (MIRAGE_Session *self,
                                                         GObject *cur_track,
                                                         GObject **next_track,
                                                         GError **error);
gboolean            mirage_session_get_number_of_languages
                                                        (MIRAGE_Session *self,
                                                         gint *number_of_languages,
                                                         GError **error);
gboolean            mirage_session_add_language         (MIRAGE_Session *self,
                                                         gint langcode,
                                                         GObject **language,
                                                         GError **error);
gboolean            mirage_session_remove_language_by_index
                                                        (MIRAGE_Session *self,
                                                         gint index,
                                                         GError **error);
gboolean            mirage_session_remove_language_by_code
                                                        (MIRAGE_Session *self,
                                                         gint langcode,
                                                         GError **error);
gboolean            mirage_session_remove_language_by_object
                                                        (MIRAGE_Session *self,
                                                         GObject *language,
                                                         GError **error);
gboolean            mirage_session_get_language_by_index
                                                        (MIRAGE_Session *self,
                                                         gint index,
                                                         GObject **language,
                                                         GError **error);
gboolean            mirage_session_get_language_by_code (MIRAGE_Session *self,
                                                         gint langcode,
                                                         GObject **language,
                                                         GError **error);
gboolean            mirage_session_for_each_language    (MIRAGE_Session *self,
                                                         MIRAGE_CallbackFunction func,
                                                         gpointer user_data,
                                                         GError **error);
gboolean            mirage_session_set_cdtext_data      (MIRAGE_Session *self,
                                                         guint8 *data,
                                                         gint len,
                                                         GError **error);
gboolean            mirage_session_get_cdtext_data      (MIRAGE_Session *self,
                                                         guint8 **data,
                                                         gint *len,
                                                         GError **error);
gboolean            mirage_session_get_prev             (MIRAGE_Session *self,
                                                         GObject **prev_session,
                                                         GError **error);
gboolean            mirage_session_get_next             (MIRAGE_Session *self,
                                                         GObject **next_session,
                                                         GError **error);

Object Hierarchy

  GObject
   +----MIRAGE_Object
         +----MIRAGE_Session

Description

MIRAGE_Session 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, etc.

Details

enum MIRAGE_SessionTypes

typedef enum {
    MIRAGE_SESSION_CD_DA     = 0x00,
    MIRAGE_SESSION_CD_ROM    = 0x00,
    MIRAGE_SESSION_CD_I      = 0x10,
    MIRAGE_SESSION_CD_ROM_XA = 0x20,
} MIRAGE_SessionTypes;

Session types

MIRAGE_SESSION_CD_DA

CD AUDIO

MIRAGE_SESSION_CD_ROM

CD-ROM

MIRAGE_SESSION_CD_I

CD-I

MIRAGE_SESSION_CD_ROM_XA

CD-ROM XA

struct MIRAGE_Session

struct MIRAGE_Session;

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


mirage_session_set_session_type ()

gboolean            mirage_session_set_session_type     (MIRAGE_Session *self,
                                                         gint type,
                                                         GError **error);

Sets session type. type must be one of MIRAGE_SessionTypes.

self :

a MIRAGE_Session

type :

session type

error :

location to store error, or NULL

Returns :

TRUE on success, FALSE on failure

mirage_session_get_session_type ()

gboolean            mirage_session_get_session_type     (MIRAGE_Session *self,
                                                         gint *type,
                                                         GError **error);

Retrieves session type.

self :

a MIRAGE_Session

type :

location to store session type

error :

location to store error, or NULL

Returns :

TRUE on success, FALSE on failure

mirage_session_layout_set_session_number ()

gboolean            mirage_session_layout_set_session_number
                                                        (MIRAGE_Session *self,
                                                         gint number,
                                                         GError **error);

Sets sessions's session number.

Note

Intended for internal use only.

self :

a MIRAGE_Session

number :

session number

error :

location to store error, or NULL

Returns :

TRUE on success, FALSE on failure

mirage_session_layout_get_session_number ()

gboolean            mirage_session_layout_get_session_number
                                                        (MIRAGE_Session *self,
                                                         gint *number,
                                                         GError **error);

Retrieves sessions's session number.

self :

a MIRAGE_Session

number :

location to store session number

error :

location to store error, or NULL

Returns :

TRUE on success, FALSE on failure

mirage_session_layout_set_first_track ()

gboolean            mirage_session_layout_set_first_track
                                                        (MIRAGE_Session *self,
                                                         gint first_track,
                                                         GError **error);

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

Note

Intended for internal use only.

Note

Causes top-down change.

self :

a MIRAGE_Session

first_track :

first track number

error :

location to store error, or NULL

Returns :

TRUE on success, FALSE on failure

mirage_session_layout_get_first_track ()

gboolean            mirage_session_layout_get_first_track
                                                        (MIRAGE_Session *self,
                                                         gint *first_track,
                                                         GError **error);

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

Note

Intended for internal use only.

self :

a MIRAGE_Session

first_track :

location to store first track number

error :

location to store error, or NULL

Returns :

TRUE on success, FALSE on failure

mirage_session_layout_set_start_sector ()

gboolean            mirage_session_layout_set_start_sector
                                                        (MIRAGE_Session *self,
                                                         gint start_sector,
                                                         GError **error);

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.

Note

Intended for internal use only.

Note

Causes top-down change.

self :

a MIRAGE_Session

start_sector :

start sector

error :

location to store error, or NULL

Returns :

TRUE on success, FALSE on failure

mirage_session_layout_get_start_sector ()

gboolean            mirage_session_layout_get_start_sector
                                                        (MIRAGE_Session *self,
                                                         gint *start_sector,
                                                         GError **error);

Retrieves start sector of the session layout.

Note

Intended for internal use only.

self :

a MIRAGE_Session

start_sector :

location to store start sector

error :

location to store error, or NULL

Returns :

TRUE on success, FALSE on failure

mirage_session_layout_get_length ()

gboolean            mirage_session_layout_get_length    (MIRAGE_Session *self,
                                                         gint *length,
                                                         GError **error);

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.

self :

a MIRAGE_Session

length :

location to store session layout length

error :

location to store error, or NULL

Returns :

TRUE on success, FALSE on failure

mirage_session_set_leadout_length ()

gboolean            mirage_session_set_leadout_length   (MIRAGE_Session *self,
                                                         gint length,
                                                         GError **error);

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.

Note

Intended for internal use only.

self :

a MIRAGE_Session

length :

leadout length

error :

location to store error, or NULL

Returns :

TRUE on success, FALSE on failure

mirage_session_get_leadout_length ()

gboolean            mirage_session_get_leadout_length   (MIRAGE_Session *self,
                                                         gint *length,
                                                         GError **error);

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

Note

Intended for internal use only.

self :

a MIRAGE_Session

length :

location to store leadout length

error :

location to store error, or NULL

Returns :

TRUE on success, FALSE on failure

mirage_session_get_number_of_tracks ()

gboolean            mirage_session_get_number_of_tracks (MIRAGE_Session *self,
                                                         gint *number_of_tracks,
                                                         GError **error);

Retrieves number of tracks in the session layout.

self :

a MIRAGE_Session

number_of_tracks :

location to store number of tracks

error :

location to store error, or NULL

Returns :

TRUE on success, FALSE on failure

mirage_session_add_track_by_index ()

gboolean            mirage_session_add_track_by_index   (MIRAGE_Session *self,
                                                         gint index,
                                                         GObject **track,
                                                         GError **error);

index: index at which session should be added session: error: location to store error, or NULL

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.

If track contains pointer to existing MIRAGE_Track object, the object is added to session layout. Otherwise, a new MIRAGE_Track object is created. If track 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 track is NULL, no reference is returned.

Note

Causes bottom-up change.

self :

a MIRAGE_Session

index :

index at which track should be added

track :

pointer to MIRAGE_Track, NULL pointer or NULL

error :

location to store error, or NULL

Returns :

TRUE on success, FALSE on failure

mirage_session_add_track_by_number ()

gboolean            mirage_session_add_track_by_number  (MIRAGE_Session *self,
                                                         gint number,
                                                         GObject **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.

If track contains pointer to existing MIRAGE_Track object, the object is added to session layout. Otherwise, a new MIRAGE_Track object is created. If track 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 track is NULL, no reference is returned.

Note

Causes bottom-up change.

self :

a MIRAGE_Session

number :

track number for the added track

track :

pointer to MIRAGE_Track , NULL pointer or NULL

error :

location to store error, or NULL

Returns :

TRUE on success, FALSE on failure

mirage_session_remove_track_by_index ()

gboolean            mirage_session_remove_track_by_index
                                                        (MIRAGE_Session *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.

Note

Causes bottom-up change.

self :

a MIRAGE_Session

index :

index of track to be removed

error :

location to store error, or NULL

Returns :

TRUE on success, FALSE on failure

mirage_session_remove_track_by_number ()

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

Removes track from session layout.

number is track number of the track to be removed.

Note

Causes bottom-up change.

self :

a MIRAGE_Session

number :

track number of track to be removed

error :

location to store error, or NULL

Returns :

TRUE on success, FALSE on failure

mirage_session_remove_track_by_object ()

gboolean            mirage_session_remove_track_by_object
                                                        (MIRAGE_Session *self,
                                                         GObject *track,
                                                         GError **error);

Removes track from session layout.

track is a MIRAGE_Track object to be removed.

Note

Causes bottom-up change.

self :

a MIRAGE_Session

track :

track object to be removed

error :

location to store error, or NULL

Returns :

TRUE on success, FALSE on failure

mirage_session_get_track_by_index ()

gboolean            mirage_session_get_track_by_index   (MIRAGE_Session *self,
                                                         gint index,
                                                         GObject **track,
                                                         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.

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

self :

a MIRAGE_Session

index :

index of track to be retrieved

track :

location to store track, or NULL

error :

location to store error, or NULL

Returns :

TRUE on success, FALSE on failure

mirage_session_get_track_by_number ()

gboolean            mirage_session_get_track_by_number  (MIRAGE_Session *self,
                                                         gint number,
                                                         GObject **track,
                                                         GError **error);

Retrieves track by track number.

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

self :

a MIRAGE_Session

number :

number of track to be retrieved

track :

location to store track, or NULL

error :

location to store error, or NULL

Returns :

TRUE on success, FALSE on failure

mirage_session_get_track_by_address ()

gboolean            mirage_session_get_track_by_address (MIRAGE_Session *self,
                                                         gint address,
                                                         GObject **track,
                                                         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).

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

self :

a MIRAGE_Session

address :

address belonging to track to be retrieved

track :

location to store track, or NULL

error :

location to store error, or NULL

Returns :

TRUE on success, FALSE on failure

mirage_session_for_each_track ()

gboolean            mirage_session_for_each_track       (MIRAGE_Session *self,
                                                         MIRAGE_CallbackFunction func,
                                                         gpointer user_data,
                                                         GError **error);

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

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

self :

a MIRAGE_Session

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

gboolean            mirage_session_get_track_before     (MIRAGE_Session *self,
                                                         GObject *cur_track,
                                                         GObject **prev_track,
                                                         GError **error);

Retrieves track that comes before cur_track.

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

self :

a MIRAGE_Session

cur_track :

a track

prev_track :

location to store track, or NULL

error :

location to store error, or NULL

Returns :

TRUE on success, FALSE on failure

mirage_session_get_track_after ()

gboolean            mirage_session_get_track_after      (MIRAGE_Session *self,
                                                         GObject *cur_track,
                                                         GObject **next_track,
                                                         GError **error);

Retrieves track that comes after cur_track.

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

self :

a MIRAGE_Session

cur_track :

a track

next_track :

location to store track, or NULL

error :

location to store error, or NULL

Returns :

TRUE on success, FALSE on failure

mirage_session_get_number_of_languages ()

gboolean            mirage_session_get_number_of_languages
                                                        (MIRAGE_Session *self,
                                                         gint *number_of_languages,
                                                         GError **error);

Retrieves number of languages the session contains.

self :

a MIRAGE_Session

number_of_languages :

location to store number of languages

error :

location to store error, or NULL

Returns :

TRUE on success, FALSE on failure

mirage_session_add_language ()

gboolean            mirage_session_add_language         (MIRAGE_Session *self,
                                                         gint langcode,
                                                         GObject **language,
                                                         GError **error);

Adds language to session.

langcode is language code that should be assigned to added language. If language with that code is already present in the session, 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_Session

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

gboolean            mirage_session_remove_language_by_index
                                                        (MIRAGE_Session *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.

self :

a MIRAGE_Session

index :

index of language to be removed

error :

location to store error, or NULL

Returns :

TRUE on success, FALSE on failure

mirage_session_remove_language_by_code ()

gboolean            mirage_session_remove_language_by_code
                                                        (MIRAGE_Session *self,
                                                         gint langcode,
                                                         GError **error);

Removes language from session.

langcode is language code the language to be removed.

self :

a MIRAGE_Session

langcode :

language code of language to be removed

error :

location to store error, or NULL

Returns :

TRUE on success, FALSE on failure

mirage_session_remove_language_by_object ()

gboolean            mirage_session_remove_language_by_object
                                                        (MIRAGE_Session *self,
                                                         GObject *language,
                                                         GError **error);

Removes language from session.

language is a MIRAGE_Language object to be removed.

self :

a MIRAGE_Session

language :

language object to be removed

error :

location to store error, or NULL

Returns :

TRUE on success, FALSE on failure

mirage_session_get_language_by_index ()

gboolean            mirage_session_get_language_by_index
                                                        (MIRAGE_Session *self,
                                                         gint index,
                                                         GObject **language,
                                                         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.

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

self :

a MIRAGE_Session

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

gboolean            mirage_session_get_language_by_code (MIRAGE_Session *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_Session

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

gboolean            mirage_session_for_each_language    (MIRAGE_Session *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_Session

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

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

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

self :

a MIRAGE_Session

data :

buffer containing encoded CD-TEXT data

len :

length of data in buffer

error :

location to store error, or NULL

Returns :

TRUE on success, FALSE on failure

mirage_session_get_cdtext_data ()

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

Returns CD-TEXT data for session. It internally creates and uses MIRAGE_CDTextEncDec object as an encoder to encode data from MIRAGE_Language 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.

self :

a MIRAGE_Session

data :

location to return buffer with encoded CD-TEXT data

len :

location to return length of data in buffer

error :

location to store error, or NULL

Returns :

TRUE on success, FALSE on failure

mirage_session_get_prev ()

gboolean            mirage_session_get_prev             (MIRAGE_Session *self,
                                                         GObject **prev_session,
                                                         GError **error);

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

self :

a MIRAGE_Session

prev_session :

location to store previous session, or NULL

error :

location to store error, or NULL

Returns :

TRUE on success, FALSE on failure

mirage_session_get_next ()

gboolean            mirage_session_get_next             (MIRAGE_Session *self,
                                                         GObject **next_session,
                                                         GError **error);

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

self :

a MIRAGE_Session

next_session :

location to store next session, or NULL

error :

location to store error, or NULL

Returns :

TRUE on success, FALSE on failure

See Also

MIRAGE_Disc, MIRAGE_Track, MIRAGE_Language, MIRAGE_CDTextEncDec