ostream.h revision 378e6cb162b355d6f103526505bc00b9a78962e7
#ifndef OSTREAM_H
#define OSTREAM_H
#include "ioloop.h"
enum ostream_send_istream_result {
/* All of the istream was successfully sent to ostream. */
/* Caller needs to wait for more input from non-blocking istream. */
/* Caller needs to wait for output to non-blocking ostream.
o_stream_set_flush_pending() is automatically called. */
/* Read from istream failed. See istream->stream_errno. */
/* Write to ostream failed. See ostream->stream_errno. */
};
struct ostream {
/* Number of bytes sent via o_stream_send*() and similar functions.
This is counting the input data. For example with a compressed
ostream this is counting the uncompressed bytes. The compressed
bytes could be counted from the parent ostream's offset.
Seeking to a specified offset only makes sense if there is no
difference between input and output data sizes (e.g. there are no
wrapper ostreams changing the data). */
each call. */
int stream_errno;
/* overflow is set when some of the data given to send()
functions was neither sent nor buffered. It's never unset inside
ostream code. */
unsigned int overflow:1;
/* o_stream_send() writes all the data or returns failure */
unsigned int blocking:1;
unsigned int closed:1;
struct ostream_private *real_stream;
};
/* Returns 1 if all data is sent (not necessarily flushed), 0 if not.
Pretty much the only real reason to return 0 is if you wish to send more
data to client which isn't buffered, eg. o_stream_send_istream(). */
typedef int stream_flush_callback_t(void *context);
typedef void ostream_callback_t(void *context);
/* Create new output stream from given file descriptor.
If max_buffer_size is 0, an "optimal" buffer size is used (max 128kB). */
struct ostream *
/* The fd is set to -1 immediately to avoid accidentally closing it twice. */
/* Create an output stream from a regular file which begins at given offset.
If offset==(uoff_t)-1, the current offset isn't known. */
struct ostream *
/* Create an output stream to a buffer. */
/* Create an output streams that always fails the writes. */
struct ostream *
/* Create an output stream that simply passes through data. This is mainly
useful as a wrapper when combined with destroy callbacks. */
/* Set name (e.g. path) for output stream. */
/* Get output stream's name. Returns "" if stream has no name. */
/* Return file descriptor for stream, or -1 if none is available. */
/* Returns error string for the previous error. */
/* Close this stream (but not its parents) and unreference it. */
/* Reference counting. References start from 1, so calling o_stream_unref()
destroys the stream if o_stream_ref() is never used. */
/* Unreferences the stream and sets stream pointer to NULL. */
/* Call the given callback function when stream is destroyed. */
ATTR_NULL(3);
/* Remove the destroy callback. */
void (*callback)());
/* Mark the stream and all of its parent streams closed. Nothing will be
sent after this call. */
/* Set IO_WRITE callback. Default will just try to flush the output and
finishes when the buffer is empty. */
/* Change the maximum size for stream's output buffer to grow. */
/* Returns the current max. buffer size. */
/* Delays sending as far as possible, writing only full buffers. Also sets
TCP_CORK on if supported. */
/* Try to flush the output stream. Returns 1 if all sent, 0 if not,
-1 if error. */
/* Set "flush pending" state of stream. If set, the flush callback is called
when more data is allowed to be sent, even if the buffer itself is empty. */
/* Returns number of bytes currently in buffer. */
/* Returns number of bytes we can still write without failing. */
/* Seek to specified position from beginning of file. This works only for
files. Returns 1 if successful, -1 if error. */
/* Returns number of bytes sent, -1 = error */
unsigned int iov_count);
/* Send with delayed error handling. o_stream_nfinish() or
o_stream_ignore_last_errors() must be called after these functions before
the stream is destroyed. If any of the data can't be sent due to stream's
buffer getting full, all further nsends are ignores and o_stream_nfinish()
will fail. */
unsigned int iov_count);
/* Marks the stream's error handling as completed. Flushes the stream and
returns -1 if stream->stream_errno is non-zero. Returns failure if any of
the o_stream_nsend*() didn't write all data. */
/* Marks the stream's error handling as completed to avoid i_panic() on
destroy. */
/* If error handling is disabled, the i_panic() on destroy is never called.
This function can be called immediately after the stream is created.
When creating wrapper streams, they copy this behavior from the parent
stream. */
/* Send all of the instream to outstream.
On non-failure instream is skips over all data written to outstream.
This means that the number of bytes written to outstream is always equal to
the number of bytes skipped in instream.
It's also possible to use this function to copy data within same file
descriptor, even if the source and destination overlaps. If the file must
be grown, you have to do it manually before calling this function. */
/* Same as o_stream_send_istream(), but assume that reads and writes will
succeed. If not, o_stream_nfinish() will fail with the correct error
message (even istream's). */
/* Write data to specified offset. Returns 0 if successful, -1 if error. */
/* If there are any I/O loop items associated with the stream, move all of
them to current_ioloop. */
#endif