Functions ¶

Returns:

True on success, False on failure

code:: location to store language code, or None
charset:: location to store character set, or None
copyright:: location to store copyright flag, or None

Return type:

(bool, code: int, charset: int, copyright: int)

Retrieves block information for CD-TEXT block specified by block. block must be a valid block number (0-7). Language code assigned to the block is stored in code, code of character set used within block is stored in charset and block’s copyright flag is stored in copyright.

Mirage.cdtext_decoder_get_data(self, block, callback_func, *user_data)¶

Parameters:

self (Mirage.CdTextCoder) – a Mirage.CdTextCoder
block (int) – block number
callback_func (Mirage.CdTextDataCallback) – callback function
user_data (object or None) – data to be passed to callback function

Returns:

True on success, False on failure

Return type:

Retrieves data for CD-TEXT block specified by block. block must be a valid block number (0-7). It calls callback_func for every data pack that has been encoded in the block.

If callback_func returns False, the function immediately returns False.

Mirage.cdtext_decoder_init(self, buffer)¶

Parameters:

self (Mirage.CdTextCoder) – a Mirage.CdTextCoder
buffer (bytes) – buffer containing encoded data

Initializes CD-TEXT decoder. buffer is the buffer containing encoded CD-TEXT data and buflen is length of data in the buffer.

This function decodes CD-TEXT data and stores it in decoder’s internal representation. Information about decoded CD-TEXT blocks and their data can be obtained via subsequent calls to Mirage.cdtext_decoder_get_block_info() and Mirage.cdtext_decoder_get_data().

Mirage.cdtext_encoder_add_data(self, code, type, track, data)¶

Parameters:

self (Mirage.CdTextCoder) – a Mirage.CdTextCoder
code (int) – language code
type (int) – data type
track (int) – track number
data (bytes) – data

Adds data to the encoder. code is language code of the block the data should be added to. type denotes pack type and should be one of Mirage.LanguagePackType. track is track number the data belongs to, or 0 if data is global (belongs to disc/session). data is buffer containing data to be added, and data_len is length of data in the buffer.

This function does not perform any encoding yet; it merely adds the data into encoder’s internal representation of CD-TEXT block.

Block needs to have its information set with Mirage.cdtext_encoder_set_block_info() before data can be added to it.

Mirage.cdtext_encoder_encode(self)¶

Parameters:: self (Mirage.CdTextCoder) – a Mirage.CdTextCoder
Returns:: location to store buffer
Return type:: buffer: bytes

Encodes the CD-TEXT data. Pointer to buffer containing the encoded data is stored in buffer, and length of data in buffer is stored in buflen.

Note that buffer is the same as the argument passed to Mirage.cdtext_encoder_init().

Mirage.cdtext_encoder_init(self, buffer)¶

Parameters:

self (Mirage.CdTextCoder) – a Mirage.CdTextCoder
buffer (bytes) – buffer into which data will be encoded

Initializes CD-TEXT encoder.

Mirage.cdtext_encoder_set_block_info(self, block, code, charset, copyright)¶

Parameters:

self (Mirage.CdTextCoder) – a Mirage.CdTextCoder
block (int) – block number
code (int) – language code
charset (int) – character set
copyright (int) – copyright flag

Raises:

Returns:

True on success, False on failure

Return type:

Sets block information for CD-TEXT block specified by block. block must be a valid block number (0-7). code is the language code that is to be assigned to the block (e.g. 9 for English), charset denotes character set that is used within the block, and copyright is the copyright flag for the block.

Mirage.create_writer(writer_id)¶

Parameters:: writer_id (str) – ID of writer to create
Raises:: GLib.Error
Returns:: newly-created writer object on success, None on failure. The reference to the object should be released using GObject.Object.unref() when no longer needed.
Return type:: Mirage.Writer

Attempts to create an instance of image writer whose ID is writer_id.

Mirage.enumerate_filter_streams(func, *user_data)¶

Parameters:

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

Raises:

Returns:

True on success, False on failure

Return type:

Iterates over list of supported filter streams, calling func for each filter stream.

If func returns False, the function immediately returns False.

Mirage.enumerate_parsers(func, *user_data)¶

Parameters:

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

Raises:

Returns:

True on success, False on failure

Return type:

Iterates over list of supported parsers, calling func for each parser.

If func returns False, the function immediately returns False.

Mirage.enumerate_writers(func, *user_data)¶

Parameters:

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

Raises:

Returns:

True on success, False on failure

Return type:

Iterates over list of supported writers, calling func for each writers.

If func returns False, the function immediately returns False.

