CamelStreamBuffer

CamelStreamBuffer

Synopsis




struct              CamelStreamBuffer;
enum                CamelStreamBufferMode;
CamelStream*        camel_stream_buffer_new             (CamelStream *stream,
                                                         CamelStreamBufferMode mode);
CamelStream*        camel_stream_buffer_new_with_vbuf   (CamelStream *stream,
                                                         CamelStreamBufferMode mode,
                                                         char *buf,
                                                         guint32 size);
int                 camel_stream_buffer_gets            (CamelStreamBuffer *sbf,
                                                         char *buf,
                                                         unsigned int max);
char*               camel_stream_buffer_read_line       (CamelStreamBuffer *sbf);


Description

Details

struct CamelStreamBuffer

struct CamelStreamBuffer {
	CamelStream parent_object;

	/* these are all of course, private */
	CamelStream *stream;

	unsigned char *buf, *ptr, *end;
	int size;

	unsigned char *linebuf;	/* for reading lines at a time */
	int linesize;

	CamelStreamBufferMode mode;
	unsigned int flags;	/* internal flags */
};


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,
                                                         char *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 ()

int                 camel_stream_buffer_gets            (CamelStreamBuffer *sbf,
                                                         char *buf,
                                                         unsigned int max);

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.

Returns :

the number of characters read, or 0 for end of file, and -1 on error.

camel_stream_buffer_read_line ()

char*               camel_stream_buffer_read_line       (CamelStreamBuffer *sbf);

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

Returns :

the line read, which the caller must free when done with, or NULL on eof. If an error occurs, ex will be set.