## Main Main — Core libMirage functions |

## Synopsis

    #include <mirage.h>

                        MirageDebugMask;
    gboolean            (*MirageEnumFileFilterInfoCallback) (const MirageFileFilterInfo *info,
                                                             gpointer user_data);
    gboolean            (*MirageEnumParserInfoCallback)     (const MirageParserInfo *info,
                                                             gpointer user_data);
    gboolean            mirage_enumerate_file_filters       (MirageEnumFileFilterInfoCallback func,
                                                             gpointer user_data,
                                                             GError **error);
    gboolean            mirage_enumerate_parsers            (MirageEnumParserInfoCallback func,
                                                             gpointer user_data,
                                                             GError **error);
    gboolean            mirage_get_file_filters_info        (const MirageFileFilterInfo **info,
                                                             gint *num_file_filters,
                                                             GError **error);
    gboolean            mirage_get_file_filters_type        (const GType **types,
                                                             gint *num_file_filters,
                                                             GError **error);
    gboolean            mirage_get_parsers_info             (const MirageParserInfo **info,
                                                             gint *num_parsers,
                                                             GError **error);
    gboolean            mirage_get_parsers_type             (const GType **types,
                                                             gint *num_parsers,
                                                             GError **error);
    gboolean            mirage_get_supported_debug_masks    (const MirageDebugMask **masks,
                                                             gint *num_masks,
                                                             GError **error);
    gboolean            mirage_initialize                   (GError **error);
    gboolean            mirage_shutdown                     (GError **error);

## Description

These functions represent the core of the libMirage API. Before the library can be used, it must be initialized using `mirage_initialize()`, which loads the plugins containing image parsers and file filters. When library is no longer needed, it can be shut down using `mirage_shutdown()`, which unloads the plugins.

The core functions listed in this section enable enumeration of supported parsers and file filters. Most of the core functionality of libMirage, such as loading images, is encapsulated in MirageContext object, which can be obtained using GLib's `g_object_new()`.

## Details

### MirageDebugMask

    typedef struct {
        gchar *name;
        gint value;
    } MirageDebugMask;

Structure containing debug mask information.

gchar *`name`; | name
gint `value`; | value

### MirageEnumFileFilterInfoCallback ()

    gboolean            (*MirageEnumFileFilterInfoCallback) (const MirageFileFilterInfo *info,
                                                             gpointer user_data);

Callback function type used with `mirage_enumerate_file_filters()`. A pointer to file filter information structure is stored in `info`; the structure belongs to the file filter object and should not be modified. `user_data` is user data passed to enumeration function.

`info` : | file filter info. [in]
`user_data` : | user data passed to enumeration function. [in][closure]
Returns : | `TRUE` on success, otherwise `FALSE`

### MirageEnumParserInfoCallback ()

    gboolean            (*MirageEnumParserInfoCallback)     (const MirageParserInfo *info,
                                                             gpointer user_data);

Callback function type used with `mirage_enumerate_parsers()`. A pointer to parser information structure is stored in `info`; the structure belongs to the parser object and should not be modified. `user_data` is user data passed to enumeration function.

`info` : | parser info. [in]
`user_data` : | user data passed to enumeration function. [in][closure]
Returns : | `TRUE` on success, otherwise `FALSE`

### mirage_enumerate_file_filters ()

    gboolean            mirage_enumerate_file_filters       (MirageEnumFileFilterInfoCallback func,
                                                             gpointer user_data,
                                                             GError **error);

Iterates over list of supported file filters, calling `func` for each file filter.

If `func` returns `FALSE`, the function immediately returns `FALSE`.

`func` : | callback function. [in][scope call]
`user_data` : | data to be passed to callback function. [in][closure]
`error` : | location to store error, or `NULL`. [out][allow-none]
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_enumerate_parsers ()

    gboolean            mirage_enumerate_parsers            (MirageEnumParserInfoCallback func,
                                                             gpointer user_data,
                                                             GError **error);

Iterates over list of supported parsers, calling `func` for each parser.

If `func` returns `FALSE`, the function immediately returns `FALSE`.

`func` : | callback function. [in][scope call]
`user_data` : | data to be passed to callback function. [in][closure]
`error` : | location to store error, or `NULL`. [out][allow-none]
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_get_file_filters_info ()

    gboolean            mirage_get_file_filters_info        (const MirageFileFilterInfo **info,
                                                             gint *num_file_filters,
                                                             GError **error);

Retrieves information structures for supported file filters.

`info` : | array of file filters' information structures. [out][array length=num_file_filters][transfer none]
`num_file_filters` : | number of supported file filters. [out]
`error` : | location to store error, or `NULL`. [out][allow-none]
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_get_file_filters_type ()

    gboolean            mirage_get_file_filters_type        (const GType **types,
                                                             gint *num_file_filters,
                                                             GError **error);

Retrieves GType values for supported file filters.

`types` : | array of file filters' GType values. [out][array length=num_file_filters][transfer none]
`num_file_filters` : | number of supported file filters. [out]
`error` : | location to store error, or `NULL`. [out][allow-none]
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_get_parsers_info ()

    gboolean            mirage_get_parsers_info             (const MirageParserInfo **info,
                                                             gint *num_parsers,
                                                             GError **error);

Retrieves information structures for supported parsers.

`info` : | array of parsers' information structures. [out][array length=num_parsers][transfer none]
`num_parsers` : | number of supported parsers. [out]
`error` : | location to store error, or `NULL`. [out][allow-none]
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_get_parsers_type ()

    gboolean            mirage_get_parsers_type             (const GType **types,
                                                             gint *num_parsers,
                                                             GError **error);

Retrieves GType values for supported parsers.

`types` : | array of parsers' GType values. [out][array length=num_parsers][transfer none]
`num_parsers` : | number of supported parsers. [out]
`error` : | location to store error, or `NULL`. [out][allow-none]
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_get_supported_debug_masks ()

    gboolean            mirage_get_supported_debug_masks    (const MirageDebugMask **masks,
                                                             gint *num_masks,
                                                             GError **error);

Retrieves the pointer to array of supported debug masks and stores it in `masks`. The array consists of one or more structures of type MirageDebugMask. The number of elements in the array is stored in `num_masks`. The array belongs to libMirage and should not be altered or freed.

`masks` : | location to store pointer to masks array. [out][transfer none][array length=num_masks]
`num_masks` : | location to store number of elements in masks array. [out]
`error` : | location to store error, or `NULL`. [out][allow-none]
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_initialize ()

    gboolean            mirage_initialize                   (GError **error);

Initializes libMirage library. It should be called before any other of libMirage functions.

`error` : | location to store error, or `NULL`. [out][allow-none]
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_shutdown ()

    gboolean            mirage_shutdown                     (GError **error);

Shuts down libMirage library. It should be called when libMirage is no longer needed.

`error` : | location to store error, or `NULL`. [out][allow-none]
Returns : | `TRUE` on success, `FALSE` on failure

## See Also

MirageContext