Mirage.error_quark()¶

Returns:: The error quark used for libMirage errors.
Return type:: int

Registers an error quark for libMirage if necessary.

Mirage.get_filter_streams_info()¶

Raises:

Returns:

True on success, False on failure

info:: array of filter streams’ information structures

Return type:

(bool, info: [Mirage.FilterStreamInfo])

Retrieves information structures for supported filter streams.

Mirage.get_filter_streams_type()¶

Raises:

Returns:

True on success, False on failure

types:: array of filter streams’ GObject.GType values

Return type:

(bool, types: [GObject.GType])

Retrieves GObject.GType values for supported filter streams.

Mirage.get_parsers_info()¶

Raises:

Returns:

True on success, False on failure

info:: array of parsers’ information structures

Return type:

(bool, info: [Mirage.ParserInfo])

Retrieves information structures for supported parsers.

Mirage.get_parsers_type()¶

Raises:

Returns:

True on success, False on failure

types:: array of parsers’ GObject.GType values

Return type:

(bool, types: [GObject.GType])

Retrieves GObject.GType values for supported parsers.

Mirage.get_supported_debug_masks()¶

Raises:

Returns:

True on success, False on failure

masks:: location to store pointer to masks array

Return type:

(bool, masks: [Mirage.DebugMaskInfo])

Retrieves the pointer to array of supported debug masks and stores it in masks. The array consists of one or more structures of type Mirage.DebugMaskInfo. The number of elements in the array is stored in num_masks. The array belongs to libMirage and should not be altered or freed.

Mirage.get_writers_info()¶

Raises:

Returns:

True on success, False on failure

info:: array of writers’ information structures

Return type:

(bool, info: [Mirage.WriterInfo])

Retrieves information structures for supported parsers.

Mirage.get_writers_type()¶

Raises:

Returns:

True on success, False on failure

types:: array of writers’ GObject.GType values

Return type:

(bool, types: [GObject.GType])

Retrieves GObject.GType values for supported writers.

Mirage.helper_ascii2isrc(c)¶

Parameters:: c (int) – ASCII character
Returns:: ISRC character
Return type:: int

Converts ASCII character c into ISRC character.

Mirage.helper_bcd2hex(bcd)¶

Parameters:: bcd (int) – bcd-encoded integer
Returns:: hex-encoded integer
Return type:: int

Converts bcd-encoded integer into hex-encoded integer.

Mirage.helper_calculate_crc16(data, crctab, reflected, invert)¶

Parameters:

data (bytes) – buffer containing data
crctab ([int]) – pointer to CRC polynomial table
reflected (bool) – whether to use the reflected algorithm
invert (bool) – whether the result should be inverted

Returns:

CRC-16 checksum of data

Return type:

Calculates the CRC-16 checksum of the data stored in data.

Mirage.helper_calculate_crc32_fast(data, crctab, reflected, invert)¶

Parameters:

data (bytes) – buffer containing data
crctab ([int]) – pointer to CRC polynomial table
reflected (bool) – whether to use the reflected algorithm
invert (bool) – whether the initial value and result should be inverted

Returns:

CRC-32 checksum of data

Return type:

Calculates the CRC-32 checksum of the data stored in data. This is fast slice-by-8 implementation that processes 8 bytes at a time, and requires crctab to be allocating using Mirage.helper_init_crc32_lut() with slice parameter set to 8.

Mirage.helper_calculate_crc32_standard(data, crctab, reflected, invert)¶

Parameters:

data (bytes) – buffer containing data
crctab ([int]) – pointer to CRC polynomial table
reflected (bool) – whether to use the reflected algorithm
invert (bool) – whether the initial value and result should be inverted

Returns:

CRC-32 checksum of data

Return type:

Calculates the CRC-32 checksum of the data stored in data. This is standard inplementation that processes 1 byte at a time, and requires crctab to be allocated using Mirage.helper_init_crc32_lut() with slice parameter set to 1.

Mirage.helper_determine_sector_type(buf)¶

Parameters:: buf (int) – buffer containing at least first 16 bytes of sector’s data
Returns:: sector type (one of Mirage.SectorType)
Return type:: Mirage.SectorType

Determines sector type from its data, based on first 16 bytes, which correspond to sync pattern and header.

This function is intened to be used in image parsers, for determining track mode in cases when full (2352-byte) sector data is available.

Mirage.helper_encoding_from_bom(buffer)¶

Parameters:: buffer (bytes) – a 4-byte buffer containing BOM
Returns:: the name of encoding, or None if UTF-8 is assumed. The string is statically stored and should not be modified.
Return type:: str

