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