MirageContextual

MirageContextual — Interface for attaching context to objects.

Synopsis


#include <mirage-contextual.h>

                    MirageContextual;
                    MirageContextualInterface;
MirageStream *      mirage_contextual_create_input_stream
                                                        (MirageContextual *self,
                                                         const gchar *filename,
                                                         GError **error);
MirageStream *      mirage_contextual_create_output_stream
                                                        (MirageContextual *self,
                                                         const gchar *filename,
                                                         const gchar **filter_chain,
                                                         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);
gboolean            mirage_contextual_debug_is_active   (MirageContextual *self,
                                                         gint level);
void                mirage_contextual_debug_print_buffer
                                                        (MirageContextual *self,
                                                         gint level,
                                                         const gchar *prefix,
                                                         gint width,
                                                         const guint8 *buffer,
                                                         gint buffer_length);
MirageContext *     mirage_contextual_get_context       (MirageContextual *self);
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 MirageSector, MirageCdTextCoder, MirageFragment, MirageFileStream, MirageLanguage, MirageDisc, MirageIndex, MirageWriter, MirageTrack, MirageParser, MirageSession, MirageObject and MirageFilterStream.

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.

Details

MirageContextual

typedef struct _MirageContextual MirageContextual;

An object that can be attached a MirageContext.

MirageContextualInterface

typedef struct {
    GTypeInterface parent_iface;

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

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

Note

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

self :

 a MirageContextual

filename :

 filename to create input stream on. in.

error :

 location to store error, or NULL. out. allow-none.

Returns :

 transfer full. 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.

Note

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

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 :

 transfer full. 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_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.

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.

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.

self :

 a MirageContextual

Returns :

 transfer full. transfer full.

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 :

 transfer full. 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
Generated by GTK-Doc V1.11