MIRAGE_Parser object

## MIRAGE_Parser object MIRAGE_Parser object — Base object for parsers implementation |

## Synopsis

    #include <mirage.h>

                        MIRAGE_ParserInfo;
                        MIRAGE_Parser;
    void                mirage_parser_generate_parser_info  (MIRAGE_Parser *self,
                                                             gchar *id,
                                                             gchar *name,
                                                             gchar *description,
                                                             gchar *mime_type);
    gboolean            mirage_parser_get_parser_info       (MIRAGE_Parser *self,
                                                             MIRAGE_ParserInfo **parser_info,
                                                             GError **error);
    gboolean            mirage_parser_load_image            (MIRAGE_Parser *self,
                                                             gchar **filenames,
                                                             GObject **disc,
                                                             GError **error);
    gboolean            mirage_parser_add_redbook_pregap    (MIRAGE_Parser *self,
                                                             GObject *disc,
                                                             GError **error);
    gint                mirage_parser_guess_medium_type     (MIRAGE_Parser *self,
                                                             GObject *disc);
    gboolean            mirage_parser_get_param_string      (MIRAGE_Parser *self,
                                                             gchar *name,
                                                             const gchar **value,
                                                             GError **error);
    gboolean            mirage_parser_set_params            (MIRAGE_Parser *self,
                                                             GHashTable *params,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----MIRAGE_Object
             +----MIRAGE_Parser

## Description

MIRAGE_Parser object is a base object for image parser implementations. In addition to providing function for image loading and obtaining parser information, it also provides some helper functions that can be used in parser implementations.

MIRAGE_Parser provides a single virtual function - `mirage_parser_load_image()`. This function must be implemented by image parsers, which derive from MIRAGE_Parser object. The function must first check if given file(s) are supported by the given parser, and then the actual loading is performed. The result is a MIRAGE_Disc object, which represents the disc stored in the image file(s).

## Details

### MIRAGE_ParserInfo

    typedef struct {
        gchar *id;
        gchar *name;
        gchar *description;
        gchar *mime_type;
    } MIRAGE_ParserInfo;

A structure containing parser information. It can be obtained with call to `mirage_parser_get_parser_info()`.

`description` is a string contraining image file description (e.g. "CloneCD images") and `mime_type` is a string representing the image file MIME type (e.g. "application/libmirage-mds"). Together, this information is intended to be used for building file type filters in GUI applications.

gchar *`id`; | parser ID
gchar *`name`; | parser name
gchar *`description`; | image file description
gchar *`mime_type`; | image file MIME type

### MIRAGE_Parser

    typedef struct _MIRAGE_Parser MIRAGE_Parser;

Contains private data only, and should be accessed using the functions below.

### mirage_parser_generate_parser_info ()

    void                mirage_parser_generate_parser_info  (MIRAGE_Parser *self,
                                                             gchar *id,
                                                             gchar *name,
                                                             gchar *description,
                                                             gchar *mime_type);

Generates parser information from the input fields. It is intended as a function for creating parser information in parser implementations.

`self` : | a MIRAGE_Parser
`id` : | parser ID
`name` : | parser name
`description` : | image file description
`mime_type` : | image file MIME type

### mirage_parser_get_parser_info ()

    gboolean            mirage_parser_get_parser_info       (MIRAGE_Parser *self,
                                                             MIRAGE_ParserInfo **parser_info,
                                                             GError **error);

Retrieves parser information.

`parser_info` points to parser information that belongs to parser implementation, and therefore should not be freed.

`self` : | a MIRAGE_Parser
`parser_info` : | location to store parser info
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_parser_load_image ()

    gboolean            mirage_parser_load_image            (MIRAGE_Parser *self,
                                                             gchar **filenames,
                                                             GObject **disc,
                                                             GError **error);

Loads the image stored in `filenames`.

`self` : | a MIRAGE_Parser
`filenames` : | image filename(s)
`disc` : | location to store the resulting MIRAGE_Disc object
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_parser_add_redbook_pregap ()

    gboolean            mirage_parser_add_redbook_pregap    (MIRAGE_Parser *self,
                                                             GObject *disc,
                                                             GError **error);

A helper function, intended to be used in simpler parsers that don't get proper pregap information from the image file.

First, it sets disc layout start to -150. Then, it adds 150-sector pregap to first track of each session found on the layout; for this, a NULL fragment is used. If track already has a pregap, then the pregaps are stacked.

Note that the function works only on discs which have medium type set to CD-ROM.

`self` : | a MIRAGE_Parser
`disc` : | disc object
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_parser_guess_medium_type ()

    gint                mirage_parser_guess_medium_type     (MIRAGE_Parser *self,
                                                             GObject *disc);

Attempts to guess medium type by looking at the length of the disc layout. Currently, it supports identification of CD-ROM media, which are assumed to have layout length of 90 minutes or less.

Note that this function does not set the medium type to disc object; you still need to do it via `mirage_disc_set_medium_type()`. It is meant to be used in simple parsers whose image files don't provide medium type information.

`self` : | a MIRAGE_Parser
`disc` : | disc object
Returns : | a value from MIRAGE_MediumTypes, according to the guessed medium type.

### mirage_parser_get_param_string ()

    gboolean            mirage_parser_get_param_string      (MIRAGE_Parser *self,
                                                             gchar *name,
                                                             const gchar **value,
                                                             GError **error);

An internal function that retrieves a string parameter named `name`. It is meant to be used by parser implementation to retrieve the parameter value during the parsing.

Note that pointer to string is returned; the string belongs to whoever owns the parameters hash table that was passed to the parser, and as such should not be freed after no longer needed.

`self` : | a MIRAGE_Parser
`name` : | parameter name (key)
`value` : | location to store the string value, or `NULL`
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_parser_set_params ()

    gboolean            mirage_parser_set_params            (MIRAGE_Parser *self,
                                                             GHashTable *params,
                                                             GError **error);

An internal function that sets the parsing parameters to parser (such as password, encoding, etc.). It is meant to be used by `libmirage_create_disc()` to pass the parsing parameters to parser before performing the parsing.

`params` is a GHashTable that must have strings for its keys and values of GValue type.

Note that only pointer to `params` is stored; therefore, the hash table must still be valid when `mirage_parser_load_image()` is called. Another thing to note is that whether parameter is used or not is up to the parser implementation. In case of unsupported parameter, the parser implementation should simply ignore it.

`self` : | a MIRAGE_Parser
`params` : | a GHashTable containing parameters
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

## See Also

MIRAGE_Disc