## MirageContextual MirageContextual — Interface for attaching context to objects. |

## Synopsis

    #include <mirage-contextual.h>

                        MirageContextual;
    struct              MirageContextualInterface;
    GInputStream *      mirage_contextual_create_file_stream
                                                            (MirageContextual *self,
                                                             const gchar *filename,
                                                             GError **error);
    void                mirage_contextual_debug_message     (MirageContextual *self,
                                                             gint level,
                                                             gchar *format,
                                                             ...);
    void                mirage_contextual_debug_messagev    (MirageContextual *self,
                                                             gint level,
                                                             gchar *format,
                                                             va_list args);
    MirageContext *     mirage_contextual_get_context       (MirageContextual *self);
    const gchar *       mirage_contextual_get_file_stream_filename
                                                            (MirageContextual *self,
                                                             GInputStream *stream);
    GVariant *          mirage_contextual_get_option        (MirageContextual *self,
                                                             const gchar *name);
    gchar *             mirage_contextual_obtain_password   (MirageContextual *self,
                                                             GError **error);
    void                mirage_contextual_set_context       (MirageContextual *self,
                                                             MirageContext *context);

## Object Hierarchy

      GInterface
       +----MirageContextual

## Known Implementations

MirageContextual is implemented by MirageCdTextCoder, MirageDisc, MirageFileFilter, MirageFragment, MirageIndex, MirageLanguage, MirageObject, MirageParser, MirageSector, MirageSession and MirageTrack.

## Description

MirageContextual provides an interface that allows attachment of a MirageContext to the object implementing it. The object must implement two functions for getting and setting the context - `mirage_contextual_get_context()` and `mirage_contextual_set_context()`.

In addition, MirageContextual provides some shared code that can be used by implementations. Most notable are debugging facilities, in form of functions `mirage_contextual_debug_message()` and `mirage_contextual_debug_messagev()`, which print debug messages depending on the settings of the attached context.

Furthermore, for convenience of parser and file filter implementations, passthrough is provided for some functions of MirageContext. Using these functions is equivalent to getting and verifying the attached context, calling its function directly, and releasing the reference.

## Details

### MirageContextual

    typedef struct _MirageContextual MirageContextual;

An object that can be attached a MirageContext.

### struct MirageContextualInterface

    struct MirageContextualInterface {
        GTypeInterface parent_iface;

        /* Interface methods */
        void (*set_context) (MirageContextual *self, MirageContext *context);
        MirageContext *(*get_context) (MirageContextual *self);
    };

Provides an interface for implementing objects that can be attached a MirageContext.

GTypeInterface `parent_iface`; | the parent interface
`set_context` () | sets/attaches the context
`get_context` () | retrieves the attached context

### mirage_contextual_create_file_stream ()

    GInputStream *      mirage_contextual_create_file_stream
                                                            (MirageContextual *self,
                                                             const gchar *filename,
                                                             GError **error);

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

### Note

This is a convenience function that retrieves a MirageContext from `self` and calls `mirage_context_create_file_stream()`.

`self` : | a MirageContextual
`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_contextual_debug_message ()

    void                mirage_contextual_debug_message     (MirageContextual *self,
                                                             gint level,
                                                             gchar *format,
                                                             ...);

Outputs debug message with verbosity level `level`, format string `format` and format arguments `Varargs`. The message is displayed if debug context has mask that covers `level`, or if `level` is either `MIRAGE_DEBUG_WARNING` or `MIRAGE_DEBUG_ERROR`.

`self` : | a MirageContextual
`level` : | debug level. [in]
`format` : | message format. See the `printf()` documentation. [in]
`...` : | parameters to insert into the format string. [in]

### mirage_contextual_debug_messagev ()

    void                mirage_contextual_debug_messagev    (MirageContextual *self,
                                                             gint level,
                                                             gchar *format,
                                                             va_list args);

Outputs debug message with verbosity level `level`, format string `format` and format arguments `args`. The message is displayed if debug context has mask that covers `level`, or if `level` is either `MIRAGE_DEBUG_WARNING` or `MIRAGE_DEBUG_ERROR`.

`self` : | a MirageContextual
`level` : | debug level. [in]
`format` : | message format. See the `printf()` documentation. [in]
`args` : | parameters to insert into the format string. [in]

### mirage_contextual_get_context ()

    MirageContext *     mirage_contextual_get_context       (MirageContextual *self);

Retrieves the attached context.

`self` : | a MirageContextual
Returns : | attached context (a MirageContext), or `NULL`. The reference to context is incremented, and should be released using `g_object_unref()` when no longer needed. [transfer full]

### mirage_contextual_get_file_stream_filename ()

    const gchar *       mirage_contextual_get_file_stream_filename
                                                            (MirageContextual *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.

### Note

This is a convenience function that retrieves a MirageContext from `self` and calls `mirage_context_get_file_stream_filename()`.

`self` : | a MirageContextual
`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_contextual_get_option ()

    GVariant *          mirage_contextual_get_option        (MirageContextual *self,
                                                             const gchar *name);

Retrieves option named `name` from the context.

### Note

This is a convenience function that retrieves a MirageContext from `self` and calls `mirage_context_get_option()`.

`self` : | a MirageContextual
`name` : | option name. [in]
Returns : | a GVariant containing the option value on success, `NULL` on failure. [transfer full]

### mirage_contextual_obtain_password ()

    gchar *             mirage_contextual_obtain_password   (MirageContextual *self,
                                                             GError **error);

Obtains password string, using the MiragePasswordFunction callback that was provided via `mirage_context_set_password_function()`.

### Note

This is a convenience function that retrieves a MirageContext from `self` and calls `mirage_context_obtain_password()`.

`self` : | a MirageContextual
`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_contextual_set_context ()

    void                mirage_contextual_set_context       (MirageContextual *self,
                                                             MirageContext *context);

Sets/attaches a context.

`self` : | a MirageContextual
`context` : | debug context (a MirageContext). [in][transfer full]

## See Also

MirageContext, MirageObject, MirageFileFilter