MirageFragment

MirageFragment — Fragment object.

Synopsis

#include <mirage-fragment.h>

                    MirageFragment;
struct              MirageFragmentClass;
enum                MirageMainDataFormat;
enum                MirageSubchannelDataFormat;
gboolean            mirage_fragment_contains_address    (MirageFragment *self,
                                                         gint address);
gint                mirage_fragment_get_address         (MirageFragment *self);
gint                mirage_fragment_get_length          (MirageFragment *self);
gboolean            mirage_fragment_is_writable         (MirageFragment *self);
const gchar *       mirage_fragment_main_data_get_filename
                                                        (MirageFragment *self);
gint                mirage_fragment_main_data_get_format
                                                        (MirageFragment *self);
guint64             mirage_fragment_main_data_get_offset
                                                        (MirageFragment *self);
gint                mirage_fragment_main_data_get_size  (MirageFragment *self);
void                mirage_fragment_main_data_set_format
                                                        (MirageFragment *self,
                                                         gint format);
void                mirage_fragment_main_data_set_offset
                                                        (MirageFragment *self,
                                                         guint64 offset);
void                mirage_fragment_main_data_set_size  (MirageFragment *self,
                                                         gint size);
void                mirage_fragment_main_data_set_stream
                                                        (MirageFragment *self,
                                                         MirageStream *stream);
gboolean            mirage_fragment_read_main_data      (MirageFragment *self,
                                                         gint address,
                                                         guint8 **buffer,
                                                         gint *length,
                                                         GError **error);
gboolean            mirage_fragment_write_main_data     (MirageFragment *self,
                                                         gint address,
                                                         const guint8 *buffer,
                                                         gint length,
                                                         GError **error);
gboolean            mirage_fragment_read_subchannel_data
                                                        (MirageFragment *self,
                                                         gint address,
                                                         guint8 **buffer,
                                                         gint *length,
                                                         GError **error);
gboolean            mirage_fragment_write_subchannel_data
                                                        (MirageFragment *self,
                                                         gint address,
                                                         const guint8 *buffer,
                                                         gint length,
                                                         GError **error);
void                mirage_fragment_set_address         (MirageFragment *self,
                                                         gint address);
void                mirage_fragment_set_length          (MirageFragment *self,
                                                         gint length);
const gchar *       mirage_fragment_subchannel_data_get_filename
                                                        (MirageFragment *self);
gint                mirage_fragment_subchannel_data_get_format
                                                        (MirageFragment *self);
guint64             mirage_fragment_subchannel_data_get_offset
                                                        (MirageFragment *self);
gint                mirage_fragment_subchannel_data_get_size
                                                        (MirageFragment *self);
void                mirage_fragment_subchannel_data_set_format
                                                        (MirageFragment *self,
                                                         gint format);
void                mirage_fragment_subchannel_data_set_offset
                                                        (MirageFragment *self,
                                                         guint64 offset);
void                mirage_fragment_subchannel_data_set_size
                                                        (MirageFragment *self,
                                                         gint size);
void                mirage_fragment_subchannel_data_set_stream
                                                        (MirageFragment *self,
                                                         MirageStream *stream);
gboolean            mirage_fragment_use_the_rest_of_file
                                                        (MirageFragment *self,
                                                         GError **error);

Object Hierarchy

  GObject
   +----MirageObject
         +----MirageFragment

Implemented Interfaces

MirageFragment implements MirageContextual.

Signals

  "layout-changed"                                 : Run Last

Description

MirageFragment object represents an interface between a MirageTrack and I/O stream(s) containing the data. It allows tracks to read and/or write both sectors' main channel and subchannel data. When constructing a track, an image parser will typically create and append at least one fragment. Similarly, during image conversion and writing process, at least one fragment will be requested from image writer and written to.

