GMimeStream

## GMimeStream GMimeStream — Abstract stream class |

## Synopsis

    enum                GMimeSeekWhence;
                        GMimeStreamIOVector;
                        GMimeStream;
    void                g_mime_stream_construct             (GMimeStream *stream,
                                                             off_t start,
                                                             off_t end);
    void                g_mime_stream_ref                   (GMimeStream *stream);
    void                g_mime_stream_unref                 (GMimeStream *stream);
    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);
    off_t               g_mime_stream_seek                  (GMimeStream *stream,
                                                             off_t offset,
                                                             GMimeSeekWhence whence);
    off_t               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);
    ssize_t             g_mime_stream_length                (GMimeStream *stream);
    GMimeStream*        g_mime_stream_substream             (GMimeStream *stream,
                                                             off_t start,
                                                             off_t end);
    void                g_mime_stream_set_bounds            (GMimeStream *stream,
                                                             off_t start,
                                                             off_t end);
    ssize_t             g_mime_stream_write_string          (GMimeStream *stream,
                                                             const char *string);
    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

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

### g_mime_stream_construct ()

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

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

`stream` : | stream
`start` : | start boundary
`end` : | end boundary

### g_mime_stream_ref ()

    void                g_mime_stream_ref                   (GMimeStream *stream);

### Warning

`g_mime_stream_ref` is deprecated and should not be used in newly-written code.

Ref's a stream.

WARNING: This method is deprecated. Use `g_object_ref()` instead.

`stream` : | stream

### g_mime_stream_unref ()

    void                g_mime_stream_unref                 (GMimeStream *stream);

### Warning

`g_mime_stream_unref` is deprecated and should not be used in newly-written code.

Unref's a stream.

WARNING: This method is deprecated. Use `g_object_unref()` instead.

`stream` : | stream

### 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` : | stream
`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` : | stream
`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` : | stream
Returns : | `0` on success or `-1` on fail.

### g_mime_stream_seek ()

    off_t               g_mime_stream_seek                  (GMimeStream *stream,
                                                             off_t 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` : | stream
`offset` : | positional offset
`whence` : | seek directive
Returns : | the resultant position on success or `-1` on fail.

### g_mime_stream_tell ()

    off_t               g_mime_stream_tell                  (GMimeStream *stream);

Gets the current offset within the stream.

`stream` : | stream
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` : | stream
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` : | stream
Returns : | `TRUE` on EOS or `FALSE` otherwise.

### g_mime_stream_close ()

    int                 g_mime_stream_close                 (GMimeStream *stream);

Closes the stream.

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

### g_mime_stream_length ()

    ssize_t             g_mime_stream_length                (GMimeStream *stream);

Gets the length of the stream.

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

### g_mime_stream_substream ()

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

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

`stream` : | stream
`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,
                                                             off_t start,
                                                             off_t end);

Set the bounds on a stream.

`stream` : | stream
`start` : | start boundary
`end` : | end boundary

### g_mime_stream_write_string ()

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

Writes `string` to `stream`.

`stream` : | stream
`string` : | 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` : | stream
`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 stream `src` to stream `dest`.

`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` : | stream
`vector` : | i/o vector
`count` : | number of vector elements
Returns : | the number of bytes written or `-1` on fail.