Mirage.Disc¶

Subclasses:: None

Methods¶

Inherited:: Mirage.Object (2), GObject.Object (37), Mirage.Contextual (8)
Structs:: GObject.ObjectClass (5)

	`add_session_by_index` (index, session)
	`add_session_by_number` (number, session)
	`add_track_by_index` (index, track)
	`add_track_by_number` (number, track)
	`enumerate_sessions` (func, *user_data)
	`get_disc_structure` (layer, type)
	`get_dpm_data` ()
	`get_dpm_data_for_sector` (address)
	`get_filenames` ()
	`get_medium_type` ()
	`get_number_of_sessions` ()
	`get_number_of_tracks` ()
	`get_sector` (address)
	`get_session_after` (session)
	`get_session_before` (session)
	`get_session_by_address` (address)
	`get_session_by_index` (index)
	`get_session_by_number` (number)
	`get_session_by_track` (track)
	`get_track_by_address` (address)
	`get_track_by_index` (index)
	`get_track_by_number` (number)
	`layout_contains_address` (address)
	`layout_get_first_session` ()
	`layout_get_first_track` ()
	`layout_get_length` ()
	`layout_get_start_sector` ()
	`layout_set_first_session` (first_session)
	`layout_set_first_track` (first_track)
	`layout_set_start_sector` (start_sector)
	`put_sector` (sector)
	`remove_session_by_index` (index)
	`remove_session_by_number` (number)
	`remove_session_by_object` (session)
	`remove_track_by_index` (index)
	`remove_track_by_number` (number)
	`set_disc_structure` (layer, type, data)
	`set_dpm_data` (start, resolution, data)
	`set_filename` (filename)
	`set_filenames` (filenames)
	`set_medium_type` (medium_type)

Virtual Methods¶

Inherited:: GObject.Object (7), Mirage.Contextual (2)

Properties¶

None

Signals¶

Inherited:: Mirage.Object (1), GObject.Object (1)

Name	Short Description
`layout-changed`	Emitted when a layout of `Mirage.Disc` changed in a way that causes a bottom-up change.

Fields¶

Inherited:: Mirage.Object (1), GObject.Object (1)

Name	Type	Access	Description
parent_instance	`Mirage.Object`	r

Class Details¶

class Mirage.Disc(**kwargs)¶

Bases:: Mirage.Object
Abstract:: No
Structure:: Mirage.DiscClass

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

add_session_by_index(index, session)¶

Parameters:

index (int) – index at which session should be added
session (Mirage.Session) – a Mirage.Session to be added

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.

add_session_by_number(number, session)¶

Parameters:

number (int) – session number for the added session
session (Mirage.Session) – a Mirage.Session to be added

Raises:

GLib.Error

Returns:

True on success, False on failure

Return type:

bool

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.

add_track_by_index(index, track)¶

Parameters:

index (int) – index at which track should be added
track (Mirage.Track) – a Mirage.Track to be added

Raises:

GLib.Error

Returns:

True on success, False on failure

Return type:

bool

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.

add_track_by_number(number, track)¶

Parameters:

number (int) – track number for the added track
track (Mirage.Track) – a Mirage.Track to be added

Raises:

GLib.Error

Returns:

True on success, False on failure

Return type:

bool

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.

enumerate_sessions(func, *user_data)¶

Parameters:

func (Mirage.EnumSessionCallback) – callback function
user_data (object or None) – data to be passed to callback function

Returns:

True on success, False on failure

Return type:

bool

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

If func returns False, the function immediately returns False.

get_disc_structure(layer, type)¶

Parameters:

layer (int) – disc layer
type (int) – disc structure type

Raises:

GLib.Error

Returns:

True on success, False on failure

data:: location to store buffer containing disc structure data, or None

Return type:

(bool, data: bytes)

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.MediumType.DVD or Mirage.MediumType.BD prior to calling this function, the function will fail.

get_dpm_data()¶

Returns:

start:: location to store DPM start sector, or None
resolution:: location to store DPM data resolution, or None
data:: location to store pointer to buffer containing DPM data, or None

Return type:

(start: int, resolution: int, data: [int])

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.

get_dpm_data_for_sector(address)¶

Parameters:

address (int) – address of sector to retrieve DPM data for

Raises:

GLib.Error

Returns:

True on success, False on failure

angle:: location to store sector angle, or None
density:: location to store sector density, or None

Return type:

(bool, angle: float, density: float)

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

get_filenames()¶

Returns:: pointer to None-terminated array of filenames. The array belongs to the object and should not be modified.
Return type:: [str]

Retrieves image filename(s).

get_medium_type()¶

Returns:: medium type
Return type:: Mirage.MediumType

Retrieves medium type.

get_number_of_sessions()¶

Returns:: number of sessions
Return type:: int

Retrieves number of sessions in the disc layout.

get_number_of_tracks()¶

Returns:: number of tracks
Return type:: int

Retrieves number of tracks in the disc layout.

get_sector(address)¶

Parameters:: address (int) – sector address
Raises:: GLib.Error
Returns:: sector object on success, None on failure
Return type:: Mirage.Sector

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

get_session_after(session)¶

Parameters:: session (Mirage.Session) – a session
Raises:: GLib.Error
Returns:: a Mirage.Session on success, None on failure. The reference to the object should be released using GObject.Object.unref() when no longer needed.
Return type:: Mirage.Session

