MIRAGE_Disc object

## MIRAGE_Disc object MIRAGE_Disc object — Object representing a disc |

## Synopsis

    #include <mirage.h>

    #define             MIRAGE_MCN_SIZE
    enum                MIRAGE_MediumTypes;
                        MIRAGE_Disc;
    gboolean            mirage_disc_set_medium_type         (MIRAGE_Disc *self,
                                                             gint medium_type,
                                                             GError **error);
    gboolean            mirage_disc_get_medium_type         (MIRAGE_Disc *self,
                                                             gint *medium_type,
                                                             GError **error);
    gboolean            mirage_disc_set_filenames           (MIRAGE_Disc *self,
                                                             gchar **filenames,
                                                             GError **error);
    gboolean            mirage_disc_set_filename            (MIRAGE_Disc *self,
                                                             gchar **filenames,
                                                             GError **error);
    gboolean            mirage_disc_get_filenames           (MIRAGE_Disc *self,
                                                             gchar ***filenames,
                                                             GError **error);
    gboolean            mirage_disc_set_mcn                 (MIRAGE_Disc *self,
                                                             gchar *mcn,
                                                             GError **error);
    gboolean            mirage_disc_get_mcn                 (MIRAGE_Disc *self,
                                                             gchar **mcn,
                                                             GError **error);
    gboolean            mirage_disc_layout_set_first_session
                                                            (MIRAGE_Disc *self,
                                                             gint first_session,
                                                             GError **error);
    gboolean            mirage_disc_layout_get_first_session
                                                            (MIRAGE_Disc *self,
                                                             gint *first_session,
                                                             GError **error);
    gboolean            mirage_disc_layout_set_first_track  (MIRAGE_Disc *self,
                                                             gint first_track,
                                                             GError **error);
    gboolean            mirage_disc_layout_get_first_track  (MIRAGE_Disc *self,
                                                             gint *first_track,
                                                             GError **error);
    gboolean            mirage_disc_layout_set_start_sector (MIRAGE_Disc *self,
                                                             gint start_sector,
                                                             GError **error);
    gboolean            mirage_disc_layout_get_start_sector (MIRAGE_Disc *self,
                                                             gint *start_sector,
                                                             GError **error);
    gboolean            mirage_disc_layout_get_length       (MIRAGE_Disc *self,
                                                             gint *length,
                                                             GError **error);
    gboolean            mirage_disc_get_number_of_sessions  (MIRAGE_Disc *self,
                                                             gint *number_of_sessions,
                                                             GError **error);
    gboolean            mirage_disc_add_session_by_index    (MIRAGE_Disc *self,
                                                             gint index,
                                                             GObject **session,
                                                             GError **error);
    gboolean            mirage_disc_add_session_by_number   (MIRAGE_Disc *self,
                                                             gint number,
                                                             GObject **session,
                                                             GError **error);
    gboolean            mirage_disc_remove_session_by_index (MIRAGE_Disc *self,
                                                             gint index,
                                                             GError **error);
    gboolean            mirage_disc_remove_session_by_number
                                                            (MIRAGE_Disc *self,
                                                             gint number,
                                                             GError **error);
    gboolean            mirage_disc_remove_session_by_object
                                                            (MIRAGE_Disc *self,
                                                             GObject *session,
                                                             GError **error);
    gboolean            mirage_disc_get_session_by_index    (MIRAGE_Disc *self,
                                                             gint index,
                                                             GObject **session,
                                                             GError **error);
    gboolean            mirage_disc_get_session_by_number   (MIRAGE_Disc *self,
                                                             gint number,
                                                             GObject **session,
                                                             GError **error);
    gboolean            mirage_disc_get_session_by_address  (MIRAGE_Disc *self,
                                                             gint address,
                                                             GObject **session,
                                                             GError **error);
    gboolean            mirage_disc_get_session_by_track    (MIRAGE_Disc *self,
                                                             gint track,
                                                             GObject **session,
                                                             GError **error);
    gboolean            mirage_disc_for_each_session        (MIRAGE_Disc *self,
                                                             MIRAGE_CallbackFunction func,
                                                             gpointer user_data,
                                                             GError **error);
    gboolean            mirage_disc_get_session_before      (MIRAGE_Disc *self,
                                                             GObject *cur_session,
                                                             GObject **prev_session,
                                                             GError **error);
    gboolean            mirage_disc_get_session_after       (MIRAGE_Disc *self,
                                                             GObject *cur_session,
                                                             GObject **next_session,
                                                             GError **error);
    gboolean            mirage_disc_get_number_of_tracks    (MIRAGE_Disc *self,
                                                             gint *number_of_tracks,
                                                             GError **error);
    gboolean            mirage_disc_add_track_by_index      (MIRAGE_Disc *self,
                                                             gint index,
                                                             GObject **track,
                                                             GError **error);
    gboolean            mirage_disc_add_track_by_number     (MIRAGE_Disc *self,
                                                             gint number,
                                                             GObject **track,
                                                             GError **error);
    gboolean            mirage_disc_remove_track_by_index   (MIRAGE_Disc *self,
                                                             gint index,
                                                             GError **error);
    gboolean            mirage_disc_remove_track_by_number  (MIRAGE_Disc *self,
                                                             gint number,
                                                             GError **error);
    gboolean            mirage_disc_get_track_by_index      (MIRAGE_Disc *self,
                                                             gint index,
                                                             GObject **track,
                                                             GError **error);
    gboolean            mirage_disc_get_track_by_number     (MIRAGE_Disc *self,
                                                             gint number,
                                                             GObject **track,
                                                             GError **error);
    gboolean            mirage_disc_get_track_by_address    (MIRAGE_Disc *self,
                                                             gint address,
                                                             GObject **track,
                                                             GError **error);
    gboolean            mirage_disc_set_disc_structure      (MIRAGE_Disc *self,
                                                             gint layer,
                                                             gint type,
                                                             guint8 *data,
                                                             gint len,
                                                             GError **error);
    gboolean            mirage_disc_get_disc_structure      (MIRAGE_Disc *self,
                                                             gint layer,
                                                             gint type,
                                                             guint8 **data,
                                                             gint *len,
                                                             GError **error);
    gboolean            mirage_disc_get_sector              (MIRAGE_Disc *self,
                                                             gint address,
                                                             GObject **sector,
                                                             GError **error);
    gboolean            mirage_disc_read_sector             (MIRAGE_Disc *self,
                                                             gint address,
                                                             guint8 main_sel,
                                                             guint8 subc_sel,
                                                             guint8 *ret_buf,
                                                             gint *ret_len,
                                                             GError **error);
    gboolean            mirage_disc_set_dpm_data            (MIRAGE_Disc *self,
                                                             gint start,
                                                             gint resolution,
                                                             gint num_entries,
                                                             guint32 *data,
                                                             GError **error);
    gboolean            mirage_disc_get_dpm_data            (MIRAGE_Disc *self,
                                                             gint *start,
                                                             gint *resolution,
                                                             gint *num_entries,
                                                             guint32 **data,
                                                             GError **error);
    gboolean            mirage_disc_get_dpm_data_for_sector (MIRAGE_Disc *self,
                                                             gint address,
                                                             gdouble *angle,
                                                             gdouble *density,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----MIRAGE_Object
             +----MIRAGE_Disc

## Description

MIRAGE_Disc object is a top-level object in the disc layout representation, representing the actual disc.

It provides functions for manipulating the disc layout; adding and removing sessions and tracks, manipulating disc's MCN and medium type, and convenience functions for accessing and reading of sectors within the disc layout.

## Details

### MIRAGE_MCN_SIZE

    #define MIRAGE_MCN_SIZE 13

Length of MCN string.

### enum MIRAGE_MediumTypes

    typedef enum {
        MIRAGE_MEDIUM_CD  = 0x01,
        MIRAGE_MEDIUM_DVD = 0x02,
        MIRAGE_MEDIUM_BD  = 0x03,
        MIRAGE_MEDIUM_HD  = 0x04,
    } MIRAGE_MediumTypes;

Medium types.

`MIRAGE_MEDIUM_CD` | CD disc
`MIRAGE_MEDIUM_DVD` | DVD disc
`MIRAGE_MEDIUM_BD` | BD (Blue-Ray) disc
`MIRAGE_MEDIUM_HD` | HD-DVD disc

### MIRAGE_Disc

    typedef struct _MIRAGE_Disc MIRAGE_Disc;

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

### mirage_disc_set_medium_type ()

    gboolean            mirage_disc_set_medium_type         (MIRAGE_Disc *self,
                                                             gint medium_type,
                                                             GError **error);

Sets medium type. `medium_type` must be one of MIRAGE_MediumTypes.

### Note

Intended for internal use only.

`self` : | a MIRAGE_Disc
`medium_type` : | medium type
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_disc_get_medium_type ()

    gboolean            mirage_disc_get_medium_type         (MIRAGE_Disc *self,
                                                             gint *medium_type,
                                                             GError **error);

Retrieves medium type.

`self` : | a MIRAGE_Disc
`medium_type` : | location to store medium type.
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_disc_set_filenames ()

    gboolean            mirage_disc_set_filenames           (MIRAGE_Disc *self,
                                                             gchar **filenames,
                                                             GError **error);

Sets image filename(s).

### Note

Intended for internal use only, in image parser implementations.

`self` : | a MIRAGE_Disc
`filenames` : | `NULL`-terminated array of filenames
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_disc_set_filename ()

    gboolean            mirage_disc_set_filename            (MIRAGE_Disc *self,
                                                             gchar **filenames,
                                                             GError **error);

Sets image filename. The functionality is similar to `mirage_disc_set_filenames()`, except that only the first filename in `filenames` is set. It is intended to be used in parsers which support only single-file images.

### Note

Intended for internal use only, in image parser implementations.

`self` : | a MIRAGE_Disc
`filenames` : | `NULL` terminated array of filenames
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_disc_get_filenames ()

    gboolean            mirage_disc_get_filenames           (MIRAGE_Disc *self,
                                                             gchar ***filenames,
                                                             GError **error);

Retrieves image filename(s).

A copy of filenames array is stored in `filenames`; it should be freed with `g_strfreev()` when no longer needed.

`self` : | a MIRAGE_Disc
`filenames` : | location to store image filename(s)
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_disc_set_mcn ()

    gboolean            mirage_disc_set_mcn                 (MIRAGE_Disc *self,
                                                             gchar *mcn,
                                                             GError **error);

Sets MCN (Media Catalogue Number).

Because MCN is stored in subchannel data, this function fails if any of disc's tracks contains fragments with subchannel data provided. In that case error is set to `MIRAGE_E_DATAFIXED`.

### Note

Intended for internal use only.

`self` : | a MIRAGE_Disc
`mcn` : | MCN
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_disc_get_mcn ()

    gboolean            mirage_disc_get_mcn                 (MIRAGE_Disc *self,
                                                             gchar **mcn,
                                                             GError **error);

Retrieves MCN.

A copy of MCN string is stored in `mcn`; it should be freed with `g_free()` when no longer needed.

`self` : | a MIRAGE_Disc
`mcn` : | location to store MCN, or `NULL`
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_disc_layout_set_first_session ()

    gboolean            mirage_disc_layout_set_first_session
                                                            (MIRAGE_Disc *self,
                                                             gint first_session,
                                                             GError **error);

Sets first session number to `first_session`. This is a number that is assigned to the first session in the disc layout.

### Note

Intended for internal use only.

### Note

Causes top-down change.

`self` : | a MIRAGE_Disc
`first_session` : | first session number
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_disc_layout_get_first_session ()

    gboolean            mirage_disc_layout_get_first_session
                                                            (MIRAGE_Disc *self,
                                                             gint *first_session,
                                                             GError **error);

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

### Note

Intended for internal use only.

`self` : | a MIRAGE_Disc
`first_session` : | location to store first session number
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_disc_layout_set_first_track ()

    gboolean            mirage_disc_layout_set_first_track  (MIRAGE_Disc *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 disc layout.

### Note

Intended for internal use only.

### Note

Causes top-down change.

`self` : | a MIRAGE_Disc
`first_track` : | first track number
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_disc_layout_get_first_track ()

    gboolean            mirage_disc_layout_get_first_track  (MIRAGE_Disc *self,
                                                             gint *first_track,
                                                             GError **error);

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

### Note

Intended for internal use only.

`self` : | a MIRAGE_Disc
`first_track` : | location to store first track number
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_disc_layout_set_start_sector ()

    gboolean            mirage_disc_layout_set_start_sector (MIRAGE_Disc *self,
                                                             gint start_sector,
                                                             GError **error);

Sets start sector of the disc layout to `start_sector`. This is a sector at which the first session (and consequently first track) in the disc layout will start.

### Note

Intended for internal use only.

### Note

Causes top-down change.

`self` : | a MIRAGE_Disc
`start_sector` : | start sector
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_disc_layout_get_start_sector ()

    gboolean            mirage_disc_layout_get_start_sector (MIRAGE_Disc *self,
                                                             gint *start_sector,
                                                             GError **error);

Retrieves start sector of the disc layout.

### Note

Intended for internal use only.

`self` : | a MIRAGE_Disc
`start_sector` : | location to store start sector
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_disc_layout_get_length ()

    gboolean            mirage_disc_layout_get_length       (MIRAGE_Disc *self,
                                                             gint *length,
                                                             GError **error);

Retrieves length of the disc layout. The returned length is given in sectors.

`self` : | a MIRAGE_Disc
`length` : | location to store disc layout length
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_disc_get_number_of_sessions ()

    gboolean            mirage_disc_get_number_of_sessions  (MIRAGE_Disc *self,
                                                             gint *number_of_sessions,
                                                             GError **error);

Retrieves number of sessions in the disc layout.

`self` : | a MIRAGE_Disc
`number_of_sessions` : | location to store number of sessions
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_disc_add_session_by_index ()

    gboolean            mirage_disc_add_session_by_index    (MIRAGE_Disc *self,
                                                             gint index,
                                                             GObject **session,
                                                             GError **error);

Adds session to disc layout.

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

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

### Note

Causes bottom-up change.

`self` : | a MIRAGE_Disc
`index` : | index at which session should be added
`session` : | pointer to MIRAGE_Session, `NULL` pointer or `NULL`
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_disc_add_session_by_number ()

    gboolean            mirage_disc_add_session_by_number   (MIRAGE_Disc *self,
                                                             gint number,
                                                             GObject **session,
                                                             GError **error);

Adds session to disc layout.

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

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

### Note

Causes bottom-up change.

`self` : | a MIRAGE_Disc
`number` : | session number for the added session
`session` : | pointer to MIRAGE_Session, `NULL` pointer or `NULL`
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_disc_remove_session_by_index ()

    gboolean            mirage_disc_remove_session_by_index (MIRAGE_Disc *self,
                                                             gint index,
                                                             GError **error);

Removes session from disc layout.

`index` is the index of the session to be removed. This function calls `mirage_disc_get_session_by_index()` so `index` behavior is determined by that function.

### Note

Causes bottom-up change.

`self` : | a MIRAGE_Disc
`index` : | index of session to be removed
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_disc_remove_session_by_number ()

    gboolean            mirage_disc_remove_session_by_number
                                                            (MIRAGE_Disc *self,
                                                             gint number,
                                                             GError **error);

Removes session from disc layout.

`number` is session number of the session to be removed.

### Note

Causes bottom-up change.

`self` : | a MIRAGE_Disc
`number` : | session number of session to be removed
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_disc_remove_session_by_object ()

    gboolean            mirage_disc_remove_session_by_object
                                                            (MIRAGE_Disc *self,
                                                             GObject *session,
                                                             GError **error);

Removes session from disc layout.

`session` is a MIRAGE_Session object to be removed.

### Note

Causes bottom-up change.

`self` : | a MIRAGE_Disc
`session` : | session object to be removed
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_disc_get_session_by_index ()

    gboolean            mirage_disc_get_session_by_index    (MIRAGE_Disc *self,
                                                             gint index,
                                                             GObject **session,
                                                             GError **error);

Retrieves session by index. If `index` is negative, sessions from the end of layout are retrieved (e.g. -1 is for last session, -2 for second-to-last session, etc.). If `index` is out of range, regardless of the sign, the function fails.

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

`self` : | a MIRAGE_Disc
`index` : | index of session to be retrieved
`session` : | location to store session, or `NULL`
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_disc_get_session_by_number ()

    gboolean            mirage_disc_get_session_by_number   (MIRAGE_Disc *self,
                                                             gint number,
                                                             GObject **session,
                                                             GError **error);

Retrieves session by session number.

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

`self` : | a MIRAGE_Disc
`number` : | number of session to be retrieved
`session` : | location to store session, or `NULL`
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_disc_get_session_by_address ()

    gboolean            mirage_disc_get_session_by_address  (MIRAGE_Disc *self,
                                                             gint address,
                                                             GObject **session,
                                                             GError **error);

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

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

`self` : | a MIRAGE_Disc
`address` : | address belonging to session to be retrieved
`session` : | location to store session, or `NULL`
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_disc_get_session_by_track ()

    gboolean            mirage_disc_get_session_by_track    (MIRAGE_Disc *self,
                                                             gint track,
                                                             GObject **session,
                                                             GError **error);

Retrieves session by track number. `track` must be valid track number of track that is part of the session.

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

`self` : | a MIRAGE_Disc
`track` : | number of track belonging to session to be retrieved
`session` : | location to store session, or `NULL`
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_disc_for_each_session ()

    gboolean            mirage_disc_for_each_session        (MIRAGE_Disc *self,
                                                             MIRAGE_CallbackFunction func,
                                                             gpointer user_data,
                                                             GError **error);

Iterates over sessions list, calling `func` for each session in the layout.

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

`self` : | a MIRAGE_Disc
`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_disc_get_session_before ()

    gboolean            mirage_disc_get_session_before      (MIRAGE_Disc *self,
                                                             GObject *cur_session,
                                                             GObject **prev_session,
                                                             GError **error);

Retrieves session that comes before `cur_session`.

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

`self` : | a MIRAGE_Disc
`cur_session` : | a session
`prev_session` : | location to store session, or `NULL`
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_disc_get_session_after ()

    gboolean            mirage_disc_get_session_after       (MIRAGE_Disc *self,
                                                             GObject *cur_session,
                                                             GObject **next_session,
                                                             GError **error);

Retrieves session that comes after `cur_session`.

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

`self` : | a MIRAGE_Disc
`cur_session` : | a session
`next_session` : | location to store session, or `NULL`
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_disc_get_number_of_tracks ()

    gboolean            mirage_disc_get_number_of_tracks    (MIRAGE_Disc *self,
                                                             gint *number_of_tracks,
                                                             GError **error);

Retrieves number of tracks in the disc layout.

`self` : | a MIRAGE_Disc
`number_of_tracks` : | location to store number of tracks
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_disc_add_track_by_index ()

    gboolean            mirage_disc_add_track_by_index      (MIRAGE_Disc *self,
                                                             gint index,
                                                             GObject **track,
                                                             GError **error);

Adds track to disc layout.

`index` is the index at which track is added. The function attempts to find appropriate session by iterating over sessions list and verifying index ranges, then adds the track using `mirage_session_add_track_by_index()`. Negative `index` denotes index going backwards (i.e. -1 adds track at the end of last session, etc.). If `index`, either negative or positive, is too big, track is respectively added at the beginning of the first or at the end of the last session in the layout.

If disc layout is empty (i.e. contains no sessions), then session is created.

The rest of behavior is same as of `mirage_session_add_track_by_index()`.

### Note

Causes bottom-up change.

`self` : | a MIRAGE_Disc
`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_disc_add_track_by_number ()

    gboolean            mirage_disc_add_track_by_number     (MIRAGE_Disc *self,
                                                             gint number,
                                                             GObject **track,
                                                             GError **error);

Adds track to disc layout.

`number` is track number that should be assigned to added track. It determines track's position in the layout. The function attempts to find appropriate session using `mirage_disc_get_session_by_track()`, then adds the track using `mirage_session_add_track_by_number()`.

If disc layout is empty (i.e. contains no sessions), then session is created. If `number` is greater than last track's number, the track is added at the end of last session.

The rest of behavior is same as of `mirage_session_add_track_by_number()`.

### Note

Causes bottom-up change.

`self` : | a MIRAGE_Disc
`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_disc_remove_track_by_index ()

    gboolean            mirage_disc_remove_track_by_index   (MIRAGE_Disc *self,
                                                             gint index,
                                                             GError **error);

Removes track from disc layout.

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

### Note

Causes bottom-up change.

`self` : | a MIRAGE_Disc
`index` : | index of track to be removed
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_disc_remove_track_by_number ()

    gboolean            mirage_disc_remove_track_by_number  (MIRAGE_Disc *self,
                                                             gint number,
                                                             GError **error);

Removes track from disc layout.

`number` is track number of the track to be removed. This function calls `mirage_disc_get_track_by_number()` so `number` behavior is determined by that function.

### Note

Causes bottom-up change.

`self` : | a MIRAGE_Disc
`number` : | track number of track to be removed
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_disc_get_track_by_index ()

    gboolean            mirage_disc_get_track_by_index      (MIRAGE_Disc *self,
                                                             gint index,
                                                             GObject **track,
                                                             GError **error);

Retrieves track by index. The function attempts to find appropriate session by iterating over sessions list and verifying index ranges, then retrieves the track using `mirage_session_get_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.

The rest of behavior is same as of `mirage_session_get_track_by_index()`.

`self` : | a MIRAGE_Disc
`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_disc_get_track_by_number ()

    gboolean            mirage_disc_get_track_by_number     (MIRAGE_Disc *self,
                                                             gint number,
                                                             GObject **track,
                                                             GError **error);

Retrieves track by track number. The function attempts to find appropriate session using `mirage_disc_get_session_by_track()`, then retrieves the track using `mirage_session_get_track_by_number()`.

The rest of behavior is same as of `mirage_session_get_track_by_number()`.

`self` : | a MIRAGE_Disc
`number` : | track 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_disc_get_track_by_address ()

    gboolean            mirage_disc_get_track_by_address    (MIRAGE_Disc *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 track's start and end sector).

The function attempts to find appropriate session using `mirage_disc_get_session_by_address()`, then retrieves the track using `mirage_session_get_track_by_address()`.

The rest of behavior is same as of `mirage_session_get_track_by_address()`.

`self` : | a MIRAGE_Disc
`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_disc_set_disc_structure ()

    gboolean            mirage_disc_set_disc_structure      (MIRAGE_Disc *self,
                                                             gint layer,
                                                             gint type,
                                                             guint8 *data,
                                                             gint len,
                                                             GError **error);

Sets disc structure of type `type` to layer `layer` to disc. `data` is buffer containing disc structure data and `len` is data length.

### Note

Disc structures are valid only for DVD and BD discs; therefore, if disc type is not set to `MIRAGE_MEDIUM_DVD` or `MIRAGE_MEDIUM_BD` prior to calling this function, the function will fail and error will be set to `MIRAGE_E_INVALIDMEDIUM`.

`self` : | a MIRAGE_Disc
`layer` : | disc layer
`type` : | disc structure type
`data` : | disc structure data to be set
`len` : | length of disc structure data
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_disc_get_disc_structure ()

    gboolean            mirage_disc_get_disc_structure      (MIRAGE_Disc *self,
                                                             gint layer,
                                                             gint type,
                                                             guint8 **data,
                                                             gint *len,
                                                             GError **error);

Retrieves disc structure of type `type` from layer `layer`. The buffer containing copy of disc structure is stored to `data`; it should be freed with `g_free()` when no longer needed.

### Note

Disc structures are valid only for DVD and BD discs; therefore, if disc type is not set to `MIRAGE_MEDIUM_DVD` or `MIRAGE_MEDIUM_BD` prior to calling this function, the function will fail and error will be set to `MIRAGE_E_INVALIDMEDIUM`.

`self` : | a MIRAGE_Disc
`layer` : | disc layer
`type` : | disc structure type
`data` : | location to store buffer containing disc structure data, or `NULL`
`len` : | location to store data length, or `NULL`
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_disc_get_sector ()

    gboolean            mirage_disc_get_sector              (MIRAGE_Disc *self,
                                                             gint address,
                                                             GObject **sector,
                                                             GError **error);

Retrieves sector object representing sector at sector address `address`.

This function attempts to retrieve appropriate track using `mirage_disc_get_track_by_address()`, then retrieves sector object using `mirage_track_get_sector()`.

The rest of behavior is same as of `mirage_disc_get_sector()`.

`self` : | a MIRAGE_Disc
`address` : | sector address
`sector` : | location to store sector
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_disc_read_sector ()

    gboolean            mirage_disc_read_sector             (MIRAGE_Disc *self,
                                                             gint address,
                                                             guint8 main_sel,
                                                             guint8 subc_sel,
                                                             guint8 *ret_buf,
                                                             gint *ret_len,
                                                             GError **error);

Reads sector data from sector at address `address`. The function attempts to retrieve appropriate track using `mirage_disc_get_track_by_address()`, then reads sector data using `mirage_track_read_sector()`.

The rest of behavior is same as of `mirage_track_read_sector()`.

`self` : | a MIRAGE_Disc
`address` : | sector address
`main_sel` : | main channel selection flags
`subc_sel` : | subchannel selection flags
`ret_buf` : | buffer to write data into, or `NULL`
`ret_len` : | location to store written data length, or `NULL`
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_disc_set_dpm_data ()

    gboolean            mirage_disc_set_dpm_data            (MIRAGE_Disc *self,
                                                             gint start,
                                                             gint resolution,
                                                             gint num_entries,
                                                             guint32 *data,
                                                             GError **error);

Sets the DPM data for disc. If `num_entries` is not positive, DPM data is reset. `start` is the address at which DPM data begins, `resolution` is resolution of DPM data and `num_entries` is the number of DPM entries in buffer pointed to by `data`.

`self` : | a MIRAGE_Disc
`start` : | DPM start sector
`resolution` : | DPM data resolution
`num_entries` : | number of DPM entries
`data` : | buffer containing DPM data
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_disc_get_dpm_data ()

    gboolean            mirage_disc_get_dpm_data            (MIRAGE_Disc *self,
                                                             gint *start,
                                                             gint *resolution,
                                                             gint *num_entries,
                                                             guint32 **data,
                                                             GError **error);

Retrieves DPM data for disc. The pointer to object's private buffer containing DPM data entries is stored in `data`; as such it should not be freed.

`self` : | a MIRAGE_Disc
`start` : | location to store DPM start sector, or `NULL`
`resolution` : | location to store DPM data resolution, or `NULL`
`num_entries` : | location to store number of DPM entries, or `NULL`
`data` : | location to store pointer to buffer containing DPM data, or `NULL`
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_disc_get_dpm_data_for_sector ()

    gboolean            mirage_disc_get_dpm_data_for_sector (MIRAGE_Disc *self,
                                                             gint address,
                                                             gdouble *angle,
                                                             gdouble *density,
                                                             GError **error);

Retrieves DPM data for sector at address `address`. Two pieces of data can be retrieved; first one is sector angle, expressed in rotations (i.e. 0.25 would mean 1/4 of rotation or 90˚ and 1.0 means one full rotation or 360˚), and the other one is sector density at given address, expressed in degrees per sector).

`self` : | a MIRAGE_Disc
`address` : | address of sector to retrieve DPM data for
`angle` : | location to store sector angle, or `NULL`
`density` : | location to store sector density, or `NULL`
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

## See Also

MIRAGE_Session, MIRAGE_Track, MIRAGE_Object, MIRAGE_Parser