## MirageParser MirageParser — Base object for parsers implementation. |

## Synopsis

    #include <mirage-parser.h>

    struct              MirageParser;
    struct              MirageParserClass;
    struct              MirageParserInfo;
    void                mirage_parser_add_redbook_pregap    (MirageParser *self,
                                                             MirageDisc *disc);
    GDataInputStream *  mirage_parser_create_text_stream    (MirageParser *self,
                                                             GInputStream *stream,
                                                             GError **error);
    void                mirage_parser_generate_info         (MirageParser *self,
                                                             const gchar *id,
                                                             const gchar *name,
                                                             gint num_types,
                                                             ...);
    const MirageParserInfo * mirage_parser_get_info         (MirageParser *self);
    gint                mirage_parser_guess_medium_type     (MirageParser *self,
                                                             MirageDisc *disc);
    void                mirage_parser_info_copy             (const MirageParserInfo *info,
                                                             MirageParserInfo *dest);
    void                mirage_parser_info_free             (MirageParserInfo *info);
    MirageDisc *        mirage_parser_load_image            (MirageParser *self,
                                                             GInputStream **streams,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----MirageObject
             +----MirageParser

## Implemented Interfaces

MirageParser implements MirageContextual.

## Description

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

MirageParser provides a single virtual function - `mirage_parser_load_image()`. This function must be implemented by image parsers, which derive from MirageParser 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 MirageDisc object, which represents the disc stored in the image file(s).

## Details

### struct MirageParser

    struct MirageParser;

All the fields in the MirageParser structure are private to the MirageParser implementation and should never be accessed directly.

### struct MirageParserClass

    struct MirageParserClass {
        MirageObjectClass parent_class;

        /* Class members */
        MirageDisc *(*load_image) (MirageParser *self, GInputStream **streams, GError **error);
    };

The class structure for the MirageParser type.

MirageObjectClass `parent_class`; | the parent class
`load_image` () | loads image

### struct MirageParserInfo

    struct MirageParserInfo {
        gchar *id;
        gchar *name;
        gchar **description;
        gchar **mime_type;
    };

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

gchar *`id`; | parser ID
gchar *`name`; | parser name
gchar **`description`; | zero-terminated array of file type description strings. [array zero-terminated=1]
gchar **`mime_type`; | zero-terminated array of file type MIME strings. [array zero-terminated=1]

### mirage_parser_add_redbook_pregap ()

    void                mirage_parser_add_redbook_pregap    (MirageParser *self,
                                                             MirageDisc *disc);

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. On other discs, it does nothing.

`self` : | a MirageParser
`disc` : | disc object. [in]

### mirage_parser_create_text_stream ()

    GDataInputStream *  mirage_parser_create_text_stream    (MirageParser *self,
                                                             GInputStream *stream,
                                                             GError **error);

Constructs a filter chain for reading text files on top of provided `stream`. First, if encoding is provided via parser parameters, or if a multi-byte encoding is detected, a GConverterInputStream with a GCharsetConverter is applied. Then on top of it, a GDataInputStream is created, which can be used to read text file line-by-line.

`self` : | a MirageParser
`stream` : | a GInputStream. [in][transfer full]
`error` : | location to store error, or `NULL`. [out][allow-none]
Returns : | a GDataInputStream object on success, or `NULL` on failure. [transfer full]

### mirage_parser_generate_info ()

    void                mirage_parser_generate_info         (MirageParser *self,
                                                             const gchar *id,
                                                             const gchar *name,
                                                             gint num_types,
                                                             ...);

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

`self` : | a MirageParser
`id` : | parser ID. [in]
`name` : | parser name. [in]
`num_types` : | number of MIME types. [in]
`...` : | description and MIME type string pairs, one for each defined type. [in]

### mirage_parser_get_info ()

    const MirageParserInfo * mirage_parser_get_info         (MirageParser *self);

Retrieves parser information.

`self` : | a MirageParser
Returns : | a pointer to parser information structure. The structure belongs to object and should not be modified. [transfer none]

### mirage_parser_guess_medium_type ()

    gint                mirage_parser_guess_medium_type     (MirageParser *self,
                                                             MirageDisc *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 MirageParser
`disc` : | disc object. [in]
Returns : | a value from MirageMediumTypes, according to the guessed medium type.

### mirage_parser_info_copy ()

    void                mirage_parser_info_copy             (const MirageParserInfo *info,
                                                             MirageParserInfo *dest);

Copies parser information from `info` to `dest`.

`info` : | a MirageParserInfo to copy data from. [in]
`dest` : | a MirageParserInfo to copy data to. [in]

### mirage_parser_info_free ()

    void                mirage_parser_info_free             (MirageParserInfo *info);

Frees the allocated fields in `info` (but not the structure itself!).

`info` : | a MirageParserInfo to free. [in]

### mirage_parser_load_image ()

    MirageDisc *        mirage_parser_load_image            (MirageParser *self,
                                                             GInputStream **streams,
                                                             GError **error);

Loads the image stored in `streams`.

`self` : | a MirageParser
`streams` : | `NULL`-terminated array of data streams. [in][array zero-terminated=1]
`error` : | location to store error, or `NULL`. [out][allow-none]
Returns : | a MirageDisc object representing image on success, `NULL` on failure. [transfer full]

## See Also

MirageDisc, MirageContext