MirageDisc

MirageDisc — Object representing an optical disc.

Functions

gboolean (*MirageEnumSessionCallback) ()
void mirage_disc_add_session_by_index ()
gboolean mirage_disc_add_session_by_number ()
gboolean mirage_disc_add_track_by_index ()
gboolean mirage_disc_add_track_by_number ()
gboolean mirage_disc_enumerate_sessions ()
gboolean mirage_disc_get_disc_structure ()
void mirage_disc_get_dpm_data ()
gboolean mirage_disc_get_dpm_data_for_sector ()
gchar ** mirage_disc_get_filenames ()
MirageMediumType mirage_disc_get_medium_type ()
gint mirage_disc_get_number_of_sessions ()
gint mirage_disc_get_number_of_tracks ()
MirageSector * mirage_disc_get_sector ()
MirageSession * mirage_disc_get_session_after ()
MirageSession * mirage_disc_get_session_before ()
MirageSession * mirage_disc_get_session_by_address ()
MirageSession * mirage_disc_get_session_by_index ()
MirageSession * mirage_disc_get_session_by_number ()
MirageSession * mirage_disc_get_session_by_track ()
MirageTrack * mirage_disc_get_track_by_address ()
MirageTrack * mirage_disc_get_track_by_index ()
MirageTrack * mirage_disc_get_track_by_number ()
gboolean mirage_disc_layout_contains_address ()
gint mirage_disc_layout_get_first_session ()
gint mirage_disc_layout_get_first_track ()
gint mirage_disc_layout_get_length ()
gint mirage_disc_layout_get_start_sector ()
void mirage_disc_layout_set_first_session ()
void mirage_disc_layout_set_first_track ()
void mirage_disc_layout_set_start_sector ()
gboolean mirage_disc_put_sector ()
gboolean mirage_disc_remove_session_by_index ()
gboolean mirage_disc_remove_session_by_number ()
void mirage_disc_remove_session_by_object ()
gboolean mirage_disc_remove_track_by_index ()
gboolean mirage_disc_remove_track_by_number ()
void mirage_disc_set_disc_structure ()
void mirage_disc_set_dpm_data ()
void mirage_disc_set_filename ()
void mirage_disc_set_filenames ()
void mirage_disc_set_medium_type ()

Signals

void layout-changed Run Last

Types and Values

Object Hierarchy

    GObject
    ╰── MirageObject
        ╰── MirageDisc

Implemented Interfaces

MirageDisc implements MirageContextual.

Includes

#include <mirage-disc.h>

Description

MirageDisc 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 medium type, and convenience functions for accessing sectors on the disc.

Typically, a MirageDisc is obtained as a result of loading an image using MirageContext and its mirage_context_load_image() function.

Functions

MirageEnumSessionCallback ()

gboolean
(*MirageEnumSessionCallback) (MirageSession *session,
                              gpointer user_data);

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

Parameters

session

session.

[in]

user_data

user data passed to enumeration function.

[in][closure]

Returns

TRUE on success, otherwise FALSE


mirage_disc_add_session_by_index ()

void
mirage_disc_add_session_by_index (MirageDisc *self,
                                  gint index,
                                  MirageSession *session);

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 added at the beginning or at the end of the layout, respectively.

Causes bottom-up change.

Parameters

self

a MirageDisc

 

index

index at which session should be added.

[in]

session

a MirageSession to be added.

[in][transfer full]

mirage_disc_add_session_by_number ()

