GMimeStream

## GMimeStream GMimeStream — Abstract stream class |

## Synopsis

    enum                GMimeSeekWhence;
                        GMimeStreamIOVector;
                        GMimeStream;
    void                g_mime_stream_construct             (GMimeStream *stream,
                                                             gint64 start,
                                                             gint64 end);
    ssize_t             g_mime_stream_read                  (GMimeStream *stream,
                                                             char *buf,
                                                             size_t len);
    ssize_t             g_mime_stream_write                 (GMimeStream *stream,
                                                             const char *buf,
                                                             size_t len);
    int                 g_mime_stream_flush                 (GMimeStream *stream);
    gint64              g_mime_stream_seek                  (GMimeStream *stream,
                                                             gint64 offset,
                                                             GMimeSeekWhence whence);
    gint64              g_mime_stream_tell                  (GMimeStream *stream);
    int                 g_mime_stream_reset                 (GMimeStream *stream);
    gboolean            g_mime_stream_eos                   (GMimeStream *stream);
    int                 g_mime_stream_close                 (GMimeStream *stream);
    gint64              g_mime_stream_length                (GMimeStream *stream);
    GMimeStream *       g_mime_stream_substream             (GMimeStream *stream,
                                                             gint64 start,
                                                             gint64 end);
    void                g_mime_stream_set_bounds            (GMimeStream *stream,
                                                             gint64 start,
                                                             gint64 end);
    ssize_t             g_mime_stream_write_string          (GMimeStream *stream,
                                                             const char *str);
    ssize_t             g_mime_stream_printf                (GMimeStream *stream,
                                                             const char *fmt,
                                                             ...);
    ssize_t             g_mime_stream_write_to_stream       (GMimeStream *src,
                                                             GMimeStream *dest);
    ssize_t             g_mime_stream_writev                (GMimeStream *stream,
                                                             GMimeStreamIOVector *vector,
                                                             size_t count);

## Object Hierarchy

      GObject
       +----GMimeStream
             +----GMimeStreamBuffer
             +----GMimeStreamCat
             +----GMimeStreamFile
             +----GMimeStreamFilter
             +----GMimeStreamFs
             +----GMimeStreamMem
             +----GMimeStreamMmap
             +----GMimeStreamNull
             +----GMimeStreamPipe

## Description

Streams are the fundamental method for reading and writing data used by GMime. You'll probably notice that the basic API is similar to that of the low-level Unix I/O layer (`read()`, `write()`, `lseek()`, etc) with some additional nicities such as a printf-like function.

## Details

### enum GMimeSeekWhence

    typedef enum {
    	GMIME_STREAM_SEEK_SET = SEEK_SET,
    	GMIME_STREAM_SEEK_CUR = SEEK_CUR,
    	GMIME_STREAM_SEEK_END = SEEK_END
    } GMimeSeekWhence;

Relative seek position.

`GMIME_STREAM_SEEK_SET` | Seek relative to the beginning of the stream.
`GMIME_STREAM_SEEK_CUR` | Seek relative to the current position in the stream.
`GMIME_STREAM_SEEK_END` | Seek relative to the end of the stream.

### GMimeStreamIOVector

    typedef struct {
    	void *data;
    	size_t len;
    } GMimeStreamIOVector;

An I/O vector for use with `g_mime_stream_writev()`.

void *`data`; | data to pass to the I/O function.
size_t `len`; | length of the data, in bytes.

### GMimeStream

    typedef struct _GMimeStream GMimeStream;

Abstract I/O stream class.

### g_mime_stream_construct ()

    void                g_mime_stream_construct             (GMimeStream *stream,
                                                             gint64 start,
                                                             gint64 end);

Initializes a new stream with bounds `start` and `end`.

`stream` : | a GMimeStream
`start` : | start boundary
`end` : | end boundary

### g_mime_stream_read ()

    ssize_t             g_mime_stream_read                  (GMimeStream *stream,
                                                             char *buf,
                                                             size_t len);

Attempts to read up to `len` bytes from `stream` into `buf`.

`stream` : | a GMimeStream
`buf` : | buffer
`len` : | buffer length
Returns : | the number of bytes read or `-1` on fail.

### g_mime_stream_write ()

    ssize_t             g_mime_stream_write                 (GMimeStream *stream,
                                                             const char *buf,
                                                             size_t len);

