## MirageContext MirageContext — Context object. |

## Synopsis

    #include <mirage-context.h>

    struct              MirageContext;
    struct              MirageContextClass;
    gchar *             (*MiragePasswordFunction)           (gpointer user_data);
    void                mirage_context_clear_options        (MirageContext *self);
    GInputStream *      mirage_context_create_file_stream   (MirageContext *self,
                                                             const gchar *filename,
                                                             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);
    const gchar *       mirage_context_get_file_stream_filename
                                                            (MirageContext *self,
                                                             GInputStream *stream);
    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);

## Object Hierarchy

      GObject
       +----MirageContext

## 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 file stream caching and GInputStream to filename resolution, which is used by image parsers.

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

## Details

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

GObjectClass `parent_class`; | the parent class

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

`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.

`self` : | a MirageContext

### mirage_context_create_file_stream ()

    GInputStream *      mirage_context_create_file_stream   (MirageContext *self,
                                                             const gchar *filename,
                                                             GError **error);

Opens a file pointed to by `filename` and creates a chain of file filters on top of it.

`self` : | a MirageContext
`filename` : | filename to create stream on. [in]
`error` : | location to store error, or `NULL`. [out][allow-none]
Returns : | on success, an object inheriting GFilterInputStream (and therefore GInputStream) and implementing GSeekable 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_get_debug_domain ()

    const gchar *       mirage_context_get_debug_domain     (MirageContext *self);

Retrieves debug context's domain name.

`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.

`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.

`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_file_stream_filename ()

    const gchar *       mirage_context_get_file_stream_filename
                                                            (MirageContext *self,
                                                             GInputStream *stream);

Traverses the chain of file filters and retrieves the filename on which the GFileInputStream, located at the bottom of the chain, was opened.

`self` : | a MirageContext
`stream` : | a GInputStream. [in]
Returns : | on success, a pointer to filename on which the underyling file stream was opened. On failure, `NULL` is returned. [transfer none]

### mirage_context_get_option ()

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

Retrieves option named `name` from the context.

`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.

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

`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`.

`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.

`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`.

`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.

`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);

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.

`self` : | a MirageContext
`func` : | a password function pointer. [in][allow-none][scope call]
`user_data` : | pointer to user data to be passed to the password function. [in][closure]

## See Also

MirageContextual, MirageObject, MirageFileFilter