MIRAGE_Fragment object

## MIRAGE_Fragment object MIRAGE_Fragment object — Base object for fragment implementations |

## Synopsis

    #include <mirage.h>

                        MIRAGE_FragmentInfo;
                        MIRAGE_Fragment;
    void                mirage_fragment_generate_fragment_info
                                                            (MIRAGE_Fragment *self,
                                                             gchar *id,
                                                             gchar *name);
    gboolean            mirage_fragment_get_fragment_info   (MIRAGE_Fragment *self,
                                                             MIRAGE_FragmentInfo **fragment_info,
                                                             GError **error);
    gboolean            mirage_fragment_can_handle_data_format
                                                            (MIRAGE_Fragment *self,
                                                             gchar *filename,
                                                             GError **error);
    gboolean            mirage_fragment_set_address         (MIRAGE_Fragment *self,
                                                             gint address,
                                                             GError **error);
    gboolean            mirage_fragment_get_address         (MIRAGE_Fragment *self,
                                                             gint *address,
                                                             GError **error);
    gboolean            mirage_fragment_set_length          (MIRAGE_Fragment *self,
                                                             gint length,
                                                             GError **error);
    gboolean            mirage_fragment_get_length          (MIRAGE_Fragment *self,
                                                             gint *length,
                                                             GError **error);
    gboolean            mirage_fragment_use_the_rest_of_file
                                                            (MIRAGE_Fragment *self,
                                                             GError **error);
    gboolean            mirage_fragment_read_main_data      (MIRAGE_Fragment *self,
                                                             gint address,
                                                             guint8 *buf,
                                                             gint *length,
                                                             GError **error);
    gboolean            mirage_fragment_read_subchannel_data
                                                            (MIRAGE_Fragment *self,
                                                             gint address,
                                                             guint8 *buf,
                                                             gint *length,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----MIRAGE_Object
             +----MIRAGE_Fragment

## Description

MIRAGE_Fragment object is a base object for fragment implementations. It provides functions that are used by image parsers to provide access to data in image files.

MIRAGE_Fragment provides two virtual functions: `mirage_fragment_get_fragment_info()`, `mirage_fragment_can_handle_data_format()`. These must be implemented by fragment implementations which derive from MIRAGE_Fragment object.

Every fragment implementation needs to implement one of fragment interfaces: MIRAGE_FInterface_NULL, MIRAGE_FInterface_BINARY or MIRAGE_FInterface_AUDIO. Which interface a fragment implementation implements depends on the way the implementation handles data.

## Details

### MIRAGE_FragmentInfo

    typedef struct {
        gchar *id;
        gchar *name;
    } MIRAGE_FragmentInfo;

A structure containing fragment information. It can be obtained with call to `mirage_fragment_get_fragment_info()`.

gchar *`id`; | fragment ID
gchar *`name`; | fragment name

### MIRAGE_Fragment

    typedef struct _MIRAGE_Fragment MIRAGE_Fragment;

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

### mirage_fragment_generate_fragment_info ()

    void                mirage_fragment_generate_fragment_info
                                                            (MIRAGE_Fragment *self,
                                                             gchar *id,
                                                             gchar *name);

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

`self` : | a MIRAGE_Fragment
`id` : | fragment ID
`name` : | fragment name

### mirage_fragment_get_fragment_info ()

    gboolean            mirage_fragment_get_fragment_info   (MIRAGE_Fragment *self,
                                                             MIRAGE_FragmentInfo **fragment_info,
                                                             GError **error);

Retrieves fragment information.

`fragment_info` points to fragment information that belongs to fragment implementation, and therefore should not be freed.

`self` : | a MIRAGE_Fragment
`fragment_info` : | location to store fragment info
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_fragment_can_handle_data_format ()

    gboolean            mirage_fragment_can_handle_data_format
                                                            (MIRAGE_Fragment *self,
                                                             gchar *filename,
                                                             GError **error);

Checks whether parser can handle data stored in `filename`.

`self` : | a MIRAGE_Fragment
`filename` : | filename
`error` : | location to store error, or `NULL`
Returns : | `TRUE` if fragment can handle data file, `FALSE` if not

### mirage_fragment_set_address ()

    gboolean            mirage_fragment_set_address         (MIRAGE_Fragment *self,
                                                             gint address,
                                                             GError **error);

Sets fragment's start address. The `address` is given in sectors.

### Note

Intended for internal use only.

### Note

Causes top-down change.

`self` : | a MIRAGE_Fragment
`address` : | start address
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_fragment_get_address ()

    gboolean            mirage_fragment_get_address         (MIRAGE_Fragment *self,
                                                             gint *address,
                                                             GError **error);

Retrieves fragment's start address. The `address` is given in sectors.

### Note

Intended for internal use only.

`self` : | a MIRAGE_Fragment
`address` : | location to store start address
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_fragment_set_length ()

    gboolean            mirage_fragment_set_length          (MIRAGE_Fragment *self,
                                                             gint length,
                                                             GError **error);

Sets fragment's length. The `length` is given in sectors.

### Note

Intended for internal use only.

### Note

Causes bottom-up change.

`self` : | a MIRAGE_Fragment
`length` : | length
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_fragment_get_length ()

    gboolean            mirage_fragment_get_length          (MIRAGE_Fragment *self,
                                                             gint *length,
                                                             GError **error);

Retrieves fragment's length. The returned `length` is given in sectors.

### Note

Intended for internal use only.

`self` : | a MIRAGE_Fragment
`length` : | location to store length
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_fragment_use_the_rest_of_file ()

    gboolean            mirage_fragment_use_the_rest_of_file
                                                            (MIRAGE_Fragment *self,
                                                             GError **error);

Uses the rest of data file. It automatically calculates and sets fragment's length.

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

### mirage_fragment_read_main_data ()

    gboolean            mirage_fragment_read_main_data      (MIRAGE_Fragment *self,
                                                             gint address,
                                                             guint8 *buf,
                                                             gint *length,
                                                             GError **error);

Reads main channel selection data for sector at fragment-relative `address` into `buf` and stores read length into `length`. Both `address` and and `length` is given in sectors.

`self` : | a MIRAGE_Fragment
`address` : | address
`buf` : | buffer to read data into
`length` : | location to store read data length
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_fragment_read_subchannel_data ()

    gboolean            mirage_fragment_read_subchannel_data
                                                            (MIRAGE_Fragment *self,
                                                             gint address,
                                                             guint8 *buf,
                                                             gint *length,
                                                             GError **error);

Reads subchannel channel selection data for sector at fragment-relative `address` into `buf` and stores read length into `length`. Both `address` and `length` is given in sectors.

`self` : | a MIRAGE_Fragment
`address` : | address
`buf` : | buffer to read data into
`length` : | location to store read data length
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure