MirageStream: libMirage Reference Manual

## 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

| MirageStream
struct | MirageStreamInterface

## 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