MIRAGE_Mirage object

MIRAGE_Mirage object — Core object of the libMirage library

Synopsis


#include <mirage.h>


gboolean            (*MIRAGE_CallbackFunction)          (gpointer data,
                                                         gpointer user_data);
                    MIRAGE_Mirage;
gboolean            mirage_mirage_get_version           (MIRAGE_Mirage *self,
                                                         gchar **version,
                                                         GError **error);
gboolean            mirage_mirage_create_disc           (MIRAGE_Mirage *self,
                                                         gchar **filenames,
                                                         GObject **ret_disc,
                                                         GObject *debug_context,
                                                         GError **error);
gboolean            mirage_mirage_create_fragment       (MIRAGE_Mirage *self,
                                                         GType fragment_interface,
                                                         gchar *filename,
                                                         GObject **ret_fragment,
                                                         GError **error);
gboolean            mirage_mirage_for_each_parser       (MIRAGE_Mirage *self,
                                                         MIRAGE_CallbackFunction func,
                                                         gpointer user_data,
                                                         GError **error);
gboolean            mirage_mirage_for_each_fragment     (MIRAGE_Mirage *self,
                                                         MIRAGE_CallbackFunction func,
                                                         gpointer user_data,
                                                         GError **error);
gboolean            mirage_mirage_get_supported_debug_masks
                                                        (MIRAGE_Mirage *self,
                                                         GPtrArray **masks,
                                                         GError **error);


Object Hierarchy


  GObject
   +----MIRAGE_Object
         +----MIRAGE_Mirage

Description

MIRAGE_Mirage is core object of libMirage library. All applications using libMirage should create this object and use it to create objects that represent data stored in image files.

libMirage uses a plugin system for image parsers and data fragments implementations. MIRAGE_Mirage keeps a list of these plugins and uses it when image parser or data fragment needs to be created by mirage_mirage_create_disc() or mirage_mirage_create_fragment(). It also supports listing of supported parsers and data fragments via mirage_mirage_for_each_parser() and mirage_mirage_for_each_fragment().

Library version string can be obtained by calling mirage_mirage_get_version() and the list of supported debug masks can be obtained by calling mirage_mirage_get_supported_debug_masks().

Details

MIRAGE_CallbackFunction ()

gboolean            (*MIRAGE_CallbackFunction)          (gpointer data,
                                                         gpointer user_data);

Callback function type used in libMirage's iteration functions. data is data that the iteration function iterates for. Depending on the iteration function, it may need to be freed or released. user_data is user data passed to iteration function.

data :

data

user_data :

user data passed to iteration function

Returns :

TRUE on success, otherwise FALSE

MIRAGE_Mirage

typedef struct _MIRAGE_Mirage MIRAGE_Mirage;

Contains private data only, and should be accessed using the functions below.


mirage_mirage_get_version ()

gboolean            mirage_mirage_get_version           (MIRAGE_Mirage *self,
                                                         gchar **version,
                                                         GError **error);

Retrieves libMirage version string.

A copy of version string is stored into version; it should be freed with g_free() when no longer needed.

self :

a MIRAGE_Mirage

version :

location to return version string

error :

location to store error, or NULL

Returns :

TRUE on success, FALSE on failure

mirage_mirage_create_disc ()

gboolean            mirage_mirage_create_disc           (MIRAGE_Mirage *self,
                                                         gchar **filenames,
                                                         GObject **ret_disc,
                                                         GObject *debug_context,
                                                         GError **error);

Creates a MIRAGE_Disc object representing image stored in filenames. filenames is a NULL-terminated list of filenames containing image data. The function tries to find a parser that can handle give filename(s), creates disc implementation, attaches debug_context to it (if provided) and attempts to load the data into disc object.

If multiple filenames are provided and parser supports only single-file images, the function fails.

A reference to disc object is stored in ret_disc; it should be released with g_object_unref() when no longer needed.

self :

a MIRAGE_Mirage

filenames :

filename(s)

ret_disc :

location to store disc object

debug_context :

debug context to be attached to disc object, or NULL

error :

location to store error, or NULL

Returns :

TRUE on success, FALSE on failure

mirage_mirage_create_fragment ()

gboolean            mirage_mirage_create_fragment       (MIRAGE_Mirage *self,
                                                         GType fragment_interface,
                                                         gchar *filename,
                                                         GObject **ret_fragment,
                                                         GError **error);

Creates a MIRAGE_Fragment implementation that implements interface specified by fragment_interface and can handle data file with file name filename.

A reference to fragment object is stored in ret_fragment; it should be released with g_object_unref() when no longer needed.

self :

a MIRAGE_Mirage

fragment_interface :

interface that fragment should implement

filename :

filename of data file that fragment should be able to handle

ret_fragment :

location to store fragment

error :

location to store error, or NULL

Returns :

TRUE on success, FALSE on failure

mirage_mirage_for_each_parser ()

gboolean            mirage_mirage_for_each_parser       (MIRAGE_Mirage *self,
                                                         MIRAGE_CallbackFunction func,
                                                         gpointer user_data,
                                                         GError **error);

Iterates over list of supported parsers, calling func for each parser.

If func returns FALSE, the function immediately returns FALSE and error is set to MIRAGE_E_ITERCANCELLED.

self :

a MIRAGE_Mirage

func :

callback function

user_data :

data to be passed to callback function

error :

location to store error, or NULL

Returns :

TRUE on success, FALSE on failure

mirage_mirage_for_each_fragment ()

gboolean            mirage_mirage_for_each_fragment     (MIRAGE_Mirage *self,
                                                         MIRAGE_CallbackFunction func,
                                                         gpointer user_data,
                                                         GError **error);

Iterates over list of supported fragments, calling func for each fragment.

If func returns FALSE, the function immediately returns FALSE and error is set to MIRAGE_E_ITERCANCELLED.

self :

a MIRAGE_Mirage

func :

callback function

user_data :

data to be passed to callback function

error :

location to store error, or NULL

Returns :

TRUE on success, FALSE on failure

mirage_mirage_get_supported_debug_masks ()

gboolean            mirage_mirage_get_supported_debug_masks
                                                        (MIRAGE_Mirage *self,
                                                         GPtrArray **masks,
                                                         GError **error);

Retrieves array of supported debug masks and stores it in masks. The array is a GPtrArray, containing multiple GValueArray containers, each containing a string and an integer representing debug mask's name and value.

Both GPtrArray array and GValueArray containers should be freed with g_ptr_array_free() and g_value_array_free() when no longer needed.

self :

a MIRAGE_Mirage

masks :

location to store masks array

error :

location to store error, or NULL

Returns :

TRUE on success, FALSE on failure