CamelStream: Camel Reference Manual

## CamelStream CamelStream |

## Functions

CamelStream * | camel_stream_new ()
GIOStream * | camel_stream_ref_base_stream ()
void | camel_stream_set_base_stream ()
gssize | camel_stream_read ()
gssize | camel_stream_write ()
gint | camel_stream_flush ()
gint | camel_stream_close ()
gboolean | camel_stream_eos ()
gssize | camel_stream_write_string ()
gssize | camel_stream_write_to_stream ()

## Properties

GIOStream * | base-stream | Read / Write

## Object Hierarchy

        GObject
        ╰── CamelStream
            ├── CamelNNTPStream
            ├── CamelPOP3Stream
            ├── CamelStreamBuffer
            ├── CamelStreamFilter
            ├── CamelStreamFs
            ├── CamelStreamMem
            ├── CamelStreamNull
            ╰── CamelStreamProcess

## Description

## Functions

### camel_stream_new ()

    CamelStream *
    camel_stream_new (GIOStream *base_stream);

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

#### Parameters

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.

#### Parameters

stream | a CamelStream |

#### Returns

a GIOStream, or `NULL`.

[transfer full][nullable]

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.

#### Parameters

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 `n` bytes from `stream` into `buffer` .

#### Parameters

stream | a CamelStream object. |
buffer | output buffer. | [array length=n][type gchar]
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` .

#### Parameters

stream | a CamelStream object |
buffer | buffer to write. | [array length=n][type gchar]
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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

stream | a CamelStream object |
string | a string |
cancellable | optional GCancellable object, or `NULL` |
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.

#### Parameters

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 *

The base GIOStream.

Owner: CamelStream

Flags: Read / Write