## MirageFileFilter MirageFileFilter — File filter object. |

## Synopsis

    #include <mirage-file-filter.h>

    struct              MirageFileFilter;
    struct              MirageFileFilterClass;
    struct              MirageFileFilterInfo;
    gboolean            mirage_file_filter_can_handle_data_format
                                                            (MirageFileFilter *self,
                                                             GError **error);
    void                mirage_file_filter_generate_info    (MirageFileFilter *self,
                                                             const gchar *id,
                                                             const gchar *name,
                                                             gint num_types,
                                                             ...);
    const MirageFileFilterInfo * mirage_file_filter_get_info
                                                            (MirageFileFilter *self);
    goffset             mirage_file_filter_get_position     (MirageFileFilter *self);
    void                mirage_file_filter_info_copy        (const MirageFileFilterInfo *info,
                                                             MirageFileFilterInfo *dest);
    void                mirage_file_filter_info_free        (MirageFileFilterInfo *info);
    void                mirage_file_filter_set_file_size    (MirageFileFilter *self,
                                                             gsize size);

## Object Hierarchy

      GObject
       +----GInputStream
             +----GFilterInputStream
                   +----MirageFileFilter

## Implemented Interfaces

MirageFileFilter implements GSeekable and MirageContextual.

## Description

MirageFileFilter is a basic unit of file access abstraction used in libMirage. It inherits from GFilterInputStream and implements GSeekable interface.

When opening a file with libMirage, `mirage_context_create_file_stream()` function should be used. It creates a chain of MirageFileFilter objects on top of a GFileInputStream, and returns the top object on the chain. This allows transparent access to, for example, compressed data stored in the file.

There are two ways to implement a MirageFileFilter. For full control over the logic for reading from parts and managing position in the stream, use "full interface", which requires implementation of three virtual functions: read, seek and tell. The second option is to use "simplified interface", which provides framework for stream position management and reading logic, and requires that file filter implements partial_read function. Additionally, it requires that file filter implementation sets the file stream size using `mirage_file_filter_set_file_size()` function. In partial_read, the current position in the stream, which is managed by the framework, can be obtained using `mirage_file_filter_get_position()`.

## Details

### struct MirageFileFilter

    struct MirageFileFilter;

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

### struct MirageFileFilterClass

    struct MirageFileFilterClass {
        GFilterInputStreamClass parent_class;

        /* Class members */
        gboolean (*can_handle_data_format) (MirageFileFilter *self, GError **error);

        /* Functions reimplemented from GInputStream: */
        gssize (*read) (MirageFileFilter *self, void *buffer, gsize count, GError **error);

        /* Functions reimplemented from GSeekable: */
        goffset (*tell) (MirageFileFilter *self);
        gboolean (*seek) (MirageFileFilter *self, goffset offset, GSeekType type, GError **error);

        /* Simplified interface */
        gssize (*partial_read) (MirageFileFilter *self, void *buffer, gsize count);
    };

The class structure for the MirageFileFilter type.

GFilterInputStreamClass `parent_class`; | the parent class
`can_handle_data_format` () | checks whether file filter can handle data stored in underyling stream
`read` () | reads data from stream
`tell` () | tells the current location within stream
`seek` () | seeks to a location within stream
`partial_read` () | reads a chunk of requested data from stream

### struct MirageFileFilterInfo

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

A structure containing file filter information. It can be obtained with call to `mirage_file_filter_get_info()`.

gchar *`id`; | file filter ID
gchar *`name`; | file filter 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_file_filter_can_handle_data_format ()

    gboolean            mirage_file_filter_can_handle_data_format
                                                            (MirageFileFilter *self,
                                                             GError **error);

Checks whether file filter can handle data stored in underyling stream.

`self` : | a MirageFileFilter
`error` : | location to store error, or `NULL`. [out][allow-none]
Returns : | `TRUE` if file filter can handle data in underlying stream, `FALSE` if not

### mirage_file_filter_generate_info ()

    void                mirage_file_filter_generate_info    (MirageFileFilter *self,
                                                             const gchar *id,
                                                             const gchar *name,
                                                             gint num_types,
                                                             ...);

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

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

### mirage_file_filter_get_info ()

    const MirageFileFilterInfo * mirage_file_filter_get_info
                                                            (MirageFileFilter *self);

Retrieves file filter information.

`self` : | a MirageFileFilter
Returns : | a pointer to file filter information structure. The structure belongs to object and therefore should not be modified. [transfer none]

### mirage_file_filter_get_position ()

    goffset             mirage_file_filter_get_position     (MirageFileFilter *self);

Retrieves position in the stream.

This function is intented for use in file filter implementations that are based on the simplified interface. It should be used by the implementation's partial_read function to determine position to read from without having to worry about position management and update.

`self` : | a MirageFileFilter
Returns : | position in the stream

### mirage_file_filter_info_copy ()

    void                mirage_file_filter_info_copy        (const MirageFileFilterInfo *info,
                                                             MirageFileFilterInfo *dest);

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

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

### mirage_file_filter_info_free ()

    void                mirage_file_filter_info_free        (MirageFileFilterInfo *info);

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

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

### mirage_file_filter_set_file_size ()

    void                mirage_file_filter_set_file_size    (MirageFileFilter *self,
                                                             gsize size);

Sets size of the stream.

This function is intented for use in file filter implementations that are based on the simplified interface. It should be used by the implementation to set the stream size during stream parsing; the set stream size is then used by the read function that is implemented by the simplified interface.

`self` : | a MirageFileFilter
`size` : | size of the stream. [in]

## See Also

MirageContext