![]() |
![]() |
![]() |
libMirage Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
#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);
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()
.
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.
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 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.
|
typedef struct { gchar *name; gint value; } MIRAGE_DebugMask;
Structure containing debug mask information.
gboolean libmirage_init (GError **error);
Initializes libMirage library. It should be called before any other of libMirage functions.
gboolean libmirage_shutdown (GError **error);
Shuts down libMirage library. It should be called when libMirage is no longer needed.
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.
gchar * libmirage_obtain_password (GError **error);
Obtains password string, using the MIRAGE_PasswordFunction callback that was
provided via libmirage_set_password_function()
.
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.
|
filename(s) |
|
debug context to be attached to disc object, or NULL
|
|
parser parameters, or NULL
|
|
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.
|
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
.
|
interface that fragment should implement |
|
filename of data file that fragment should be able to handle |
|
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.
|
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
.
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
.
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.