MirageWriter

MirageWriter — Base object for image writer implementations.

Functions

Signals

void conversion-progress Run Last

Types and Values

Object Hierarchy

    GObject
    ╰── MirageObject
        ╰── MirageWriter

Implemented Interfaces

MirageWriter implements MirageContextual.

Includes

#include <mirage-writer.h>

Description

MirageWriter object is a base object for image writer implementations.

In contrast to image loading process, which is done by a single function call, the image writing process is designed to be interactive: first, the user creates a MirageDisc object. On created disc, the medium type should be set, and the filename should be changed to the desired output filename, before passing the disc object to mirage_writer_open_image(), which initializes the writer. Afterwards, the disc layout should be populated with session(s) and track(s), and tracks with fragments. Fragments for tracks are requested from writer using mirage_writer_create_fragment() function. After the fragment is set up for the track, sectors can be written to it using mirage_track_put_sector(), or mirage_disc_put_sector(). To finish image writing, call mirage_writer_finalize_image(), which might write the image descriptor file and rename image data files, if necessary.

The above-outlined process makes image writing flexible enough to accomodate both scenarios where all image data to be written is given in advance (e.g., from another image) and cases where image data is arriving incrementally, sector-by-sector.

A MirageWriter provides mirage_writer_convert_image() function, which allows writer to be used for converting an existing image by copying all relevant data from it. In addition, conversion progress reporting can be controlled using mirage_writer_set_conversion_progress_step() and followed using “conversion-progress”.

To control image writer parameters, MirageWriter implements parameter sheet with API for defining parameters and validation/retrieval of user-supplied values.

Functions

mirage_writer_add_parameter_boolean ()

void
mirage_writer_add_parameter_boolean (MirageWriter *self,
                                     const gchar *id,
                                     const gchar *name,
                                     const gchar *description,
                                     gboolean default_value);

Adds a boolean parameter to writer's parameter sheet.

Parameters

self

a MirageWriter

 

id

parameter ID.

[in]

name

parameter name.

[in]

description

parameter description.

[in]

default_value

default value.

[in]

mirage_writer_add_parameter_enum ()

void
mirage_writer_add_parameter_enum (MirageWriter *self,
                                  const gchar *id,
                                  const gchar *name,
                                  const gchar *description,
                                  const gchar *default_value,
                                  ...);

Adds an enum parameter to writer's parameter sheet. The enum parameters are treated as string parameters, except they have a pre-defined set of valid values.

Parameters

self

a MirageWriter

 

id

parameter ID.

[in]

name

parameter name.

[in]

description

parameter description.

[in]

default_value

default value.

[in]

...

NULL-terminated list of valid string values.

[in]

mirage_writer_add_parameter_int ()

void
mirage_writer_add_parameter_int (MirageWriter *self,
                                 const gchar *id,
                                 const gchar *name,
                                 const gchar *description,
                                 gint default_value);

Adds an integer parameter to writer's parameter sheet.

Parameters

self

a MirageWriter

 

id

parameter ID.

[in]

name

parameter name.

[in]

description

parameter description.

[in]

default_value

default value.

[in]

mirage_writer_add_parameter_string ()

void
mirage_writer_add_parameter_string (MirageWriter *self,
                                    const gchar *id,
                                    const gchar *name,
                                    const gchar *description,
                                    const gchar *default_value);

Adds a string parameter to writer's parameter sheet.

Parameters

self

a MirageWriter

 

id

parameter ID.

[in]

name

parameter name.

[in]

description

parameter description.

[in]

default_value

default value.

[in]

mirage_writer_convert_image ()

gboolean
mirage_writer_convert_image (MirageWriter *self,
                             const gchar *filename,
                             MirageDisc *original_disc,
                             GHashTable *parameters,
                             GCancellable *cancellable,
                             GError **error);

Convenience function that converts an already-opened image stored in original_disc and writes it to filename . If conversion progress reporting is enabled via mirage_writer_set_conversion_progress_step(), the “conversion-progress” signal is emitted at specified time intervals during conversion.

Parameters

self

a MirageWriter

 

