![]() |
![]() |
![]() |
libMirage Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy |
#include <mirage-context.h> struct MirageContext; struct MirageContextClass; gchar * (*MiragePasswordFunction) (gpointer user_data
); void mirage_context_clear_options (MirageContext *self
); MirageStream * mirage_context_create_input_stream (MirageContext *self
,const gchar *filename
,GError **error
); MirageStream * mirage_context_create_output_stream (MirageContext *self
,const gchar *filename
,const gchar **filter_chain
,GError **error
); const gchar * mirage_context_get_debug_domain (MirageContext *self
); gint mirage_context_get_debug_mask (MirageContext *self
); const gchar * mirage_context_get_debug_name (MirageContext *self
); GVariant * mirage_context_get_option (MirageContext *self
,const gchar *name
); MirageDisc * mirage_context_load_image (MirageContext *self
,gchar **filenames
,GError **error
); gchar * mirage_context_obtain_password (MirageContext *self
,GError **error
); void mirage_context_set_debug_domain (MirageContext *self
,const gchar *domain
); void mirage_context_set_debug_mask (MirageContext *self
,gint debug_mask
); void mirage_context_set_debug_name (MirageContext *self
,const gchar *name
); void mirage_context_set_option (MirageContext *self
,const gchar *name
,GVariant *value
); void mirage_context_set_password_function (MirageContext *self
,MiragePasswordFunction func
,gpointer user_data
);
MirageContext provides a context, which is attached to libMirage's objects. This way, it allows sharing and propagation of settings, such as debug verbosity, parser options, password function, etc. It also provides I/O stream caching, which is used by image parsers and writers.
Due to all the properties it holds, MirageContext is designed as the core object of libMirage and provides the library's main functionality, the loading of image files. Therefore, loading an image usually looks as follows:
initialize the library using mirage_initialize()
create a MirageContext object, i.e. using g_object_new()
and MIRAGE_TYPE_CONTEXT
(optionally) set debug name, domain and mask
load the image using mirage_context_load_image()
struct MirageContext;
All the fields in the MirageContext structure are private to the MirageContext implementation and should never be accessed directly.
struct MirageContextClass { GObjectClass parent_class; };
The class structure for the MirageContext type.
gchar * (*MiragePasswordFunction) (gpointer user_data
);
Password function type used to obtain password for encrypted
images. A password function needs to be set to MirageContext via
mirage_context_set_password_function()
, along with user_data
that
the password function should be called with.
|
user data passed to password function. [in][closure] |
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. |
void mirage_context_clear_options (MirageContext *self
);
Clears all the options from the context.
|
a MirageContext |
MirageStream * mirage_context_create_input_stream (MirageContext *self
,const gchar *filename
,GError **error
);
Opens a file pointed to by filename
and creates a chain of filter
streams on top of it.
|
a MirageContext |
|
filename to create input stream on. [in] |
|
location to store error, or NULL . [out][allow-none]
|
Returns : |
on success, an object implementing MirageStream
interface is returned, which can be used to access data stored in file.
On failure, NULL is returned. The reference to the object should be
released using g_object_unref() when no longer needed. [transfer full]
|
MirageStream * mirage_context_create_output_stream (MirageContext *self
,const gchar *filename
,const gchar **filter_chain
,GError **error
);
Opens a file pointed to by filename
and optionally creates a chain
of filter streams on top of it.
The chain of filters is described by filter
-chain, which is a
NULL-terminated array of strings corresponding to type names of
filters, with the last filter being the one on the top. Filters are
passed by their name types because their actual type values are
determined when the plugins are loaded. If invalid filter is specified
in the chain, this function will fail. It is the caller's responsibility
to construct a valid filter chain.
|
a MirageContext |
|
filename to create output stream on. [in] |
|
NULL-terminated array of strings describing types of filters to include in the filter chain, or NULL . [in][allow-none][array zero-terminated=1]
|
|
location to store error, or NULL . [out][allow-none]
|
Returns : |
on success, an object implementing MirageStream
interface is returned, which can be used to write data to file.
On failure, NULL is returned. The reference to the object should be
released using g_object_unref() when no longer needed. [transfer full]
|
const gchar * mirage_context_get_debug_domain (MirageContext *self
);
Retrieves debug context's domain name.
|
a MirageContext |
Returns : |
pointer to buffer containing the domain name, or NULL . The buffer belongs to the object and should not be modified. [transfer none]
|
gint mirage_context_get_debug_mask (MirageContext *self
);
Retrieves debug context's debug mask.
|
a MirageContext |
Returns : |
debug context's debug mask |
const gchar * mirage_context_get_debug_name (MirageContext *self
);
Retrieves debug context's name.
|
a MirageContext |
Returns : |
pointer to buffer containing the name, or NULL . The buffer belongs to the object and should not be modified. [transfer none]
|
GVariant * mirage_context_get_option (MirageContext *self
,const gchar *name
);
Retrieves option named name
from the context.
|
a MirageContext |
|
option name. [in] |
Returns : |
pointer to a GVariant containing the option
value on success, NULL on failure. [transfer full]
|
MirageDisc * mirage_context_load_image (MirageContext *self
,gchar **filenames
,GError **error
);
Creates a MirageDisc 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) and uses it to load the data
into disc object.
If multiple filenames are provided and parser supports only single-file images, only the first filename is used.
|
a MirageContext |
|
filename(s). [in][array zero-terminated=1] |
|
location to store error, or NULL . [out][allow-none]
|
Returns : |
a MirageDisc object on success, NULL on failure. The reference to
the object should be released using g_object_unref() when no longer needed. [transfer full]
|
gchar * mirage_context_obtain_password (MirageContext *self
,GError **error
);
Obtains password string, using the MiragePasswordFunction callback
that was provided via mirage_context_set_password_function()
.
|
a MirageContext |
|
location to store error, or NULL . [out][allow-none]
|
Returns : |
password string on success, NULL on failure. The string should be
freed with g_free() when no longer needed. |
void mirage_context_set_debug_domain (MirageContext *self
,const gchar *domain
);
Sets debug context's domain name to domain
.
|
a MirageContext |
|
domain name. [in] |
void mirage_context_set_debug_mask (MirageContext *self
,gint debug_mask
);
Sets debug context's debug mask.
|
a MirageContext |
|
debug mask. [in] |
void mirage_context_set_debug_name (MirageContext *self
,const gchar *name
);
Sets debug context's name to name
.
|
a MirageContext |
|
name. [in] |
void mirage_context_set_option (MirageContext *self
,const gchar *name
,GVariant *value
);
Sets an option to the context. If option with the specified name already exists, it is replaced.
|
a MirageContext |
|
option name. [in] |
|
option value. [in][transfer full] |
void mirage_context_set_password_function (MirageContext *self
,MiragePasswordFunction func
,gpointer user_data
);
Sets the password function to context. 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 MirageContext |
|
a password function pointer. [in][allow-none][scope call] |
|
pointer to user data to be passed to the password function. [in][closure] |