## MirageSession MirageSession — Object representing a session. |

## Synopsis

    #include <mirage-session.h>

    gboolean            (*MirageEnumLanguageCallback)       (MirageLanguage *language,
                                                             gpointer user_data);
    gboolean            (*MirageEnumTrackCallback)          (MirageTrack *track,
                                                             gpointer user_data);
                        MirageSession;
    struct              MirageSessionClass;
    enum                MirageSessionTypes;
    gboolean            mirage_session_add_language         (MirageSession *self,
                                                             gint code,
                                                             MirageLanguage *language,
                                                             GError **error);
    void                mirage_session_add_track_by_index   (MirageSession *self,
                                                             gint index,
                                                             MirageTrack *track);
    gboolean            mirage_session_add_track_by_number  (MirageSession *self,
                                                             gint number,
                                                             MirageTrack *track,
                                                             GError **error);
    gboolean            mirage_session_enumerate_languages  (MirageSession *self,
                                                             MirageEnumLanguageCallback func,
                                                             gpointer user_data);
    gboolean            mirage_session_enumerate_tracks     (MirageSession *self,
                                                             MirageEnumTrackCallback func,
                                                             gpointer user_data);
    gboolean            mirage_session_get_cdtext_data      (MirageSession *self,
                                                             guint8 **data,
                                                             gint *len,
                                                             GError **error);
    MirageLanguage *    mirage_session_get_language_by_code (MirageSession *self,
                                                             gint code,
                                                             GError **error);
    MirageLanguage *    mirage_session_get_language_by_index
                                                            (MirageSession *self,
                                                             gint index,
                                                             GError **error);
    gint                mirage_session_get_leadout_length   (MirageSession *self);
    MirageSession *     mirage_session_get_next             (MirageSession *self,
                                                             GError **error);
    gint                mirage_session_get_number_of_languages
                                                            (MirageSession *self);
    gint                mirage_session_get_number_of_tracks (MirageSession *self);
    MirageSession *     mirage_session_get_prev             (MirageSession *self,
                                                             GError **error);
    MirageSessionTypes  mirage_session_get_session_type     (MirageSession *self);
    MirageTrack *       mirage_session_get_track_after      (MirageSession *self,
                                                             MirageTrack *track,
                                                             GError **error);
    MirageTrack *       mirage_session_get_track_before     (MirageSession *self,
                                                             MirageTrack *track,
                                                             GError **error);
    MirageTrack *       mirage_session_get_track_by_address (MirageSession *self,
                                                             gint address,
                                                             GError **error);
    MirageTrack *       mirage_session_get_track_by_index   (MirageSession *self,
                                                             gint index,
                                                             GError **error);
    MirageTrack *       mirage_session_get_track_by_number  (MirageSession *self,
                                                             gint number,
                                                             GError **error);
    gint                mirage_session_layout_get_first_track
                                                            (MirageSession *self);
    gint                mirage_session_layout_get_length    (MirageSession *self);
    gint                mirage_session_layout_get_session_number
                                                            (MirageSession *self);
    gint                mirage_session_layout_get_start_sector
                                                            (MirageSession *self);
    void                mirage_session_layout_set_first_track
                                                            (MirageSession *self,
                                                             gint first_track);
    void                mirage_session_layout_set_session_number
                                                            (MirageSession *self,
                                                             gint number);
    void                mirage_session_layout_set_start_sector
                                                            (MirageSession *self,
                                                             gint start_sector);
    gboolean            mirage_session_remove_language_by_code
                                                            (MirageSession *self,
                                                             gint code,
                                                             GError **error);
    gboolean            mirage_session_remove_language_by_index
                                                            (MirageSession *self,
                                                             gint index,
                                                             GError **error);
    void                mirage_session_remove_language_by_object
                                                            (MirageSession *self,
                                                             MirageLanguage *language);
    gboolean            mirage_session_remove_track_by_index
                                                            (MirageSession *self,
                                                             gint index,
                                                             GError **error);
    gboolean            mirage_session_remove_track_by_number
                                                            (MirageSession *self,
                                                             gint number,
                                                             GError **error);
    void                mirage_session_remove_track_by_object
                                                            (MirageSession *self,
                                                             MirageTrack *track);
    gboolean            mirage_session_set_cdtext_data      (MirageSession *self,
                                                             guint8 *data,
                                                             gint len,
                                                             GError **error);
    void                mirage_session_set_leadout_length   (MirageSession *self,
                                                             gint length);
    void                mirage_session_set_session_type     (MirageSession *self,
                                                             MirageSessionTypes type);

## Object Hierarchy

      GObject
       +----MirageObject
             +----MirageSession

## Implemented Interfaces

MirageSession implements MirageContextual.

## Signals

      "layout-changed"                                 : Run Last

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

## Details

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

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

`track` : | track. [in]
`user_data` : | user data passed to enumeration function. [in][closure]
Returns : | `TRUE` on success, otherwise `FALSE`

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

MirageObjectClass `parent_class`; | the parent class

### enum MirageSessionTypes

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

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

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

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

### Note

Causes bottom-up change.

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

### Note

Causes bottom-up change.

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

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

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

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

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

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

### Note

Intended for internal use only.

`self` : | a MirageSession
Returns : | leadout length

### mirage_session_get_next ()

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

Retrieves session that is placed after `self` in disc layout.

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

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

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

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

    MirageSessionTypes  mirage_session_get_session_type     (MirageSession *self);

Retrieves session type.

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

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

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

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

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

`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_get_first_track ()

    gint                mirage_session_layout_get_first_track
                                                            (MirageSession *self);

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

### Note

Intended for internal use only.

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

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

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

### Note

Intended for internal use only.

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

### Note

Intended for internal use only.

### Note

Causes top-down change.

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

### Note

Intended for internal use only.

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

### Note

Intended for internal use only.

### Note

Causes top-down change.

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

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

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

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

### Note

Causes bottom-up change.

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

### Note

Causes bottom-up change.

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

### Note

Causes bottom-up change.

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

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

### Note

Intended for internal use only.

`self` : | a MirageSession
`length` : | leadout length. [in]

### mirage_session_set_session_type ()

    void                mirage_session_set_session_type     (MirageSession *self,
                                                             MirageSessionTypes type);

Sets session type. `type` must be one of MirageSessionTypes.

`self` : | a MirageSession
`type` : | session type. [in]

## Signal Details

### The `"layout-changed"` signal

    void                user_function                      (MirageSession *session,
                                                            gpointer       user_data)      : Run Last

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

`session` : | a MirageSession
`user_data` : | user data set when the signal handler was connected.

## See Also

MirageDisc, MirageTrack, MirageLanguage, MirageCdTextCoder