gboolean
mirage_disc_add_session_by_number (MirageDisc *self,
                                   gint number,
                                   MirageSession *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.

Causes bottom-up change.

Parameters

self

a MirageDisc

 

number

session number for the added session.

[in]

session

a MirageSession to be added.

[in][transfer full]

error

location to store error, or NULL.

[out][allow-none]

Returns

TRUE on success, FALSE on failure


mirage_disc_add_track_by_index ()

gboolean
mirage_disc_add_track_by_index (MirageDisc *self,
                                gint index,
                                MirageTrack *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().

Causes bottom-up change.

Parameters

self

a MirageDisc

 

index

index at which track should be added.

[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_disc_add_track_by_number ()

gboolean
mirage_disc_add_track_by_number (MirageDisc *self,
                                 gint number,
                                 MirageTrack *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().

Causes bottom-up change.

Parameters

self

a MirageDisc

 

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

gboolean
mirage_disc_enumerate_sessions (MirageDisc *self,
                                MirageEnumSessionCallback func,
                                gpointer user_data);

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

If func returns FALSE, the function immediately returns FALSE.

Parameters

self

a MirageDisc

 

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

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

Retrieves disc structure of type type from layer layer . The pointer to buffer containing the disc structure is stored in data ; the buffer belongs to the object and therefore should not be modified.

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.

Parameters

self

a MirageDisc

 

layer

disc layer.

[in]

type

disc structure type.

[in]

data

location to store buffer containing disc structure data, or NULL.

[out][transfer none][allow-none][array length=len]

len

location to store data length, or NULL.

[out][allow-none]

error

location to store error, or NULL.

[out][allow-none]

Returns

TRUE on success, FALSE on failure


mirage_disc_get_dpm_data ()

void
mirage_disc_get_dpm_data (MirageDisc *self,
                          gint *start,
                          gint *resolution,
                          gint *num_entries,
                          const guint32 **data);

Retrieves DPM data for disc. The pointer to buffer containing DPM data entries is stored in data ; the buffer belongs to object and therefore should not be modified.

Parameters

self

a MirageDisc

 

start

location to store DPM start sector, or NULL.

[out][allow-none]

resolution

location to store DPM data resolution, or NULL.

[out][allow-none]

num_entries

location to store number of DPM entries, or NULL.

[out][allow-none]

data

location to store pointer to buffer containing DPM data, or NULL.

[out][allow-none][array length=num_entries][transfer none]

mirage_disc_get_dpm_data_for_sector ()

gboolean
mirage_disc_get_dpm_data_for_sector (MirageDisc *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).

Parameters

self

a MirageDisc

 

address

address of sector to retrieve DPM data for.

[in]

angle

location to store sector angle, or NULL.

[out][allow-none]

density

location to store sector density, or NULL.

[out][allow-none]

error

location to store error, or NULL.

[out][allow-none]

Returns

TRUE on success, FALSE on failure


mirage_disc_get_filenames ()

gchar **
mirage_disc_get_filenames (MirageDisc *self);

Retrieves image filename(s).

Parameters

self

a MirageDisc

 

Returns

pointer to NULL-terminated array of filenames. The array belongs to the object and should not be modified.

[transfer none][array zero-terminated=1]


mirage_disc_get_medium_type ()

MirageMediumType
mirage_disc_get_medium_type (MirageDisc *self);

Retrieves medium type.

Parameters

self

a MirageDisc

 

Returns

medium type


mirage_disc_get_number_of_sessions ()

gint
mirage_disc_get_number_of_sessions (MirageDisc *self);

Retrieves number of sessions in the disc layout.

Parameters

self

a MirageDisc

 

Returns

number of sessions


mirage_disc_get_number_of_tracks ()

gint
mirage_disc_get_number_of_tracks (MirageDisc *self);

Retrieves number of tracks in the disc layout.

Parameters

self

a MirageDisc

 

Returns

number of tracks


mirage_disc_get_sector ()

MirageSector *
mirage_disc_get_sector (MirageDisc *self,
                        gint address,
                        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().

Parameters

self

a MirageDisc

 

address

sector address.

[in]

error

location to store error, or NULL.

[out][allow-none]

Returns

sector object on success, NULL on failure.

[transfer full]


mirage_disc_get_session_after ()

MirageSession *
mirage_disc_get_session_after (MirageDisc *self,
                               MirageSession *session,
                               GError **error);

Retrieves session that comes after session .

Parameters

self

a MirageDisc

 

session

a session.

[in]

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

MirageSession *
mirage_disc_get_session_before (MirageDisc *self,
                                MirageSession *session,
                                GError **error);

Retrieves session that comes before session .

Parameters

self

a MirageDisc

 

session

a session.

[in]

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

MirageSession *
mirage_disc_get_session_by_address (MirageDisc *self,
                                    gint address,
                                    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).

Parameters

self

a MirageDisc

 

address

address belonging to session to be retrieved.

[in]

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

MirageSession *
mirage_disc_get_session_by_index (MirageDisc *self,
                                  gint index,
                                  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.

Parameters

self

a MirageDisc

 

index

index of session to be retrieved.

[in]

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

MirageSession *
mirage_disc_get_session_by_number (MirageDisc *self,
                                   gint number,
                                   GError **error);

Retrieves session by session number.

Parameters

self

a MirageDisc

 

number

number of session to be retrieved.

[in]

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

MirageSession *
mirage_disc_get_session_by_track (MirageDisc *self,
                                  gint track,
                                  GError **error);

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

Parameters

self

a MirageDisc

 

track

number of track belonging to session to be retrieved.

[in]

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

MirageTrack *
mirage_disc_get_track_by_address (MirageDisc *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 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().

Parameters

self

a MirageDisc

 

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

MirageTrack *
mirage_disc_get_track_by_index (MirageDisc *self,
                                gint index,
                                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().

Parameters

self

a MirageDisc

 

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

MirageTrack *
mirage_disc_get_track_by_number (MirageDisc *self,
                                 gint number,
                                 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().

Parameters

self

a MirageDisc

 

number

track 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_disc_layout_contains_address ()

gboolean
mirage_disc_layout_contains_address (MirageDisc *self,
                                     gint address);

Checks whether the disc contains the given address or not.

Parameters

self

a MirageDisc

 

address

address to be checked

 

Returns

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


mirage_disc_layout_get_first_session ()

gint
mirage_disc_layout_get_first_session (MirageDisc *self);

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

Intended for internal use only.

Parameters

self

a MirageDisc

 

Returns

first session number


mirage_disc_layout_get_first_track ()

gint
mirage_disc_layout_get_first_track (MirageDisc *self);

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

Intended for internal use only.

Parameters

self

a MirageDisc

 

Returns

first track number


mirage_disc_layout_get_length ()

gint
mirage_disc_layout_get_length (MirageDisc *self);

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

Parameters

self

a MirageDisc

 

Returns

disc layout length


mirage_disc_layout_get_start_sector ()

gint
mirage_disc_layout_get_start_sector (MirageDisc *self);

Retrieves start sector of the disc layout.

Intended for internal use only.

Parameters

self

a MirageDisc

 

Returns

start sector


mirage_disc_layout_set_first_session ()

void
mirage_disc_layout_set_first_session (MirageDisc *self,
                                      gint first_session);

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

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

Parameters

self

a MirageDisc

 

first_session

first session number.

[in]

mirage_disc_layout_set_first_track ()

void
mirage_disc_layout_set_first_track (MirageDisc *self,
                                    gint first_track);

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

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

Parameters

self

a MirageDisc

 

first_track

first track number.

[in]

mirage_disc_layout_set_start_sector ()

void
mirage_disc_layout_set_start_sector (MirageDisc *self,
                                     gint start_sector);

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.

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

Parameters

self

a MirageDisc

 

start_sector

start sector.

[in]

mirage_disc_put_sector ()

gboolean
mirage_disc_put_sector (MirageDisc *self,
                        MirageSector *sector,
                        GError **error);

Writes the sector to disc.

This function attempts to retrieve appropriate track using mirage_disc_get_track_by_address(), then writes sector object using mirage_track_put_sector(); therefore, same restrictions regarding sector address apply as when putting sector directly to track.

Parameters

self

a MirageDisc

 

sector

a MirageSector representing sector to be written.

[in]

error

location to store error, or NULL.

[out][allow-none]

Returns

TRUE on success, FALSE on failure.


mirage_disc_remove_session_by_index ()

gboolean
mirage_disc_remove_session_by_index (MirageDisc *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.

Causes bottom-up change.

Parameters

self

a MirageDisc

 

index

index of session to be removed.

[in]

error

location to store error, or NULL.

[out][allow-none]

Returns

TRUE on success, FALSE on failure


mirage_disc_remove_session_by_number ()

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

Removes session from disc layout.

number is session number of the session to be removed.

Causes bottom-up change.

Parameters

self

a MirageDisc

 

number

session number of session to be removed.

[in]

error

location to store error, or NULL.

[out][allow-none]

Returns

TRUE on success, FALSE on failure


mirage_disc_remove_session_by_object ()

void
mirage_disc_remove_session_by_object (MirageDisc *self,
                                      MirageSession *session);

Removes session from disc layout.

session is a MirageSession object to be removed.

Causes bottom-up change.

Parameters

self

a MirageDisc

 

session

session object to be removed.

[in]

mirage_disc_remove_track_by_index ()

gboolean
mirage_disc_remove_track_by_index (MirageDisc *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.

Causes bottom-up change.

Parameters

self

a MirageDisc

 

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

gboolean
mirage_disc_remove_track_by_number (MirageDisc *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.

Causes bottom-up change.

Parameters

self

a MirageDisc

 

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

void
mirage_disc_set_disc_structure (MirageDisc *self,
                                gint layer,
                                gint type,
                                const guint8 *data,
                                gint len);

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

Disc structures are valid only for DVD and BD discs. This function silently fails on invalid disc types.

Parameters

self

a MirageDisc

 

layer

disc layer.

[in]

type

disc structure type.

[in]

data

disc structure data to be set.

[in][array length=len]

len

length of disc structure data.

[in]

mirage_disc_set_dpm_data ()

void
mirage_disc_set_dpm_data (MirageDisc *self,
                          gint start,
                          gint resolution,
                          gint num_entries,
                          const guint32 *data);

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 .

Parameters

self

a MirageDisc

 

start

DPM start sector.

[in]

resolution

DPM data resolution.

[in]

num_entries

number of DPM entries.

[in]

data

buffer containing DPM data.

[in][array length=num_entries]

mirage_disc_set_filename ()

void
mirage_disc_set_filename (MirageDisc *self,
                          const gchar *filename);

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

Intended for internal use only, in image parser implementations.

Parameters

self

a MirageDisc

 

filename

filename.

[in]

mirage_disc_set_filenames ()

void
mirage_disc_set_filenames (MirageDisc *self,
                           gchar **filenames);

Sets image filename(s).

Intended for internal use only, in image parser implementations.

Parameters

self

a MirageDisc

 

filenames

NULL-terminated array of filenames.

[in][array zero-terminated=1]

mirage_disc_set_medium_type ()

void
mirage_disc_set_medium_type (MirageDisc *self,
                             MirageMediumType medium_type);

Sets medium type. medium_type must be one of MirageMediumType.

Intended for internal use only.

Parameters

self

a MirageDisc

 

medium_type

medium type.

[in]

Types and Values

MirageDisc

typedef struct _MirageDisc MirageDisc;

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


struct MirageDiscClass

struct MirageDiscClass {
    MirageObjectClass parent_class;
};

The class structure for the MirageDisc type.

Members


enum MirageMediumType

Medium types.

Members

MIRAGE_MEDIUM_CD

CD disc

 

MIRAGE_MEDIUM_DVD

DVD disc

 

MIRAGE_MEDIUM_BD

BD (Blue-Ray) disc

 

MIRAGE_MEDIUM_HD

HD-DVD disc

 

MIRAGE_MEDIUM_HDD

Hard-disk

 

Signal Details

The “layout-changed” signal

void
user_function (MirageDisc *disc,
               gpointer    user_data)

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

Parameters

disc

a MirageDisc

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

See Also

MirageSession, MirageTrack, MirageObject, MirageParser, MirageWriter, MirageContext