![]() |
![]() |
![]() |
libMirage Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Implemented Interfaces | Signals |
#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
);
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.
typedef enum { MIRAGE_FRAGMENT_PREGAP, MIRAGE_FRAGMENT_DATA, } MirageFragmentRole;
Fragment roles.
struct MirageWriterInfo { gchar *id; gchar *name; };
A structure containing writer information. It can be obtained with call to
mirage_writer_get_info()
.
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.
struct MirageWriter;
All the fields in the MirageWriter structure are private to the MirageWriter implementation and should never be accessed directly.
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 |
the parent class |
initializes writer on specified image | |
creates a fragment of specified role for the given track | |
finalizes image |
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.
|
a MirageWriter |
|
parameter ID. [in] |
|
parameter name. [in] |
|
parameter description. [in] |
|
default value. [in] |
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.
|
a MirageWriter |
|
parameter ID. [in] |
|
parameter name. [in] |
|
parameter description. [in] |
|
default value. [in] |
|
NULL -terminated list of valid string values. [in]
|
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.
|
a MirageWriter |
|
parameter ID. [in] |
|
parameter name. [in] |
|
parameter description. [in] |
|
default value. [in] |
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.
|
a MirageWriter |
|
parameter ID. [in] |
|
parameter name. [in] |
|
parameter description. [in] |
|
default value. [in] |
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.
|
a MirageWriter |
|
filename of output image. [in] |
|
disc layout obtained from original image. [in] |
|
writer parameters. [in] |
|
optional GCancellable object, NULL to ignore. [in][allow-none]
|
|
location to store error, or NULL . [out][allow-none]
|
Returns : |
TRUE on success, FALSE on failure |
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.
|
a MirageWriter |
|
track for which the fragment is to be created. [in] |
|
fragment role. [in] |
|
location to store error, or NULL . [out][allow-none]
|
Returns : |
pointer to created fragment object on success, NULL on failure. [transfer full]
|
gboolean mirage_writer_finalize_image (MirageWriter *self
,MirageDisc *disc
,GError **error
);
Finalizes the image, possibly creating the image descriptor file if necessary.
|
a MirageWriter |
|
disc object for which the image is being written. [in] |
|
location to store error, or NULL . [out][allow-none]
|
Returns : |
TRUE on success, FALSE on failure |
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.
|
a MirageWriter |
|
writer ID. [in] |
|
writer name. [in] |
guint mirage_writer_get_conversion_progress_step
(MirageWriter *self
);
Retrieves conversion progress step setting.
|
a MirageWriter |
Returns : |
the value of conversion progress step. |
const MirageWriterInfo * mirage_writer_get_info (MirageWriter *self
);
Retrieves writer information.
|
a MirageWriter |
Returns : |
a pointer to writer information structure. The structure belongs to object and should not be modified. [transfer none] |
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.
|
a MirageWriter |
|
parameter ID string |
Returns : |
user-supplied parameter value. |
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.
|
a MirageWriter |
|
parameter ID string |
Returns : |
user-supplied parameter value. |
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.
|
a MirageWriter |
|
parameter ID string |
Returns : |
user-supplied parameter value. |
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.
|
a MirageWriter |
|
parameter ID string |
Returns : |
user-supplied parameter value. |
void mirage_writer_info_copy (const MirageWriterInfo *info
,MirageWriterInfo *dest
);
Copies parser information from info
to dest
.
|
a MirageWriterInfo to copy data from. [in] |
|
a MirageWriterInfo to copy data to. [in] |
void mirage_writer_info_free (MirageWriterInfo *info
);
Frees the allocated fields in info
(but not the structure itself!).
|
a MirageWriterInfo to free. [in] |
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.
|
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*] |
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.
|
a MirageWriter |
|
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. |
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.
|
a MirageWriter |
|
disc object for which the image will be created. [in] |
|
writer parameters. [in] |
|
location to store error, or NULL . [out][allow-none]
|
Returns : |
TRUE on success, FALSE on failure |
void mirage_writer_set_conversion_progress_step (MirageWriter *self
,guint step
);
Sets conversion progress step. Setting step
to 0 disables conversion
progress reporting.
|
a MirageWriter |
|
new conversion progress step value |
"conversion-progress"
signalvoid user_function (MirageWriter *object,
guint progress,
gpointer user_data) : Run Last
Emitted when the image conversion progress reaches a new progress mark.
|
a MirageWriter |
|
percentual image conversion progress |
|
user data set when the signal handler was connected. |