## MirageContextual

MirageContextual — Interface for attaching context to objects.

## Functions

MirageStream * | mirage_contextual_create_input_stream ()
MirageStream * | mirage_contextual_create_output_stream ()
void | mirage_contextual_debug_message ()
void | mirage_contextual_debug_messagev ()
gboolean | mirage_contextual_debug_is_active ()
void | mirage_contextual_debug_print_buffer ()
MirageContext * | mirage_contextual_get_context ()
GVariant * | mirage_contextual_get_option ()
gchar * | mirage_contextual_obtain_password ()
void | mirage_contextual_set_context ()

## Types and Values

| MirageContextual
struct | MirageContextualInterface

## Object Hierarchy

        GInterface
        ╰── MirageContextual

## Known Implementations

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

## Includes

    #include <mirage-contextual.h>

## 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 image parser and filter stream 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.

## Functions

### mirage_contextual_create_input_stream ()

    MirageStream *
    mirage_contextual_create_input_stream (MirageContextual *self,
                                           const gchar *filename,
                                           GError **error);

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

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

#### Parameters

self | a MirageContextual |
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_contextual_create_output_stream ()

    MirageStream *
    mirage_contextual_create_output_stream
                                   (MirageContextual *self,
                                    const gchar *filename,
                                    const gchar **filter_chain,
                                    GError **error);

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

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

#### Parameters

self | a MirageContextual |
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_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`.

#### Parameters

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

#### Parameters

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

    gboolean
    mirage_contextual_debug_is_active (MirageContextual *self,
                                       gint level);

Checks whether debug messages at debug level `level` are currently active or not.

#### Parameters

self | a MirageContextual |
level | debug level. | [in]

#### Returns

a boolean indicating whether debug messages at debug level `level` are currently active or not.

### mirage_contextual_debug_print_buffer ()

    void
    mirage_contextual_debug_print_buffer (MirageContextual *self,
                                          gint level,
                                          const gchar *prefix,
                                          gint width,
                                          const guint8 *buffer,
                                          gint buffer_length);

Prints contents of `buffer` as a sequence of `buffer_length` two-digit hexadecimal numbers, arranged in lines of `width` numbers. Each line is optionally prefixed by `prefix` . If specified debug `level` is not active (masked by context), this function does nothing.

#### Parameters

self | a MirageContextual |
level | debug level. | [in]
prefix | prefix, or none. | [in][allow-none]
width | output width. | [in]
buffer | buffer to print. | [in][array length=buffer_length]
buffer_length | buffer length. | [in]

### mirage_contextual_get_context ()

    MirageContext *
    mirage_contextual_get_context (MirageContextual *self);

Retrieves the attached context.

#### Parameters

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

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

Retrieves option named `name` from the context.

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

#### Parameters

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

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

#### Parameters

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.

#### Parameters

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

## Types and Values

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

#### Members

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

## See Also

MirageContext, MirageObject