libEtPan! API
Prev | Chapter 2. Tools and datatypes | Next

# Buffered I/O

    #include <libetpan/libetpan.h>

    typedef struct _mailstream mailstream;

streams are objects where we can read data from and write data to. They are not seekable. That can be for example a pipe or a network stream.

    mailstream * mailstream_new(mailstream_low * low, size_t buffer_size);

    int mailstream_close(mailstream * s);

mailstream_new() creates a new stream stream with the low-level (see the Section called non-buffered I/O) stream and a given buffer size.

mailstream_close() closes the stream. This function will be in charge to free the mailstream_low structure.

    ssize_t mailstream_write(mailstream * s, void * buf, size_t count);

    int mailstream_flush(mailstream * s);

    ssize_t mailstream_read(mailstream * s, void * buf, size_t count);

    ssize_t mailstream_feed_read_buffer(mailstream * s);

mailstream_write() writes a buffer to the given stream. This write operation will be buffered.

mailstream_flush() will force a write of all buffered data for a given stream.

mailstream_read() reads data from the stream to the given buffer.

mailstream_feed_read_buffer() this function will just fill the buffer for reading.

    mailstream_low * mailstream_get_low(mailstream * s);

    void mailstream_set_low(mailstream * s, mailstream_low * low);

mailstream_get_low() returns the low-level stream of the given stream.

mailstream_set_low() changes the low-level of the given stream. Useful, for example, when a stream change from clear stream to SSL stream.

    char * mailstream_read_line(mailstream * stream, MMAPString * line);

    char * mailstream_read_line_append(mailstream * stream, MMAPString * line);

    char * mailstream_read_line_remove_eol(mailstream * stream, MMAPString * line);

    char * mailstream_read_multiline(mailstream * s, size_t size,
        MMAPString * stream_buffer,
        MMAPString * multiline_buffer,
        size_t progr_rate,
        progress_function * progr_fun);

mailstream_read_line() reads an entire line from the buffer and store it into the given string. returns NULL on error, the corresponding array of char is returned otherwise.

mailstream_read_line_append() reads an entire line from the buffer and appends it to the given string. returns NULL on error, the array of char corresponding to the entire buffer is returned otherwise.

mailstream_read_line_remove_eol() reads an entire line from the buffer and store it into the given string. All CR LF are removed. returns NULL on error, the corresponding array of char is returned otherwise.

mailstream_read_multiline() reads a multiline data (several lines, the data are ended with a single period '.') from the given stream and store it into the given multiline buffer (multiline_buffer). progr_rate should be 0 and progr_fun NULL (deprecated things). stream_buffer is a buffer used for internal work of the function. size should be 0 (deprecated things).

    int mailstream_is_end_multiline(char * line);

returns 1 if the line is an end of multiline data (a single period '.', eventually with CR and/or LF). 0 is returned otherwise.

    int mailstream_send_data(mailstream * s, char * message,
        size_t size,
        size_t progr_rate,
        progress_function * progr_fun);

sends multiline data to the given stream. size is the size of the data. progr_rate and progr_fun are deprecated. progr_rate must be 0, progr_fun must be NULL.

## socket stream

    mailstream * mailstream_socket_open(int fd);

mailstream_socket_open() will open a clear-text socket.

## TLS stream

    mailstream * mailstream_ssl_open(int fd);

mailstream_ssl_open() will open a TLS/SSL socket.

    int mailstream_ssl_set_server_name(struct mailstream_ssl_context * ssl_context,
        char * hostname)

mailstream_ssl_set_server_name() allows the client to enable the use of the Server Name Indication TLS extension upon opening a TLS stream, by providing the domain name to be indicated to server as the desired destination. ssl_context is the context pointer passed to the client-supplied callback function by mailstream_ssl_open_with_callback() etc. Note that hostname must be a domain name, not a string representation of an IP address.

Prev | Home | Next
Hash table | Up | non-buffered I/O