## CamelStream

CamelStream

## Synopsis

    struct              CamelStream;
    CamelStream *       camel_stream_new                    (GIOStream *base_stream);
    GIOStream *         camel_stream_ref_base_stream        (CamelStream *stream);
    void                camel_stream_set_base_stream        (CamelStream *stream,
                                                             GIOStream *base_stream);
    gssize              camel_stream_read                   (CamelStream *stream,
                                                             gchar *buffer,
                                                             gsize n,
                                                             GCancellable *cancellable,
                                                             GError **error);
    gssize              camel_stream_write                  (CamelStream *stream,
                                                             const gchar *buffer,
                                                             gsize n,
                                                             GCancellable *cancellable,
                                                             GError **error);
    gint                camel_stream_flush                  (CamelStream *stream,
                                                             GCancellable *cancellable,
                                                             GError **error);
    gint                camel_stream_close                  (CamelStream *stream,
                                                             GCancellable *cancellable,
                                                             GError **error);
    gboolean            camel_stream_eos                    (CamelStream *stream);
    gssize              camel_stream_write_string           (CamelStream *stream,
                                                             const gchar *string,
                                                             GCancellable *cancellable,
                                                             GError **error);
    gssize              camel_stream_write_to_stream        (CamelStream *stream,
                                                             CamelStream *output_stream,
                                                             GCancellable *cancellable,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----CamelStream
             +----CamelStreamBuffer
             +----CamelStreamFilter
             +----CamelStreamFs
             +----CamelStreamMem
             +----CamelStreamNull
             +----CamelStreamProcess
             +----CamelNNTPStream
             +----CamelPOP3Stream

## Implemented Interfaces

CamelStream implements GSeekable.

## Properties

      "base-stream"              GIOStream*            : Read / Write

## Description

## Details

### struct CamelStream

    struct CamelStream;

### camel_stream_new ()

    CamelStream *       camel_stream_new                    (GIOStream *base_stream);

Creates a CamelStream as a thin wrapper for `base_stream`.

`base_stream` : | a GIOStream
Returns : | a CamelStream

Since 3.12

### camel_stream_ref_base_stream ()

    GIOStream *         camel_stream_ref_base_stream        (CamelStream *stream);

Returns the GIOStream for `stream`. This is only valid if `stream` was created with `camel_stream_new()`. For all other CamelStream subclasses this function returns `NULL`.

The returned GIOStream is referenced for thread-safety and should be unreferenced with `g_object_unref()` when finished with it.

`stream` : | a CamelStream
Returns : | a GIOStream, or `NULL`

Since 3.12

### camel_stream_set_base_stream ()

    void                camel_stream_set_base_stream        (CamelStream *stream,
                                                             GIOStream *base_stream);

Replaces the GIOStream passed to `camel_stream_new()` with `base_stream`. The new `base_stream` should wrap the original GIOStream, such as when adding Transport Layer Security after issuing a STARTTLS command.

`stream` : | a CamelStream
`base_stream` : | a GIOStream

Since 3.12

### camel_stream_read ()

    gssize              camel_stream_read                   (CamelStream *stream,
                                                             gchar *buffer,
                                                             gsize n,
                                                             GCancellable *cancellable,
                                                             GError **error);

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

`stream` : | a CamelStream object.
`buffer` : | output buffer
`n` : | max number of bytes to read.
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | the number of bytes actually read, or `-1` on error and set errno.

### camel_stream_write ()

    gssize              camel_stream_write                  (CamelStream *stream,
                                                             const gchar *buffer,
                                                             gsize n,
                                                             GCancellable *cancellable,
                                                             GError **error);

Attempts to write up to `n` bytes of `buffer` into `stream`.

`stream` : | a CamelStream object
`buffer` : | buffer to write.
`n` : | number of bytes to write
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | the number of bytes written to the stream, or `-1` on error along with setting errno.

### camel_stream_flush ()

    gint                camel_stream_flush                  (CamelStream *stream,
                                                             GCancellable *cancellable,
                                                             GError **error);

Flushes any buffered data to the stream's backing store. Only meaningful for writable streams.

`stream` : | a CamelStream object
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | `0` on success or `-1` on fail along with setting `error`

### camel_stream_close ()

    gint                camel_stream_close                  (CamelStream *stream,
                                                             GCancellable *cancellable,
                                                             GError **error);

Closes the stream.

`stream` : | a CamelStream object
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | `0` on success or `-1` on error.

### camel_stream_eos ()

    gboolean            camel_stream_eos                    (CamelStream *stream);

Tests if there are bytes left to read on the `stream` object.

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

### camel_stream_write_string ()

    gssize              camel_stream_write_string           (CamelStream *stream,
                                                             const gchar *string,
                                                             GCancellable *cancellable,
                                                             GError **error);

Writes the string to the stream.

`stream` : | a CamelStream object
`string` : | a string
`error` : | return location for a GError, or `NULL`
Returns : | the number of characters written or `-1` on error.

### camel_stream_write_to_stream ()

    gssize              camel_stream_write_to_stream        (CamelStream *stream,
                                                             CamelStream *output_stream,
                                                             GCancellable *cancellable,
                                                             GError **error);

Write all of a stream (until eos) into another stream, in a blocking fashion.

`stream` : | source CamelStream object
`output_stream` : | destination CamelStream object
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | `-1` on error, or the number of bytes succesfully copied across streams.

## Property Details

### The `"base-stream"` property

      "base-stream"              GIOStream*            : Read / Write

The base GIOStream.