Main libMirage functions

Main libMirage functions — Main libMirage functions

Synopsis


#include <mirage.h>

gboolean            (*MIRAGE_CallbackFunction)          (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,
                                                         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)          (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_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,
                                                         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