Attempts to write up to `len` bytes of `buf` to `stream`.

`stream` : | a GMimeStream
`buf` : | buffer
`len` : | buffer length
Returns : | the number of bytes written or `-1` on fail.

### g_mime_stream_flush ()

    int                 g_mime_stream_flush                 (GMimeStream *stream);

Sync's the stream to disk.

`stream` : | a GMimeStream
Returns : | `0` on success or `-1` on fail.

### g_mime_stream_seek ()

    gint64              g_mime_stream_seek                  (GMimeStream *stream,
                                                             gint64 offset,
                                                             GMimeSeekWhence whence);

Repositions the offset of the stream `stream` to the argument `offset` according to the directive `whence` as follows:

GMIME_STREAM_SEEK_SET: Seek `offset` bytes relative to the beginning (bound_start) of the stream.

GMIME_STREAM_SEEK_CUR: Seek `offset` bytes relative to the current offset of the stream.

GMIME_STREAM_SEEK_END: Seek `offset` bytes relative to the end of the stream (bound_end if non-negative).

`stream` : | a GMimeStream
`offset` : | positional offset
`whence` : | seek directive
Returns : | the resultant position on success or `-1` on fail.

### g_mime_stream_tell ()

    gint64              g_mime_stream_tell                  (GMimeStream *stream);

Gets the current offset within the stream.

`stream` : | a GMimeStream
Returns : | the current position within the stream or `-1` on fail.

### g_mime_stream_reset ()

    int                 g_mime_stream_reset                 (GMimeStream *stream);

Resets the stream.

`stream` : | a GMimeStream
Returns : | `0` on success or `-1` on fail.

### g_mime_stream_eos ()

    gboolean            g_mime_stream_eos                   (GMimeStream *stream);

Tests the end-of-stream indicator for `stream`.

`stream` : | a GMimeStream
Returns : | `TRUE` on EOS or `FALSE` otherwise.

### g_mime_stream_close ()

    int                 g_mime_stream_close                 (GMimeStream *stream);

Closes the stream.

`stream` : | a GMimeStream
Returns : | `0` on success or `-1` on fail.

### g_mime_stream_length ()

    gint64              g_mime_stream_length                (GMimeStream *stream);

Gets the length of the stream.

`stream` : | a GMimeStream
Returns : | the length of the stream or `-1` if unknown.

### g_mime_stream_substream ()

    GMimeStream *       g_mime_stream_substream             (GMimeStream *stream,
                                                             gint64 start,
                                                             gint64 end);

Creates a new substream of `stream` with bounds `start` and `end`.

`stream` : | a GMimeStream
`start` : | start boundary
`end` : | end boundary
Returns : | a substream of `stream` with bounds `start` and `end`.

### g_mime_stream_set_bounds ()

    void                g_mime_stream_set_bounds            (GMimeStream *stream,
                                                             gint64 start,
                                                             gint64 end);

Set the bounds on a stream.

`stream` : | a GMimeStream
`start` : | start boundary
`end` : | end boundary

### g_mime_stream_write_string ()

    ssize_t             g_mime_stream_write_string          (GMimeStream *stream,
                                                             const char *str);

Writes `string` to `stream`.

`stream` : | a GMimeStream
`str` : | string to write
Returns : | the number of bytes written or `-1` on fail.

### g_mime_stream_printf ()

    ssize_t             g_mime_stream_printf                (GMimeStream *stream,
                                                             const char *fmt,
                                                             ...);

Write formatted output to a stream.

`stream` : | a GMimeStream
`fmt` : | format
`...` : | arguments
Returns : | the number of bytes written or `-1` on fail.

### g_mime_stream_write_to_stream ()

    ssize_t             g_mime_stream_write_to_stream       (GMimeStream *src,
                                                             GMimeStream *dest);

Attempts to write the source stream to the destination stream.

`src` : | source stream
`dest` : | destination stream
Returns : | the number of bytes written or `-1` on fail.

### g_mime_stream_writev ()

    ssize_t             g_mime_stream_writev                (GMimeStream *stream,
                                                             GMimeStreamIOVector *vector,
                                                             size_t count);

Writes at most `count` blocks described by `vector` to `stream`.

`stream` : | a GMimeStream
`vector` : | a GMimeStreamIOVector
`count` : | number of vector elements
Returns : | the number of bytes written or `-1` on fail.