MirageContext

MirageContext — Context object.

Functions

Types and Values

Object Hierarchy

    GObject
    ╰── MirageContext

Includes

#include <mirage-context.h>

Description

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:

Functions

MiragePasswordFunction ()

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.

Parameters

user_data

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.


mirage_context_clear_options ()

void
mirage_context_clear_options (MirageContext *self);

Clears all the options from the context.

Parameters

self

a MirageContext

 

mirage_context_create_input_stream ()

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.

Parameters

self

a MirageContext

 

filename

filename to create input stream on.

[in]

error

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]


mirage_context_create_output_stream ()

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.

Parameters

self

a MirageContext

 

filename

filename to create output stream on.

[in]

filter_chain

NULL-terminated array of strings describing types of filters to include in the filter chain, or NULL.

[in][allow-none][array zero-terminated=1]

error

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]


mirage_context_get_debug_domain ()

const gchar *
mirage_context_get_debug_domain (MirageContext *self);

Retrieves debug context's domain name.

Parameters

self

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]


mirage_context_get_debug_mask ()

gint
mirage_context_get_debug_mask (MirageContext *self);

Retrieves debug context's debug mask.

Parameters

self

a MirageContext

 

Returns

debug context's debug mask


mirage_context_get_debug_name ()

const gchar *
mirage_context_get_debug_name (MirageContext *self);

Retrieves debug context's name.

Parameters

self

a MirageContext

 

Returns

pointer to buffer containing the name, or NULL. The buffer belongs to the object and should not be modified.

[transfer none]


mirage_context_get_option ()

GVariant *
mirage_context_get_option (MirageContext *self,
                           const gchar *name);

Retrieves option named name from the context.

Parameters

self

a MirageContext

 

name

option name.

[in]

Returns

pointer to a GVariant containing the option value on success, NULL on failure.

[transfer full]


mirage_context_load_image ()

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.

Parameters

self

a MirageContext

 

filenames

filename(s).

[in][array zero-terminated=1]

error

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]


mirage_context_obtain_password ()

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().

Parameters

self

a MirageContext

 

error

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.


mirage_context_set_debug_domain ()

void
mirage_context_set_debug_domain (MirageContext *self,
                                 const gchar *domain);

Sets debug context's domain name to domain .

Parameters

self

a MirageContext

 

domain

domain name.

[in]

mirage_context_set_debug_mask ()

void
mirage_context_set_debug_mask (MirageContext *self,
                               gint debug_mask);

Sets debug context's debug mask.

Parameters

self

a MirageContext

 

debug_mask

debug mask.

[in]

mirage_context_set_debug_name ()

void
mirage_context_set_debug_name (MirageContext *self,
                               const gchar *name);

Sets debug context's name to name .

Parameters

self

a MirageContext

 

name

name.

[in]

mirage_context_set_option ()

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.

Parameters

self

a MirageContext

 

name

option name.

[in]

value

option value.

[in][transfer full]

mirage_context_set_password_function ()

void
mirage_context_set_password_function (MirageContext *self,
                                      MiragePasswordFunction func,
                                      gpointer user_data,
                                      GDestroyNotify destroy);

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.

Parameters

self

a MirageContext

 

func

a password function pointer.

[in][allow-none][scope notified]

user_data

pointer to user data to be passed to the password function.

[in][closure]

destroy

destroy notify for user_data , or NULL.

[in][allow-none]

Types and Values

struct MirageContext

struct MirageContext;

All the fields in the MirageContext structure are private to the MirageContext implementation and should never be accessed directly.


struct MirageContextClass

struct MirageContextClass {
    GObjectClass parent_class;
};

The class structure for the MirageContext type.

Members

See Also

MirageContextual, MirageObject