filename

filename of output image.

[in]

original_disc

disc layout obtained from original image.

[in]

parameters

writer parameters.

[in][element-type utf8 GLib.Variant]

cancellable

optional GCancellable object, NULL to ignore.

[in][allow-none]

error

location to store error, or NULL.

[out][allow-none]

Returns

TRUE on success, FALSE on failure


mirage_writer_create_fragment ()

MirageFragment *
mirage_writer_create_fragment (MirageWriter *self,
                               MirageTrack *track,
                               MirageFragmentRole role,
                               GError **error);

Creates a fragment with specified role for given track . The latter needs to already be part of disc's layout.

The role helps writer implementation determine what kind of fragment to create; for example, some writer implementations create dummy fragments for pregaps.

Parameters

self

a MirageWriter

 

track

track for which the fragment is to be created.

[in]

role

fragment role.

[in]

error

location to store error, or NULL.

[out][allow-none]

Returns

pointer to created fragment object on success, NULL on failure.

[transfer full]


mirage_writer_finalize_image ()

gboolean
mirage_writer_finalize_image (MirageWriter *self,
                              MirageDisc *disc,
                              GError **error);

Finalizes the image, possibly creating the image descriptor file if necessary.

Parameters

self

a MirageWriter

 

disc

disc object for which the image is being written.

[in]

error

location to store error, or NULL.

[out][allow-none]

Returns

TRUE on success, FALSE on failure


mirage_writer_generate_info ()

void
mirage_writer_generate_info (MirageWriter *self,
                             const gchar *id,
                             const gchar *name);

Generates writer information from the input fields. It is intended as a function for creating writer information in writer implementations.

Parameters

self

a MirageWriter

 

id

writer ID.

[in]

name

writer name.

[in]

mirage_writer_get_conversion_progress_step ()

guint
mirage_writer_get_conversion_progress_step
                               (MirageWriter *self);

Retrieves conversion progress step setting.

Parameters

self

a MirageWriter

 

Returns

the value of conversion progress step.


mirage_writer_get_info ()

const MirageWriterInfo *
mirage_writer_get_info (MirageWriter *self);

Retrieves writer information.

Parameters

self

a MirageWriter

 

Returns

a pointer to writer information structure. The structure belongs to object and should not be modified.

[transfer none]


mirage_writer_get_parameter_boolean ()

gboolean
mirage_writer_get_parameter_boolean (MirageWriter *self,
                                     const gchar *id);

Looks up the boolean parameter with specified id from user-supplied writer parameters and returns its value. If user did not supply the parameter, its default value is returned instead.

Parameters

self

a MirageWriter

 

id

parameter ID string

 

Returns

user-supplied parameter value.


mirage_writer_get_parameter_enum ()

const gchar *
mirage_writer_get_parameter_enum (MirageWriter *self,
                                  const gchar *id);

Looks up the enum parameter with specified id from user-supplied writer parameters and returns its value. If user did not supply the parameter, its default value is returned instead.

Parameters

self

a MirageWriter

 

id

parameter ID string

 

Returns

user-supplied parameter value.


mirage_writer_get_parameter_int ()

gint
mirage_writer_get_parameter_int (MirageWriter *self,
                                 const gchar *id);

Looks up the string parameter with specified id from user-supplied writer parameters and returns its value. If user did not supply the parameter, its default value is returned instead.

Parameters

self

a MirageWriter

 

id

parameter ID string

 

Returns

user-supplied parameter value.


mirage_writer_get_parameter_string ()

const gchar *
mirage_writer_get_parameter_string (MirageWriter *self,
                                    const gchar *id);

Looks up the string parameter with specified id from user-supplied writer parameters and returns its value. If user did not supply the parameter, its default value is returned instead.

Parameters

self

a MirageWriter

 

id

parameter ID string

 

Returns

user-supplied parameter value.


mirage_writer_info_copy ()

void
mirage_writer_info_copy (const MirageWriterInfo *info,
                         MirageWriterInfo *dest);

Copies parser information from info to dest .

Parameters

info

a MirageWriterInfo to copy data from.

