MirageWriter: libMirage Reference Manual

## MirageWriter MirageWriter — Base object for image writer implementations. |

## Functions

void | mirage_writer_add_parameter_boolean ()
void | mirage_writer_add_parameter_enum ()
void | mirage_writer_add_parameter_int ()
void | mirage_writer_add_parameter_string ()
gboolean | mirage_writer_convert_image ()
MirageFragment * | mirage_writer_create_fragment ()
gboolean | mirage_writer_finalize_image ()
void | mirage_writer_generate_info ()
guint | mirage_writer_get_conversion_progress_step ()
const MirageWriterInfo * | mirage_writer_get_info ()
gboolean | mirage_writer_get_parameter_boolean ()
const gchar * | mirage_writer_get_parameter_enum ()
gint | mirage_writer_get_parameter_int ()
const gchar * | mirage_writer_get_parameter_string ()
void | mirage_writer_info_copy ()
void | mirage_writer_info_free ()
GList * | mirage_writer_lookup_parameter_ids ()
const MirageWriterParameter * | mirage_writer_lookup_parameter_info ()
gboolean | mirage_writer_open_image ()
void | mirage_writer_set_conversion_progress_step ()

## Signals

void | conversion-progress | Run Last

## Types and Values

enum | MirageFragmentRole
struct | MirageWriterInfo
struct | MirageWriterParameter
struct | MirageWriter
struct | MirageWriterClass

## 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_impl) (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_impl` () | 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