A MirageFragment object is obtained using g_object_new() function. Both main channel and subchannel data I/O streams can be set using mirage_fragment_main_data_set_stream() and mirage_fragment_subchannel_data_set_stream() functions. If no streams are set, the fragment acts as a "NULL" fragment, and can be used to represent zero-filled pregaps and postgaps in tracks.

Details

MirageFragment

typedef struct _MirageFragment MirageFragment;

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


struct MirageFragmentClass

struct MirageFragmentClass {
    MirageObjectClass parent_class;
};

The class structure for the MirageFragment type.

MirageObjectClass parent_class;

the parent class

enum MirageMainDataFormat

typedef enum {
    MIRAGE_MAIN_DATA_FORMAT_DATA  = 0x01,
    MIRAGE_MAIN_DATA_FORMAT_AUDIO = 0x02,
    MIRAGE_MAIN_DATA_FORMAT_AUDIO_SWAP = 0x04,
} MirageMainDataFormat;

Track file data formats.

MIRAGE_MAIN_DATA_FORMAT_DATA

binary data

MIRAGE_MAIN_DATA_FORMAT_AUDIO

audio data

MIRAGE_MAIN_DATA_FORMAT_AUDIO_SWAP

audio data that needs to be swapped

enum MirageSubchannelDataFormat

typedef enum {
    MIRAGE_SUBCHANNEL_DATA_FORMAT_INTERNAL = 0x01,
    MIRAGE_SUBCHANNEL_DATA_FORMAT_EXTERNAL = 0x02,

    MIRAGE_SUBCHANNEL_DATA_FORMAT_PW96_INTERLEAVED = 0x10,
    MIRAGE_SUBCHANNEL_DATA_FORMAT_PW96_LINEAR = 0x20,
    MIRAGE_SUBCHANNEL_DATA_FORMAT_RW96 = 0x40,
    MIRAGE_SUBCHANNEL_DATA_FORMAT_Q16 = 0x80,
} MirageSubchannelDataFormat;

Subchannel file data formats.

MIRAGE_SUBCHANNEL_DATA_FORMAT_INTERNAL

internal subchannel (i.e. included in track file)

MIRAGE_SUBCHANNEL_DATA_FORMAT_EXTERNAL

external subchannel (i.e. provided by separate file)

MIRAGE_SUBCHANNEL_DATA_FORMAT_PW96_INTERLEAVED

P-W subchannel, 96 bytes, interleaved

MIRAGE_SUBCHANNEL_DATA_FORMAT_PW96_LINEAR

P-W subchannel, 96 bytes, linear

MIRAGE_SUBCHANNEL_DATA_FORMAT_RW96

R-W subchannel, 96 bytes, cooked

MIRAGE_SUBCHANNEL_DATA_FORMAT_Q16

Q subchannel, 16 bytes

mirage_fragment_contains_address ()

gboolean            mirage_fragment_contains_address    (MirageFragment *self,
                                                         gint address);

Checks whether the fragment contains the given address or not.

self :

a MirageFragment

address :

address to be checked

Returns :

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

mirage_fragment_get_address ()

gint                mirage_fragment_get_address         (MirageFragment *self);

Retrieves fragment's start address. The address is given in sectors.

Note

Intended for internal use only.

self :

a MirageFragment

Returns :

start address

mirage_fragment_get_length ()

gint                mirage_fragment_get_length          (MirageFragment *self);

Retrieves fragment's length. The returned length is given in sectors.

Note

Intended for internal use only.

self :

a MirageFragment

Returns :

length

mirage_fragment_is_writable ()

gboolean            mirage_fragment_is_writable         (MirageFragment *self);

Checks if fragment is writable, i.e., whether it has main channel data stream set and this stream is writable.

self :

a MirageFragment

Returns :

TRUE if fragment is writable, FALSE if it is not.

mirage_fragment_main_data_get_filename ()

const gchar *       mirage_fragment_main_data_get_filename
                                                        (MirageFragment *self);

Retrieves filename of main channel data stream.

self :

a MirageFragment

Returns :