[in]

dest

a MirageWriterInfo to copy data to.

[in]

mirage_writer_info_free ()

void
mirage_writer_info_free (MirageWriterInfo *info);

Frees the allocated fields in info (but not the structure itself!).

Parameters

info

a MirageWriterInfo to free.

[in]

mirage_writer_lookup_parameter_ids ()

GList *
mirage_writer_lookup_parameter_ids (MirageWriter *self);

Retrieves the list of parameter ID strings from writer's parameter sheet. The IDs are ordered in the same way as they were inserted into the parameter sheet.

Parameters

self

a MirageWriter

 

Returns

the list of parameter IDs. The list and its elements belong to the writer and should not be modified.

[transfer none][element-type gchar*]


mirage_writer_lookup_parameter_info ()

const MirageWriterParameter *
mirage_writer_lookup_parameter_info (MirageWriter *self,
                                     const gchar *id);

Looks up the parameter with specified id in writer's parameter sheet and retrieves the parameter's information structure.

Parameters

self

a MirageWriter

 

id

parameter ID string

 

Returns

the pointer to parameter's information structure on success, NULL on failure. The information structure belong to the writer and should not be modified.


mirage_writer_open_image ()

gboolean
mirage_writer_open_image (MirageWriter *self,
                          MirageDisc *disc,
                          GHashTable *parameters,
                          GError **error);

Initializes the image writer to start the writing process for disc . The latter should have set the image filename(s) and medium type, but does not have to have disc layout (sessions, tracks) built yet.

Parameters

self

a MirageWriter

 

disc

disc object for which the image will be created.

[in]

parameters

writer parameters.

[in][element-type utf8 GLib.Variant]

error

location to store error, or NULL.

[out][allow-none]

Returns

TRUE on success, FALSE on failure


mirage_writer_set_conversion_progress_step ()

void
mirage_writer_set_conversion_progress_step
                               (MirageWriter *self,
                                guint step);

Sets conversion progress step. Setting step to 0 disables conversion progress reporting.

Parameters

self

a MirageWriter

 

step

new conversion progress step value

 

Types and Values

enum MirageFragmentRole

Fragment roles.

Members

MIRAGE_FRAGMENT_PREGAP

pregap fragment

 

MIRAGE_FRAGMENT_DATA

data fragment

 

struct MirageWriterInfo

struct MirageWriterInfo {
    gchar *id;
    gchar *name;
};

A structure containing writer information. It can be obtained with call to mirage_writer_get_info().

Members

gchar *id;

writer ID

 

gchar *name;

writer name

 

struct MirageWriterParameter

struct MirageWriterParameter {
    gchar *name;
    gchar *description;

    GVariant *default_value;

    GVariant *enum_values;
};

A structure encapsulating information about image writer parameters, using in writer's parameter sheet.

Members

gchar *name;

parameter name

 

gchar *description;

description of parameter

 

GVariant *default_value;

default value for parameter. Also determines parameter type.

 

GVariant *enum_values;

if parameter is an enum, this field contains all possible values. The variant has a signature "as".

 

struct MirageWriter

struct MirageWriter;

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


struct MirageWriterClass

struct MirageWriterClass {
    MirageObjectClass parent_class;

    /* Class members */
    gboolean (*open_image) (MirageWriter *self, MirageDisc *disc, GError **error);
    MirageFragment *(*create_fragment) (MirageWriter *self, MirageTrack *track, MirageFragmentRole role, GError **error);
    gboolean (*finalize_image) (MirageWriter *self, MirageDisc *disc, GError **error);
};

The class structure for the MirageWriter type.

Members

open_image ()

initializes writer on specified image

 

create_fragment ()

creates a fragment of specified role for the given track

 

finalize_image ()

finalizes image

 

Signal Details

The “conversion-progress” signal

void
user_function (MirageWriter *object,
               guint         progress,
               gpointer      user_data)

Emitted when the image conversion progress reaches a new progress mark.

Parameters

object

a MirageWriter

 

progress

percentual image conversion progress

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

See Also

MirageDisc, MirageParser