Tries to decode BOM provided in buffer, and based on the result returns the following encodings: UTF-32BE, UTF32-LE, UTF-16LE, UTF-16BE or UTF-8 (if BOM is not valid).

Mirage.helper_find_data_file(filename, path)¶

Parameters:

filename (str) – declared filename
path (str or None) – path where to look for file (can be a filename), or None

Returns:

a newly allocated string containing the fullpath of file, or None.

Return type:

str

Attempts to find a file with filename filename and path path. filename can be file’s basename or an absolute path. path can be either directory path (in this case, it must end with ‘/’) or a filename (i.e. of file descriptor).

If filename is an absolute path, its existence is first checked. If it does not exist, search (see below) is performed in filename's dirname. If still no match is found and path is not None, path's dirname is combined with filename's basename, and the combination’s existence is checked. If that fails as well, search (see below) is performed in path's dirname. Searching in the directory is performed as follows. Directory is opened and its content is case-insensitively compared to filename's basename. All filenames whose beginning match filename are considered, and the shortest one is returned. This way, all possible case variations (i.e. file.iso, FILE.ISO, FiLe.IsO, etc.) are taken into account. This function can return a filename with additional suffices, but only if a file without those extra suffices does not exist. E.g., if search is done for ‘data.img’, and only ‘data.img.gz’ exists, it will be returned. However, if both ‘data.img’ and ‘data.img.gz’ exist, the former will be returned. The returned string should be freed when no longer needed.

Mirage.helper_format_stringd(format, dictionary)¶

Parameters:

format (str) – format string
dictionary ({object: object}) – a GLib.HashTable containing replacement token/value pairs

Returns:

string with all replacement tokens either replaced or removed. The string should be freed using GLib.free() when no longer needed.

Return type:

str

Dictionary-version of mirage_helper_format_string().

dictionary is a GLib.HashTable where keys are replacement token strings and each value is a GLib.Variant containing corresponding token replacement value.

Mirage.helper_get_suffix(filename)¶

Parameters:: filename (str) – filename
Returns:: pointer to character in filename at which the suffix starts.
Return type:: str

Retrieves suffix from filename.

Mirage.helper_has_suffix(filename, suffix)¶

Parameters:

filename (str) – filename
suffix (str) – suffix

Returns:

True if filename contains suffix suffix, False if not

Return type:

Checks whether file name filename ends with suffix suffix.

Mirage.helper_hex2bcd(hex)¶

Parameters:: hex (int) – hex-encoded integer
Returns:: bcd-encoded integer
Return type:: int

Converts hex-encoded integer into bcd-encoded integer.

Mirage.helper_init_crc16_lut(genpoly)¶

Parameters:: genpoly (int) – generator polynomial
Returns:: Pointer to the CRC16 look-up table or None on failure.
Return type:: int

Calculates a look-up table for CRC16 based on the generator polynomial.

Mirage.helper_init_crc32_lut(genpoly, slices)¶

Parameters:

genpoly (int) – generator polynomial
slices (int) – number of bytes to process at once

Returns:

Pointer to the CRC32 look-up table or None on failure.

Return type:

Calculates a look-up table for CRC32 based on the generator polynomial. The size of the lookup table depends on slices. The standard algorithm processes 1 byte at a time and has a look-up table size of 1KiB, whereas The slice-by-4 and slice-by-8 algorithms use 4 and 8 KiB look-up tables that are derived from the initial look-up table.

Mirage.helper_init_ecma_130b_scrambler_lut()¶

Returns:: Pointer to the generated scrambler look-up table or None on failure.
Return type:: int

Calculates a look-up table for sector data scrambler from ECMA-130, Annex B. The look-up table consists of 2340 entries, each being a scramble byte for corresponding byte in sector data.

Mirage.helper_isrc2ascii(c)¶

Parameters:: c (int) – ISRC character
Returns:: ACSII character
Return type:: int

Converts ISRC character c into ASCII character.

Mirage.helper_lba2msf(lba, diff)¶

Parameters:

lba (int) – LBA address
diff (bool) – account for the difference

Returns:

m:: location to store minutes, or None
s:: location to store seconds, or None
f:: location to store frames, or None

Return type:

(m: int, s: int, f: int)

Converts LBA sector address stored in lba into MSF address, storing each field into m, s and f, respectively.

If diff is True, 150 frames difference is accounted for; this should be used when converting absolute addresses. When converting relative addresses (or lengths), diff should be set to False.

Mirage.helper_lba2msf_str(lba, diff)¶

Parameters:

lba (int) – LBA address
diff (bool) – account for the difference

Returns:

a newly-allocated string containing MSF address; it should be freed with GLib.free() when no longer needed.

Return type:

str

Converts LBA sector address stored in lba into MSF address.

If diff is True, 150 frames difference is accounted for; this should be used when converting absolute addresses. When converting relative addresses (or lengths), diff should be set to False.

Mirage.helper_msf2lba(m, s, f, diff)¶

Parameters:

m (int) – minutes
s (int) – seconds
f (int) – frames
diff (bool) – difference

Returns:

integer representing LBA address

Return type:

Converts MSF sector address stored in m, s and f into LBA address.

If diff is True, 150 frames difference is accounted for; this should be used when converting absolute addresses. When converting relative addresses (or lengths), diff should be set to False.

Mirage.helper_msf2lba_str(msf, diff)¶

Parameters:

msf (str) – MSF string
diff (bool) – difference

Returns:

integer representing LBA address or -1 on failure.

Return type:

Converts MSF sector address stored in msf string into LBA address.

If diff is True, 150 frames difference is accounted for; this should be used when converting absolute addresses. When converting relative addresses (or lengths), diff should be set to False.

Mirage.helper_sector_edc_ecc_compute_ecc_block(src, major_count, minor_count, major_mult, minor_inc)¶

Parameters:

src (int) – data to calculate ECC data for
major_count (int) – major count
minor_count (int) – minor count
major_mult (int) – major multiplicator
minor_inc (int) – minor increment

Returns:

buffer to write calculated ECC data into

Return type:

dest: int

Calculates ECC (error correction code) for data in src and writes the result into dest. The code assumes 2352 byte sectors. It can calculate both P and Q layer of ECC data, depending on major_count, minor_count, major_mult and minor_inc.

To calculate ECC (first P, then Q layer) for different types of sectors and store it into sector data, use:

Mode 1 sector:

mirage_helper_sector_edc_ecc_compute_ecc_block(sector_buffer+0xC, 86, 24, 2, 86, sector_buffer+0x81C);
mirage_helper_sector_edc_ecc_compute_ecc_block(sector_buffer+0xC, 52, 43, 86, 88, sector_buffer+0x8C8);

Mode 2 Form 1 sector:

mirage_helper_sector_edc_ecc_compute_ecc_block(sector_buffer+0xC, 86, 24, 2, 86, sector_buffer+0x81C); \n
mirage_helper_sector_edc_ecc_compute_ecc_block(sector_buffer+0xC, 52, 43, 86, 88, sector_buffer+0x8C8);

(This is assuming all other sector data, including EDC, is already stored in sector_buffer and that sector_buffer is 2532 bytes long)

Mirage.helper_sector_edc_ecc_compute_edc_block(src)¶

Parameters:: src (bytes) – data to calculate EDC data for
Returns:: buffer to write calculated EDC data into (4 bytes)
Return type:: dest: bytes

Calculates EDC (error detection code) for data in src of length size and writes the result into dest.

To calculate EDC for different types of sectors and store it into sector data, use:

Mode 1 sector: mirage_helper_sector_edc_ecc_compute_edc_block(sector_buffer+0x00, 0x810, sector_buffer+0x810);
Mode 2 Form 1 sector: mirage_helper_sector_edc_ecc_compute_edc_block(sector_buffer+0x10, 0x808, sector_buffer+0x818);
Mode 2 Form 2 sector: mirage_helper_sector_edc_ecc_compute_edc_block(sector_buffer+0x10, 0x91C, sector_buffer+0x92C);

(This is assuming all other sector data is already stored in sector_buffer and that sector_buffer is 2532 bytes long)

Mirage.helper_strcasecmp(str1, str2)¶

Parameters:

str1 (str) – first string
str2 (str) – second string

Returns:

an integer less than, equal to, or greater than zero if str1 is found, respectively, to be less than, to match, or be greater than str2.

Return type:

Replacement function for GLib.strcasecmp/strcasecmp, which can properly handle UTF-8. Glib docs state this is only an approximation, albeit it should be a fairly good one.

It compares the two strings str1 and str2, ignoring the case of the characters. It returns an integer less than, equal to, or greater than zero if str1 is found, respectively, to be less than, to match, or be greater than str2.

Mirage.helper_strncasecmp(str1, str2, len)¶

Parameters:

str1 (str) – first string
str2 (str) – second string
len (int) – length of string to compare

Returns:

an integer less than, equal to, or greater than zero if first len characters of str1 is found, respectively, to be less than, to match, or be greater than first len characters of str2.

Return type: