MirageWriter

MirageWriter — Base object for image writer implementations.

Synopsis

#include <mirage-writer.h>

enum                MirageFragmentRole;
struct              MirageWriterInfo;
struct              MirageWriterParameter;
struct              MirageWriter;
struct              MirageWriterClass;
void                mirage_writer_add_parameter_boolean (MirageWriter *self,
                                                         const gchar *id,
                                                         const gchar *name,
                                                         const gchar *description,
                                                         gboolean default_value);
void                mirage_writer_add_parameter_enum    (MirageWriter *self,
                                                         const gchar *id,
                                                         const gchar *name,
                                                         const gchar *description,
                                                         const gchar *default_value,
                                                         ...);
void                mirage_writer_add_parameter_int     (MirageWriter *self,
                                                         const gchar *id,
                                                         const gchar *name,
                                                         const gchar *description,
                                                         gint default_value);
void                mirage_writer_add_parameter_string  (MirageWriter *self,
                                                         const gchar *id,
                                                         const gchar *name,
                                                         const gchar *description,
                                                         const gchar *default_value);
gboolean            mirage_writer_convert_image         (MirageWriter *self,
                                                         const gchar *filename,
                                                         MirageDisc *original_disc,
                                                         GHashTable *parameters,
                                                         GCancellable *cancellable,
                                                         GError **error);
MirageFragment *    mirage_writer_create_fragment       (MirageWriter *self,
                                                         MirageTrack *track,
                                                         MirageFragmentRole role,
                                                         GError **error);
gboolean            mirage_writer_finalize_image        (MirageWriter *self,
                                                         MirageDisc *disc,
                                                         GError **error);
void                mirage_writer_generate_info         (MirageWriter *self,
                                                         const gchar *id,
                                                         const gchar *name);
guint               mirage_writer_get_conversion_progress_step
                                                        (MirageWriter *self);
const MirageWriterInfo * mirage_writer_get_info         (MirageWriter *self);
gboolean            mirage_writer_get_parameter_boolean (MirageWriter *self,
                                                         const gchar *id);
const gchar *       mirage_writer_get_parameter_enum    (MirageWriter *self,
                                                         const gchar *id);
gint                mirage_writer_get_parameter_int     (MirageWriter *self,
                                                         const gchar *id);
const gchar *       mirage_writer_get_parameter_string  (MirageWriter *self,
                                                         const gchar *id);
void                mirage_writer_info_copy             (const MirageWriterInfo *info,
                                                         MirageWriterInfo *dest);
void                mirage_writer_info_free             (MirageWriterInfo *info);
GList *             mirage_writer_lookup_parameter_ids  (MirageWriter *self);
const MirageWriterParameter * mirage_writer_lookup_parameter_info
                                                        (MirageWriter *self,
                                                         const gchar *id);
gboolean            mirage_writer_open_image            (MirageWriter *self,
                                                         MirageDisc *disc,
                                                         GHashTable *parameters,
                                                         GError **error);
void                mirage_writer_set_conversion_progress_step
                                                        (MirageWriter *self,
                                                         guint step);

Object Hierarchy

  GObject
   +----MirageObject
         +----MirageWriter

Implemented Interfaces

MirageWriter implements MirageContextual.

Signals

  "conversion-progress"                            : Run Last

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.

Details

enum MirageFragmentRole

typedef enum {
    MIRAGE_FRAGMENT_PREGAP,
    MIRAGE_FRAGMENT_DATA,
} MirageFragmentRole;

Fragment roles.

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

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.

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.

MirageObjectClass parent_class;

the parent class

open_image ()

initializes writer on specified image

create_fragment ()

creates a fragment of specified role for the given track

finalize_image ()

finalizes image

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.

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.

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.

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.

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.

self :

a MirageWriter

filename :

filename of output image. [in]

original_disc :

disc layout obtained from original image. [in]

parameters :

writer parameters. [in]

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

self :

a MirageWriter

disc :

disc object for which the image will be created. [in]

parameters :

writer parameters. [in]

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.

self :

a MirageWriter

step :

new conversion progress step value

Signal Details

The "conversion-progress" signal

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

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

object :

a MirageWriter

progress :

percentual image conversion progress

user_data :

user data set when the signal handler was connected.

See Also

MirageDisc, MirageParser