## CamelStreamBuffer

CamelStreamBuffer

## Synopsis

                        CamelStreamBuffer;
    enum                CamelStreamBufferMode;
    CamelStream *       camel_stream_buffer_new             (CamelStream *stream,
                                                             CamelStreamBufferMode mode);
    CamelStream *       camel_stream_buffer_new_with_vbuf   (CamelStream *stream,
                                                             CamelStreamBufferMode mode,
                                                             gchar *buf,
                                                             guint32 size);
    gint                camel_stream_buffer_gets            (CamelStreamBuffer *sbf,
                                                             gchar *buf,
                                                             guint max,
                                                             GCancellable *cancellable,
                                                             GError **error);
    gchar *             camel_stream_buffer_read_line       (CamelStreamBuffer *sbf,
                                                             GCancellable *cancellable,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----CamelObject
             +----CamelStream
                   +----CamelStreamBuffer

## Description

## Details

### CamelStreamBuffer

    typedef struct _CamelStreamBuffer CamelStreamBuffer;

### enum CamelStreamBufferMode

    typedef enum {
    	CAMEL_STREAM_BUFFER_BUFFER = 0,
    	CAMEL_STREAM_BUFFER_NONE,
    	CAMEL_STREAM_BUFFER_READ = 0x00,
    	CAMEL_STREAM_BUFFER_WRITE = 0x80,
    	CAMEL_STREAM_BUFFER_MODE = 0x80
    } CamelStreamBufferMode;

### camel_stream_buffer_new ()

    CamelStream *       camel_stream_buffer_new             (CamelStream *stream,
                                                             CamelStreamBufferMode mode);

Create a new buffered stream of another stream. A default buffer size (1024 bytes), automatically managed will be used for buffering.

See `camel_stream_buffer_new_with_vbuf()` for details on the `mode` parameter.

`stream` : | a CamelStream object to buffer
`mode` : | Operational mode of buffered stream.
Returns : | a newly created buffered stream.

### camel_stream_buffer_new_with_vbuf ()

    CamelStream *       camel_stream_buffer_new_with_vbuf   (CamelStream *stream,
                                                             CamelStreamBufferMode mode,
                                                             gchar *buf,
                                                             guint32 size);

Create a new stream which buffers another stream, `stream`.

The following values are available for `mode`:

CAMEL_STREAM_BUFFER_BUFFER, Buffer the input/output in blocks. CAMEL_STREAM_BUFFER_NEWLINE, Buffer on newlines (for output). CAMEL_STREAM_BUFFER_NONE, Perform no buffering.

Note that currently this is ignored and CAMEL_STREAM_BUFFER_BUFFER is always used.

In addition, one of the following mode options should be or'd together with the buffering mode:

CAMEL_STREAM_BUFFER_WRITE, Buffer in write mode. CAMEL_STREAM_BUFFER_READ, Buffer in read mode.

Buffering can only be done in one direction for any buffer instance.

If `buf` is non-NULL, then use the memory pointed to (for upto `size` bytes) as the buffer for all buffering operations. It is upto the application to free this buffer. If `buf` is NULL, then allocate and manage `size` bytes for all buffering.

`stream` : | An existing stream to buffer.
`mode` : | Mode to buffer in.
`buf` : | Memory to use for buffering.
`size` : | Size of buffer to use.
Returns : | A new stream with buffering applied.

### camel_stream_buffer_gets ()

    gint                camel_stream_buffer_gets            (CamelStreamBuffer *sbf,
                                                             gchar *buf,
                                                             guint max,
                                                             GCancellable *cancellable,
                                                             GError **error);

Read a line of characters up to the next newline character or `max`-1 characters.

If the newline character is encountered, then it will be included in the buffer `buf`. The buffer will be NUL terminated.

`sbf` : | a CamelStreamBuffer object
`buf` : | Memory to write the string to.
`max` : | Maxmimum number of characters to store.
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | the number of characters read, or `0` for end of file, and `-1` on error.

### camel_stream_buffer_read_line ()

    gchar *             camel_stream_buffer_read_line       (CamelStreamBuffer *sbf,
                                                             GCancellable *cancellable,
                                                             GError **error);

This function reads a complete newline-terminated line from the stream and returns it in allocated memory. The trailing newline (and carriage return if any) are not included in the returned string.

`sbf` : | a CamelStreamBuffer object
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | return location for a `GError`, or `NULL`
Returns : | the line read, which the caller must free when done with, or `NULL` on eof. If an error occurs, `error` will be set.