Main libMirage functions

## 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