MirageContextual

MirageContextual — Interface for attaching context to objects.

Functions

Types and Values

Object Hierarchy

    GInterface
    ╰── MirageContextual

Known Implementations

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

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

Functions

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.

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

Parameters

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.

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

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

Parameters

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.

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, MirageFileFilter