MIRAGE_Fragment object

MIRAGE_Fragment object — Base object for fragment implementations

Synopsis

#include <mirage.h>

                    MIRAGE_FragmentInfo;
                    MIRAGE_Fragment;
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;
    gchar *version;
    gchar *author;
    
    gchar *interface;
    
    gchar **suffixes;
} MIRAGE_FragmentInfo;

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

interface is a string contraining name of interface the fragment implements; it is provided for debug and informational purposes. suffixes is a NULL-terminated array of strings representing data file suffixes (e.g. ".wav"); some fragment implementations might use it when checking whether they can handle given file. However, this depends on implementation. If fragment is not bound to particular suffix, the list should contain only "N/A".

gchar *id;

fragment ID

gchar *name;

fragment name

gchar *version;

fragment version

gchar *author;

author name

gchar *interface;

interface fragment implements

gchar **suffixes;

list of data file suffixes

MIRAGE_Fragment

typedef struct _MIRAGE_Fragment MIRAGE_Fragment;

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


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.

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.

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.

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.

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.

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.

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