![]() |
![]() |
![]() |
libMirage Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
#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
);
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) (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 |
|
user data passed to iteration function |
Returns : |
TRUE on success, otherwise FALSE
|
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.
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure |
gboolean libmirage_shutdown (GError **error
);
Shuts down libMirage library. It should be called when libMirage is no longer needed.
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure |
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.
|
a password function pointer |
|
pointer to user data to be passed to the password function |
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure |
gchar * libmirage_obtain_password (GError **error
);
Obtains password string, using the MIRAGE_PasswordFunction callback that was
provided via libmirage_set_password_function()
.
|
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. |
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
,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
.
|
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
.
|
callback function |
|
data to be passed to callback function |
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure |
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
.
|
callback function |
|
data to be passed to callback function |
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure |
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.
|
location to store pointer to masks array |
|
location to store number of elements in masks array |
|
location to store error, or NULL
|
Returns : |
TRUE on success, FALSE on failure |