MirageStream

MirageStream — Interface for I/O streams.

Functions

const gchar * mirage_stream_get_filename ()
gboolean mirage_stream_is_writable ()
gboolean mirage_stream_move_file ()
gssize mirage_stream_read ()
gssize mirage_stream_write ()
gboolean mirage_stream_seek ()
goffset mirage_stream_tell ()
GInputStream * mirage_stream_get_g_input_stream ()

Types and Values

Object Hierarchy

    GInterface
    ╰── MirageStream

Known Implementations

MirageStream is implemented by MirageFileStream and MirageFilterStream.

Includes

#include <mirage-stream.h>

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).

Functions

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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 .

Parameters

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.

Parameters

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.

Parameters

self

a MirageFileStream

 

Returns

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

[transfer full]

Types and Values

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.

Members

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

 

See Also

MirageFileStream, MirageFilterStream