MirageFilterStream

MirageFilterStream — Filter I/O stream object.

Synopsis

#include <mirage-filter-stream.h>

struct              MirageFilterStream;
struct              MirageFilterStreamClass;
struct              MirageFilterStreamInfo;
gboolean            mirage_filter_stream_open           (MirageFilterStream *self,
                                                         MirageStream *stream,
                                                         gboolean writable,
                                                         GError **error);
void                mirage_filter_stream_generate_info  (MirageFilterStream *self,
                                                         const gchar *id,
                                                         const gchar *name,
                                                         gboolean writable,
                                                         gint num_types,
                                                         ...);
const MirageFilterStreamInfo * mirage_filter_stream_get_info
                                                        (MirageFilterStream *self);
MirageStream *      mirage_filter_stream_get_underlying_stream
                                                        (MirageFilterStream *self);
void                mirage_filter_stream_info_copy      (const MirageFilterStreamInfo *info,
                                                         MirageFilterStreamInfo *dest);
void                mirage_filter_stream_info_free      (MirageFilterStreamInfo *info);
goffset             mirage_filter_stream_simplified_get_position
                                                        (MirageFilterStream *self);
void                mirage_filter_stream_simplified_set_stream_length
                                                        (MirageFilterStream *self,
                                                         gsize length);

Object Hierarchy

  GObject
   +----MirageObject
         +----MirageFilterStream

Implemented Interfaces

MirageFilterStream implements MirageContextual and MirageStream.

Description

MirageFilterStream is a basic unit of file access abstraction used in libMirage. It implements MirageStream interface to perform I/O operations.

When opening a file with libMirage, mirage_context_create_input_stream() function should be used. It creates a chain of MirageFilterStream objects on top of a MirageFileStream, and returns the top object on the chain. This allows transparent access to, for example, compressed data stored in the file. Alternatively, you can create a MirageFileStream yourself and open additional MirageFilterStream objects on top of it.

There are two ways to implement a MirageFilterStream. 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 read interface", which provides framework for stream position management and reading logic, and requires that filter stream implements partial_read function. Additionally, it requires that filter stream implementation sets the file stream size using mirage_filter_stream_simplified_set_stream_length() function. In simplified_partial_read, the current position in the stream, which is managed by the framework, can be obtained using mirage_filter_stream_simplified_get_position().

Details

struct MirageFilterStream

struct MirageFilterStream;

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


struct MirageFilterStreamClass

struct MirageFilterStreamClass {
    MirageObjectClass parent_class;

    /* Class members */
    gboolean (*open) (MirageFilterStream *self, MirageStream *stream, gboolean writable, GError **error);

    /* Functions implemented for MirageStream: */
    gssize (*read) (MirageFilterStream *self, void *buffer, gsize count, GError **error);
    gssize (*write) (MirageFilterStream *self, const void *buffer, gsize count, GError **error);
    gboolean (*seek) (MirageFilterStream *self, goffset offset, GSeekType type, GError **error);
    goffset (*tell) (MirageFilterStream *self);

    /* Simplified read/write interface */
    gssize (*simplified_partial_read) (MirageFilterStream *self, void *buffer, gsize count);
    gssize (*simplified_partial_write) (MirageFilterStream *self, const void *buffer, gsize count);
};

The class structure for the MirageFilterStream type.

MirageObjectClass parent_class;

the parent class

open ()

opens a filter stream on top underyling stream

read ()

reads data from stream

write ()

wrties data to stream

seek ()

seeks to a location within stream

tell ()

tells the current location within stream

simplified_partial_read ()

reads a chunk of requested data from stream (part of simplified interface)

simplified_partial_write ()

writes a chunk of requested data to stream (part of simplified interface)

struct MirageFilterStreamInfo

struct MirageFilterStreamInfo {
    gchar *id;
    gchar *name;
    gboolean writable;
    gchar **description;
    gchar **mime_type;
};

A structure containing filter stream information. It can be obtained with call to mirage_filter_stream_get_info().

gchar *id;

filter stream ID

gchar *name;

filter stream name

gboolean writable;

whether filter stream supports write operation

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_filter_stream_open ()

gboolean            mirage_filter_stream_open           (MirageFilterStream *self,
                                                         MirageStream *stream,
                                                         gboolean writable,
                                                         GError **error);

Opens stream on top of provided underlying stream.

self :

a MirageFilterStream

stream :

an underlying stream. [in]

writable :

a flag indicating whether the stream should be opened in read/write mode or not. [in]

error :

location to store error, or NULL. [out][allow-none]

Returns :

TRUE on success, FALSE on failure

mirage_filter_stream_generate_info ()

void                mirage_filter_stream_generate_info  (MirageFilterStream *self,
                                                         const gchar *id,
                                                         const gchar *name,
                                                         gboolean writable,
                                                         gint num_types,
                                                         ...);

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

self :

a MirageFilterStream

id :

filter stream ID. [in]

name :

filter stream name. [in]

writable :

flag indicating whether filter stream supports write operation. [in]

num_types :

number of MIME types. [in]

... :

description and MIME type string pairs, one for each defined type. [in]

mirage_filter_stream_get_info ()

const MirageFilterStreamInfo * mirage_filter_stream_get_info
                                                        (MirageFilterStream *self);

Retrieves filter stream information.

self :

a MirageFilterStream

Returns :

a pointer to filter stream information structure. The structure belongs to object and therefore should not be modified. [transfer none]

mirage_filter_stream_get_underlying_stream ()

MirageStream *      mirage_filter_stream_get_underlying_stream
                                                        (MirageFilterStream *self);

Retrieves filter stream's underlying stream.

self :

a MirageFilterStream

Returns :

a pointer to filter stream's underlying stream. The reference belongs to filter stream and should not be released. [transfer none]

mirage_filter_stream_info_copy ()

void                mirage_filter_stream_info_copy      (const MirageFilterStreamInfo *info,
                                                         MirageFilterStreamInfo *dest);

Copies parser information from info to dest.

info :

a MirageFilterStreamInfo to copy data from. [in]

dest :

a MirageFilterStreamInfo to copy data to. [in]

mirage_filter_stream_info_free ()

void                mirage_filter_stream_info_free      (MirageFilterStreamInfo *info);

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

info :

a MirageFilterStreamInfo to free. [in]

mirage_filter_stream_simplified_get_position ()

goffset             mirage_filter_stream_simplified_get_position
                                                        (MirageFilterStream *self);

Retrieves position in the stream.

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

self :

a MirageFilterStream

Returns :

position in the stream

mirage_filter_stream_simplified_set_stream_length ()

void                mirage_filter_stream_simplified_set_stream_length
                                                        (MirageFilterStream *self,
                                                         gsize length);

Sets size of the stream.

This function is intented for use in filter stream 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 MirageFilterStream

length :

length of the stream. [in]

See Also

MirageStream, MirageFileStream