MirageStream

MirageStream — Interface for I/O streams.

Synopsis

#include <mirage-stream.h>

                    MirageStream;
struct              MirageStreamInterface;
const gchar *       mirage_stream_get_filename          (MirageStream *self);
gboolean            mirage_stream_is_writable           (MirageStream *self);
gboolean            mirage_stream_move_file             (MirageStream *self,
                                                         const gchar *new_filename,
                                                         GError **error);
gssize              mirage_stream_read                  (MirageStream *self,
                                                         void *buffer,
                                                         gsize count,
                                                         GError **error);
gssize              mirage_stream_write                 (MirageStream *self,
                                                         const void *buffer,
                                                         gsize count,
                                                         GError **error);
gboolean            mirage_stream_seek                  (MirageStream *self,
                                                         goffset offset,
                                                         GSeekType type,
                                                         GError **error);
goffset             mirage_stream_tell                  (MirageStream *self);
GInputStream *      mirage_stream_get_g_input_stream    (MirageStream *self);

Object Hierarchy

  GInterface
   +----MirageStream

Known Implementations

MirageStream is implemented by MirageFileStream and MirageFilterStream.

Description

MirageStream is a basic unit of file access abstraction used in libMirage. It supports basic I/O operations, such as read, write, seek and tell.

Streams in libMirage are designed around the idea of filter stream chains, where several filter streams (MirageFilterStream) can be chained on top of a stream that abstracts direct access to the file (MirageFileStream).

Details

MirageStream

typedef struct _MirageStream MirageStream;

A stream object.


struct MirageStreamInterface

struct MirageStreamInterface {
    GTypeInterface parent_iface;

    /* Interface methods */
    const gchar *(*get_filename) (MirageStream *self);
    gboolean (*is_writable) (MirageStream *self);

    gboolean (*move_file) (MirageStream *self, const gchar *new_filename, GError **error);

    gssize (*read) (MirageStream *self, void *buffer, gsize count, GError **error);
    gssize (*write) (MirageStream *self, const void *buffer, gsize count, GError **error);
    gboolean (*seek) (MirageStream *self, goffset offset, GSeekType type, GError **error);
    goffset (*tell) (MirageStream *self);
};

Provides an interface for implementing I/O streams.

GTypeInterface parent_iface;

the parent interface

get_filename ()

retrieves the filename of the underlying file

is_writable ()

determines whether the stream (chain) is writable

move_file ()

moves the underlying file

read ()

reads from stream

write ()

writes to stream

seek ()

seeks to specified position in stream

tell ()

retrieves current position in stream

mirage_stream_get_filename ()

const gchar *       mirage_stream_get_filename          (MirageStream *self);

Retrieves the name to file on which the stream is opened. If self is a filter stream in the filter stream chain, the filename is obtained from the stream at the bottom of the chain.

self :

a MirageFileStream

Returns :

pointer to a buffer containing the filename. The buffer belongs to the stream object and should not be modified. [transfer none]

mirage_stream_is_writable ()

gboolean            mirage_stream_is_writable           (MirageStream *self);

Queries the stream (chain) for write support. For the stream to be writable, the stream object implementation itself must support write operations, and any stream objects below it in the stream chain must also be writable.

self :

a MirageFileStream

Returns :

TRUE if the stream (chain) is writable, FALSE if it is not.

mirage_stream_move_file ()

gboolean            mirage_stream_move_file             (MirageStream *self,
                                                         const gchar *new_filename,
                                                         GError **error);

Attempts to move the file on top of which the stream (chain) is opened to new_filename. If supported, native move operations are used, otherwise a copy + delete fallback is used.

self :

a MirageFileStream

new_filename :

the new filename. [in]

error :

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

Returns :

TRUE on success, FALSE on failure.

mirage_stream_read ()

gssize              mirage_stream_read                  (MirageStream *self,
                                                         void *buffer,
                                                         gsize count,
                                                         GError **error);

Attempts to read count bytes from stream into the buffer starting at buffer. Will block during the operation.

self :

a MirageFileStream

buffer :

a buffer to read data into. [in]

count :

number of bytes to read from stream. [in]

error :

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

Returns :

number of bytes read, or -1 on error, or 0 on end of file.

mirage_stream_write ()

gssize              mirage_stream_write                 (MirageStream *self,
                                                         const void *buffer,
                                                         gsize count,
                                                         GError **error);

Attempts to write count bytes to stream from the buffer starting at buffer. Will block during the operation.

self :

a MirageFileStream

buffer :

a buffer to write data from. [in]

count :

number of bytes to write to stream. [in]

error :

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

Returns :

number of bytes written, or -1 on error.

mirage_stream_seek ()

gboolean            mirage_stream_seek                  (MirageStream *self,
                                                         goffset offset,
                                                         GSeekType type,
                                                         GError **error);

Seeks in the stream by the given offset, modified by type.

self :

a MirageFileStream

offset :

offset to seek. [in]

type :

seek type. [in]

error :

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

Returns :

TRUE on success, FALSE on failure.

mirage_stream_tell ()

goffset             mirage_stream_tell                  (MirageStream *self);

Retrieves the current position within the stream.

self :

a MirageFileStream

Returns :

the offset from the beginning of the stream.

mirage_stream_get_g_input_stream ()

GInputStream *      mirage_stream_get_g_input_stream    (MirageStream *self);

Constructs and returns a compatibility object inheriting a GInputStream. This is to allow regular GIO stream objects (for example, a GDataInputStream) to be chained on top of our filter stream chain.

self :

a MirageFileStream

Returns :

a GInputStream. The reference should be released using g_object_unref() when no longer needed. [transfer full]

See Also

MirageFileStream, MirageFilterStream