![]() |
![]() |
![]() |
libMirage Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy |
#include <mirage.h> enum MIRAGE_SessionTypes; 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);
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.
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
typedef struct _MIRAGE_Session MIRAGE_Session;
Contains private data only, and should be accessed using the functions below.
gboolean mirage_session_set_session_type (MIRAGE_Session *self, gint type, GError **error);
Sets session type. type
must be one of MIRAGE_SessionTypes.
|
a MIRAGE_Session |
|
session type |
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure
|
gboolean mirage_session_get_session_type (MIRAGE_Session *self, gint *type, GError **error);
Retrieves session type.
|
a MIRAGE_Session |
|
location to store session type |
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure
|
gboolean mirage_session_layout_set_session_number (MIRAGE_Session *self, gint number, GError **error);
Sets sessions's session number.
|
a MIRAGE_Session |
|
session number |
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure
|
gboolean mirage_session_layout_get_session_number (MIRAGE_Session *self, gint *number, GError **error);
Retrieves sessions's session number.
|
a MIRAGE_Session |
|
location to store session number |
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure
|
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.
|
a MIRAGE_Session |
|
first track number |
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure
|
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.
|
a MIRAGE_Session |
|
location to store first track number |
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure
|
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.
|
a MIRAGE_Session |
|
start sector |
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure
|
gboolean mirage_session_layout_get_start_sector (MIRAGE_Session *self, gint *start_sector, GError **error);
Retrieves start sector of the session layout.
|
a MIRAGE_Session |
|
location to store start sector |
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure
|
gboolean mirage_session_layout_get_length (MIRAGE_Session *self, gint *length, GError **error);
Retrieves length of the session layout.
|
a MIRAGE_Session |
|
location to store session layout length |
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure
|
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.
|
a MIRAGE_Session |
|
leadout length |
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure
|
gboolean mirage_session_get_leadout_length (MIRAGE_Session *self, gint *length, GError **error);
Retrieves session's leadout length.
|
a MIRAGE_Session |
|
location to store leadout length |
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure
|
gboolean mirage_session_get_number_of_tracks (MIRAGE_Session *self, gint *number_of_tracks, GError **error);
Retrieves number of tracks in the session layout.
|
a MIRAGE_Session |
|
location to store number of tracks |
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure
|
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.
|
a MIRAGE_Session |
|
index at which track should be added |
|
pointer to MIRAGE_Track, NULL pointer or NULL
|
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure
|
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.
|
a MIRAGE_Session |
|
track number for the added track |
|
pointer to MIRAGE_Track , NULL pointer or NULL
|
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure
|
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.
|
a MIRAGE_Session |
|
index of track to be removed |
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure
|
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.
|
a MIRAGE_Session |
|
track number of track to be removed |
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure
|
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.
|
a MIRAGE_Session |
|
track object to be removed |
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure
|
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.
|
a MIRAGE_Session |
|
index of track to be retrieved |
|
location to store track, or NULL
|
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure
|
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.
|
a MIRAGE_Session |
|
number of track to be retrieved |
|
location to store track, or NULL
|
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure
|
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.
|
a MIRAGE_Session |
|
address belonging to track to be retrieved |
|
location to store track, or NULL
|
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure
|
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
.
|
a MIRAGE_Session |
|
callback function |
|
data to be passed to callback function |
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure
|
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.
|
a MIRAGE_Session |
|
a track |
|
location to store track, or NULL
|
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure
|
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.
|
a MIRAGE_Session |
|
a track |
|
location to store track, or NULL
|
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure
|
gboolean mirage_session_get_number_of_languages (MIRAGE_Session *self, gint *number_of_languages, GError **error);
Retrieves number of languages the session contains.
|
a MIRAGE_Session |
|
location to store number of languages |
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure
|
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.
|
a MIRAGE_Session |
|
language code for the added language |
|
pointer to MIRAGE_Language, NULL pointer or NULL
|
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure
|
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.
|
a MIRAGE_Session |
|
index of language to be removed |
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure
|
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.
|
a MIRAGE_Session |
|
language code of language to be removed |
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure
|
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.
|
a MIRAGE_Session |
|
language object to be removed |
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure
|
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.
|
a MIRAGE_Session |
|
index of language to be retrieved |
|
location to store language, or NULL
|
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure
|
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.
|
a MIRAGE_Session |
|
language code of language to be retrieved |
|
location to store language, or NULL
|
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure
|
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
.
|
a MIRAGE_Session |
|
callback function |
|
data to be passed to callback function |
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure
|
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.
|
a MIRAGE_Session |
|
buffer containing encoded CD-TEXT data |
|
length of data in buffer |
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure
|
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.
|
a MIRAGE_Session |
|
location to return buffer with encoded CD-TEXT data |
|
location to return length of data in buffer |
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure
|
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.
|
a MIRAGE_Session |
|
location to store previous session, or NULL
|
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure
|
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.
|
a MIRAGE_Session |
|
location to store next session, or NULL
|
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure
|