Retrieves session that comes after session.

get_session_before(session)¶

Parameters:: session (Mirage.Session) – a session
Raises:: GLib.Error
Returns:: a Mirage.Session on success, None on failure. The reference to the object should be released using GObject.Object.unref() when no longer needed.
Return type:: Mirage.Session

Retrieves session that comes before session.

get_session_by_address(address)¶

Parameters:: address (int) – address belonging to session to be retrieved
Raises:: GLib.Error
Returns:: a Mirage.Session on success, None on failure. The reference to the object should be released using GObject.Object.unref() when no longer needed.
Return type:: Mirage.Session

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

get_session_by_index(index)¶

Parameters:: index (int) – index of session to be retrieved
Raises:: GLib.Error
Returns:: a Mirage.Session on success, None on failure. The reference to the object should be released using GObject.Object.unref() when no longer needed.
Return type:: Mirage.Session

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.

get_session_by_number(number)¶

Parameters:: number (int) – number of session to be retrieved
Raises:: GLib.Error
Returns:: a Mirage.Session on success, None on failure. The reference to the object should be released using GObject.Object.unref() when no longer needed.
Return type:: Mirage.Session

Retrieves session by session number.

get_session_by_track(track)¶

Parameters:: track (int) – number of track belonging to session to be retrieved
Raises:: GLib.Error
Returns:: a Mirage.Session on success, None on failure. The reference to the object should be released using GObject.Object.unref() when no longer needed.
Return type:: Mirage.Session

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

get_track_by_address(address)¶

Parameters:: address (int) – address belonging to track to be retrieved
Raises:: GLib.Error
Returns:: a Mirage.Track on success, None on failure. The reference to the object should be released using GObject.Object.unref() when no longer needed.
Return type:: Mirage.Track

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

get_track_by_index(index)¶

Parameters:: index (int) – index of track to be retrieved
Raises:: GLib.Error
Returns:: a Mirage.Track on success, None on failure. The reference to the object should be released using GObject.Object.unref() when no longer needed.
Return type:: Mirage.Track

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

get_track_by_number(number)¶

Parameters:: number (int) – track number of track to be retrieved
Raises:: GLib.Error
Returns:: a Mirage.Track on success, None on failure. The reference to the object should be released using GObject.Object.unref() when no longer needed.
Return type:: Mirage.Track

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

layout_contains_address(address)¶

Parameters:: address (int) – address to be checked
Returns:: True if address falls inside disc, False if it does not
Return type:: bool

Checks whether the disc contains the given address or not.

layout_get_first_session()¶

Returns:: first session number
Return type:: int

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

Intended for internal use only.

layout_get_first_track()¶

Returns:: first track number
Return type:: int

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

Intended for internal use only.

layout_get_length()¶

Returns:: disc layout length
Return type:: int

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

layout_get_start_sector()¶

Returns:: start sector
Return type:: int

Retrieves start sector of the disc layout.

Intended for internal use only.

layout_set_first_session(first_session)¶

Parameters:: first_session (int) – first session number

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.

layout_set_first_track(first_track)¶

Parameters:: first_track (int) – first track number

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.

layout_set_start_sector(start_sector)¶

Parameters:: start_sector (int) – 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.

put_sector(sector)¶

Parameters:: sector (Mirage.Sector) – a Mirage.Sector representing sector to be written
Raises:: GLib.Error
Returns:: True on success, False on failure.
Return type:: bool

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.

remove_session_by_index(index)¶

Parameters:: index (int) – index of session to be removed
Raises:: GLib.Error
Returns:: True on success, False on failure
Return type:: bool

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.

remove_session_by_number(number)¶

Parameters:: number (int) – session number of session to be removed
Raises:: GLib.Error
Returns:: True on success, False on failure
Return type:: bool

Removes session from disc layout.

number is session number of the session to be removed.

Causes bottom-up change.

remove_session_by_object(session)¶

Parameters:: session (Mirage.Session) – session object to be removed

Removes session from disc layout.

session is a Mirage.Session object to be removed.

Causes bottom-up change.

remove_track_by_index(index)¶

Parameters:: index (int) – index of track to be removed
Raises:: GLib.Error
Returns:: True on success, False on failure
Return type:: bool

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.

remove_track_by_number(number)¶

Parameters:: number (int) – track number of track to be removed
Raises:: GLib.Error
Returns:: True on success, False on failure
Return type:: bool

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.

set_disc_structure(layer, type, data)¶

Parameters:

layer (int) – disc layer
type (int) – disc structure type
data (bytes) – disc structure data to be set

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.

set_dpm_data(start, resolution, data)¶

Parameters:

start (int) – DPM start sector
resolution (int) – DPM data resolution
data ([int]) – buffer containing DPM 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.

set_filename(filename)¶

Parameters:: filename (str) – 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.

set_filenames(filenames)¶

Parameters:: filenames ([str]) – None-terminated array of filenames

Sets image filename(s).

Intended for internal use only, in image parser implementations.

set_medium_type(medium_type)¶

Parameters:: medium_type (Mirage.MediumType) – medium type

Sets medium type. medium_type must be one of Mirage.MediumType.

Intended for internal use only.

Signal Details¶

Mirage.Disc.signals.layout_changed(disc)¶

Signal Name:: layout-changed
Flags:: RUN_LAST
Parameters:: disc (Mirage.Disc) – The object which received the signal

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