pointer to main channel data file name string. The string belongs to object and should not be modified. [transfer none]

mirage_fragment_main_data_get_format ()

gint                mirage_fragment_main_data_get_format
                                                        (MirageFragment *self);

Retrieves main data file format.

self :

a MirageFragment

Returns :

main data file format

mirage_fragment_main_data_get_offset ()

guint64             mirage_fragment_main_data_get_offset
                                                        (MirageFragment *self);

Retrieves main data file offset.

self :

a MirageFragment

Returns :

main data file offset

mirage_fragment_main_data_get_size ()

gint                mirage_fragment_main_data_get_size  (MirageFragment *self);

Retrieves main data file sector size.

self :

a MirageFragment

Returns :

main data file sector size

mirage_fragment_main_data_set_format ()

void                mirage_fragment_main_data_set_format
                                                        (MirageFragment *self,
                                                         gint format);

Sets main data file format. format must be one of MirageMainDataFormat.

self :

a MirageFragment

format :

main data file format. [in]

mirage_fragment_main_data_set_offset ()

void                mirage_fragment_main_data_set_offset
                                                        (MirageFragment *self,
                                                         guint64 offset);

Sets main data file offset.

self :

a MirageFragment

offset :

main data file offset. [in]

mirage_fragment_main_data_set_size ()

void                mirage_fragment_main_data_set_size  (MirageFragment *self,
                                                         gint size);

Sets main data file sector size.

self :

a MirageFragment

size :

main data file sector size. [in]

mirage_fragment_main_data_set_stream ()

void                mirage_fragment_main_data_set_stream
                                                        (MirageFragment *self,
                                                         MirageStream *stream);

Sets main channel data stream.

self :

a MirageFragment

stream :

a MirageStream on main channel data file. [in][transfer full]

mirage_fragment_read_main_data ()

gboolean            mirage_fragment_read_main_data      (MirageFragment *self,
                                                         gint address,
                                                         guint8 **buffer,
                                                         gint *length,
                                                         GError **error);

Reads main channel data for sector at fragment-relative address (given in sectors). The buffer for reading data into is allocated by function and should be freed using g_free() when no longer needed. The pointer to buffer is stored into buffer and the length of read data is stored into length.

self :

a MirageFragment

address :

address. [in]

buffer :

location to store pointer to buffer with read data, or NULL. [out][allow-none][array length=length]

length :

location to store read data length. [out]

error :

location to store error, or NULL. [out][allow-none]

Returns :

TRUE on success, FALSE on failure

mirage_fragment_write_main_data ()

gboolean            mirage_fragment_write_main_data     (MirageFragment *self,
                                                         gint address,
                                                         const guint8 *buffer,
                                                         gint length,
                                                         GError **error);

Writes main channel data for sector at fragment-relative address (given in sectors).

self :

a MirageFragment

address :

address. [in]

buffer :

buffer with data to write, or NULL. [in][allow-none][array length=length]

length :

length of data to write. [in]

error :

location to store error, or NULL. [out][allow-none]

Returns :

TRUE on success, FALSE on failure

mirage_fragment_read_subchannel_data ()

gboolean            mirage_fragment_read_subchannel_data
                                                        (MirageFragment *self,
                                                         gint address,
                                                         guint8 **buffer,
                                                         gint *length,
                                                         GError **error);

Writes subchannel data for sector at fragment-relative address (given in sectors).

self :

a MirageFragment

address :

address. [in]

buffer :

buffer with data to write, or NULL. [in][allow-none][array length=length]

length :

location to store read data length. [out]

error :

location to store error, or NULL. [out][allow-none]

Returns :

TRUE on success, FALSE on failure

mirage_fragment_write_subchannel_data ()

gboolean            mirage_fragment_write_subchannel_data
                                                        (MirageFragment *self,
                                                         gint address,
                                                         const guint8 *buffer,
                                                         gint length,
                                                         GError **error);

