Main libMirage functions

Main libMirage functions — Main libMirage functions

Synopsis

#include <mirage.h>

gboolean            (*MIRAGE_CallbackFunction)          (const gpointer data,
                                                         gpointer user_data);
gchar *             (*MIRAGE_PasswordFunction)          (gpointer user_data);
                    MIRAGE_DebugMask;
gboolean            libmirage_init                      (GError **error);
gboolean            libmirage_shutdown                  (GError **error);
gboolean            libmirage_set_password_function     (MIRAGE_PasswordFunction func,
                                                         gpointer user_data,
                                                         GError **error);
gchar *             libmirage_obtain_password           (GError **error);
GObject *           libmirage_create_disc               (gchar **filenames,
                                                         GObject *debug_context,
                                                         GHashTable *params,
                                                         GError **error);
GObject *           libmirage_create_fragment           (GType fragment_interface,
                                                         const gchar *filename,
                                                         GError **error);
gboolean            libmirage_for_each_parser           (MIRAGE_CallbackFunction func,
                                                         gpointer user_data,
                                                         GError **error);
gboolean            libmirage_for_each_fragment         (MIRAGE_CallbackFunction func,
                                                         gpointer user_data,
                                                         GError **error);
gboolean            libmirage_get_supported_debug_masks (const MIRAGE_DebugMask **masks,
                                                         gint *num_masks,
                                                         GError **error);

Description

These functions represent the core of the libMirage API.

Before libMirage is used, it must be initialized using libmirage_init(). This initializes the plugin system and loads the image parser and data fragment plugins. When library is no longer needed, it can be shut down using libmirage_shutdown(), which frees the plugin data.

If libMirage is not initializes, the calls to all its functions will fail. You could still create basic objects, such as MIRAGE_Disc or MIRAGE_Session, using GLib's g_object_new(), however some of the objects' function implementations rely on initialized libMirage library and therefore their behavior would be incorrect.

The password callback function can be set using libmirage libmirage_set_password_function(), which stores a MIRAGE_PasswordFunction callback function and user data for the callback to be called with. The password callback function is used by libmirage_obtain_password(), which is usually called by image parser implementation which is trying to load an encrypted image and needs password to do so.

Image file(s) can be loaded using libmirage_create_disc(), which (if loading succeeded) returns a MIRAGE_Disc object representing the disc stored in the image file(s). Function libmirage_create_fragment() creates a fragment implementation - this function is usually used by image parsers.

Supported image parsers and fragments can be enumerated using libmirage_for_each_parser() and libmirage_for_each_fragment(), respectively. The list of supported debug masks can be obtained using libmirage_get_supported_debug_masks().

Details

MIRAGE_CallbackFunction ()

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

Callback function type used in libMirage's iteration functions. A pointer to data buffer is stored in data; the buffer usually belongs to the object and therefore should not be modified. 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_PasswordFunction ()

gchar *             (*MIRAGE_PasswordFunction)          (gpointer user_data);

Password function type used in libMirage's to obtain password for encrypted images. A password function needs to be set to libMirage via libmirage_set_password_function(), along with user_data that the password function should be called with.

`user_data` :	user data passed to password function
Returns :	password string on success, otherwise `NULL`. Password string should be a copy, allocated via function such as `g_strdup()`, and will be freed after it is used.

MIRAGE_DebugMask

typedef struct {
    gchar *name;
    gint value;
} MIRAGE_DebugMask;

Structure containing debug mask information.

gchar *`name`;	name
gint `value`;	value

libmirage_init ()

gboolean            libmirage_init                      (GError **error);

Initializes libMirage library. It should be called before any other of libMirage functions.

`error` :	location to store error, or `NULL`
Returns :	`TRUE` on success, `FALSE` on failure

libmirage_shutdown ()

gboolean            libmirage_shutdown                  (GError **error);

Shuts down libMirage library. It should be called when libMirage is no longer needed.

`error` :	location to store error, or `NULL`
Returns :	`TRUE` on success, `FALSE` on failure

libmirage_set_password_function ()

gboolean            libmirage_set_password_function     (MIRAGE_PasswordFunction func,
                                                         gpointer user_data,
                                                         GError **error);

Sets the password function to libMirage. The function is used by parsers that support encrypted images to obtain password for unlocking such images.

Both func and user_data can be NULL; in that case the appropriate setting will be reset.

`func` :	a password function pointer
`user_data` :	pointer to user data to be passed to the password function
`error` :	location to store error, or `NULL`
Returns :	`TRUE` on success, `FALSE` on failure

libmirage_obtain_password ()

gchar *             libmirage_obtain_password           (GError **error);

Obtains password string, using the MIRAGE_PasswordFunction callback that was provided via libmirage_set_password_function().

`error` :	location to store error, or `NULL`
Returns :	password string on success, `NULL` on failure. The string should be freed with `g_free()` when no longer needed.

libmirage_create_disc ()

GObject *           libmirage_create_disc               (gchar **filenames,
                                                         GObject *debug_context,
                                                         GHashTable *params,
                                                         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.

params, if not NULL, is a GHashTable containing parser parameters (such as password, encoding, etc.) - it must have strings for its keys and values of GValue type. The hash table is passed to the parser; whether parameters are actually used (or supported) by the parser, however, depends on the parser implementation. If parser does not support a parameter, it will be ignored.

If multiple filenames are provided and parser supports only single-file images, only the first filename is used.

`filenames` :	filename(s)
`debug_context` :	debug context to be attached to disc object, or `NULL`
`params` :	parser parameters, or `NULL`
`error` :	location to store error, or `NULL`
Returns :	a MIRAGE_Disc object on success, `NULL` on failure. The reference to the object should be released using `g_object_unref()` when no longer needed.

libmirage_create_fragment ()

GObject *           libmirage_create_fragment           (GType fragment_interface,
                                                         const gchar *filename,
                                                         GError **error);

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

`fragment_interface` :	interface that fragment should implement
`filename` :	filename of data file that fragment should be able to handle
`error` :	location to store error, or `NULL`
Returns :	a MIRAGE_Fragment object on success, `NULL` on failure. The reference to the object should be released using `g_object_unref()` when no longer needed.

libmirage_for_each_parser ()

gboolean            libmirage_for_each_parser           (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.

`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

libmirage_for_each_fragment ()

gboolean            libmirage_for_each_fragment         (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.

`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

libmirage_get_supported_debug_masks ()

gboolean            libmirage_get_supported_debug_masks (const MIRAGE_DebugMask **masks,
                                                         gint *num_masks,
                                                         GError **error);

Retrieves the pointer to array of supported debug masks and stores it in masks. The array consists of one or more structures of type MIRAGE_DebugMask. The number of elements in the array is stored in num_masks. The array belongs to libMirage and should not be altered or freed.

`masks` :	location to store pointer to masks array
`num_masks` :	location to store number of elements in masks array
`error` :	location to store error, or `NULL`
Returns :	`TRUE` on success, `FALSE` on failure

			libMirage Reference Manual
Top \| Description