Reads subchannel data for sector at fragment-relative address (given in sectors). The buffer for reading data into is allocated by function and should be freed using g_free() when no longer needed. The pointer to buffer is stored into buffer and the length of read data is stored into length.

self :

a MirageFragment

address :

address. [in]

buffer :

buffer with read data, or NULL. [in][allow-none][array length=length]

length :

length of data to write. [in]

error :

location to store error, or NULL. [out][allow-none]

Returns :

TRUE on success, FALSE on failure

mirage_fragment_set_address ()

void                mirage_fragment_set_address         (MirageFragment *self,
                                                         gint address);

Sets fragment's start address. The address is given in sectors.

Note

Intended for internal use only.

Note

Causes top-down change.

self :

a MirageFragment

address :

start address. [in]

mirage_fragment_set_length ()

void                mirage_fragment_set_length          (MirageFragment *self,
                                                         gint length);

Sets fragment's length. The length is given in sectors.

Note

Intended for internal use only.

Note

Causes bottom-up change.

self :

a MirageFragment

length :

length. [in]

mirage_fragment_subchannel_data_get_filename ()

const gchar *       mirage_fragment_subchannel_data_get_filename
                                                        (MirageFragment *self);

Retrieves filename of subchannel data input stream.

self :

a MirageFragment

Returns :

pointer to subchannel data file name string. The string belongs to object and should not be modified. [transfer none]

mirage_fragment_subchannel_data_get_format ()

gint                mirage_fragment_subchannel_data_get_format
                                                        (MirageFragment *self);

Retrieves subchannel data file format.

self :

a MirageFragment

Returns :

subchannel data file format

mirage_fragment_subchannel_data_get_offset ()

guint64             mirage_fragment_subchannel_data_get_offset
                                                        (MirageFragment *self);

Retrieves subchannel data file offset.

self :

a MirageFragment

Returns :

subchannel data file offset

mirage_fragment_subchannel_data_get_size ()

gint                mirage_fragment_subchannel_data_get_size
                                                        (MirageFragment *self);

Retrieves subchannel data file sector size.

self :

a MirageFragment

Returns :

subchannel data file sector size

mirage_fragment_subchannel_data_set_format ()

void                mirage_fragment_subchannel_data_set_format
                                                        (MirageFragment *self,
                                                         gint format);

Sets subchannel data file format. format must be a combination of MirageSubchannelDataFormat.

self :

a MirageFragment

format :

subchannel data file format. [in]

mirage_fragment_subchannel_data_set_offset ()

void                mirage_fragment_subchannel_data_set_offset
                                                        (MirageFragment *self,
                                                         guint64 offset);

Sets subchannel data file offset.

self :

a MirageFragment

offset :

subchannel data file offset. [in]

mirage_fragment_subchannel_data_set_size ()

void                mirage_fragment_subchannel_data_set_size
                                                        (MirageFragment *self,
                                                         gint size);

Sets subchannel data file sector size.

self :

a MirageFragment

size :

subchannel data file sector size. [in]

mirage_fragment_subchannel_data_set_stream ()

void                mirage_fragment_subchannel_data_set_stream
                                                        (MirageFragment *self,
                                                         MirageStream *stream);

Sets subchannel data stream.

self :

a MirageFragment

stream :

a MirageStream on subchannel data file. [in][transfer full]

mirage_fragment_use_the_rest_of_file ()

gboolean            mirage_fragment_use_the_rest_of_file
                                                        (MirageFragment *self,
                                                         GError **error);

Uses the rest of data file. It automatically calculates and sets fragment's length.

self :

a MirageFragment

error :

location to store error, or NULL. [out][allow-none]

Returns :

TRUE on success, FALSE on failure

Signal Details

The "layout-changed" signal

void                user_function                      (MirageFragment *fragment,
                                                        gpointer        user_data)      : Run Last

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

fragment :

a MirageFragment

user_data :

user data set when the signal handler was connected.

See Also

MirageStream, MirageTrack