ostream.h revision 6cc0546c058f3e6253c6f99727b28dd602712974
c865b0e9c65fd77f7b2ab6f8616d3def5501ecb3Timo Sirainen /* errno for the last operation send/seek operation. cleared before
c865b0e9c65fd77f7b2ab6f8616d3def5501ecb3Timo Sirainen each call. */
568fec5b1e629f25d288b48007485b9aa4a018b1Timo Sirainen /* errno of the last failed send/seek. never cleared. */
568fec5b1e629f25d288b48007485b9aa4a018b1Timo Sirainen /* overflow is set when some of the data given to send()
568fec5b1e629f25d288b48007485b9aa4a018b1Timo Sirainen functions was neither sent nor buffered. It's never unset inside
568fec5b1e629f25d288b48007485b9aa4a018b1Timo Sirainen ostream code. */
62fc0b4f07eb6f18a3bff4b1fccb636e6fae3cf4Timo Sirainen/* Returns 1 if all data is sent (not necessarily flushed), 0 if not.
62fc0b4f07eb6f18a3bff4b1fccb636e6fae3cf4Timo Sirainen Pretty much the only real reason to return 0 is if you wish to send more
62fc0b4f07eb6f18a3bff4b1fccb636e6fae3cf4Timo Sirainen data to client which isn't buffered, eg. o_stream_send_istream(). */
62fc0b4f07eb6f18a3bff4b1fccb636e6fae3cf4Timo Sirainentypedef int stream_flush_callback_t(void *context);
62fc0b4f07eb6f18a3bff4b1fccb636e6fae3cf4Timo Sirainen/* Create new output stream from given file descriptor.
b04e76cbc807707d299055be79500f8ff131da43Timo Sirainen If max_buffer_size is 0, an "optimal" buffer size is used (max 128kB). */
72c4ef3b44c50c662b37bba93b463b0caeb63a4fTimo Siraineno_stream_create_fd(int fd, size_t max_buffer_size, bool autoclose_fd);
0c5854b6891c59c1c3f443569bc823d7db571582Teemu Huovila/* Create an output stream from a regular file which begins at given offset.
62fc0b4f07eb6f18a3bff4b1fccb636e6fae3cf4Timo Sirainen If offset==(uoff_t)-1, the current offset isn't known. */
62fc0b4f07eb6f18a3bff4b1fccb636e6fae3cf4Timo Siraineno_stream_create_fd_file(int fd, uoff_t offset, bool autoclose_fd);
62fc0b4f07eb6f18a3bff4b1fccb636e6fae3cf4Timo Sirainen/* o_stream_close() + o_stream_unref() */
62fc0b4f07eb6f18a3bff4b1fccb636e6fae3cf4Timo Sirainenvoid o_stream_destroy(struct ostream **stream);
62fc0b4f07eb6f18a3bff4b1fccb636e6fae3cf4Timo Sirainen/* Reference counting. References start from 1, so calling o_stream_unref()
62fc0b4f07eb6f18a3bff4b1fccb636e6fae3cf4Timo Sirainen destroys the stream if o_stream_ref() is never used. */
62fc0b4f07eb6f18a3bff4b1fccb636e6fae3cf4Timo Sirainen/* Unreferences the stream and sets stream pointer to NULL. */
f5c0d5cada4da23a167c38426d0c481a3e1d5583Timo Sirainen/* Mark the stream closed. Nothing will be sent after this call. */
f5c0d5cada4da23a167c38426d0c481a3e1d5583Timo Sirainen/* Set IO_WRITE callback. Default will just try to flush the output and
f5c0d5cada4da23a167c38426d0c481a3e1d5583Timo Sirainen finishes when the buffer is empty. */
f5c0d5cada4da23a167c38426d0c481a3e1d5583Timo Sirainenvoid o_stream_set_flush_callback(struct ostream *stream,
62fc0b4f07eb6f18a3bff4b1fccb636e6fae3cf4Timo Sirainen#define o_stream_set_flush_callback(stream, callback, context) \
62fc0b4f07eb6f18a3bff4b1fccb636e6fae3cf4Timo Sirainen CONTEXT_CALLBACK(o_stream_set_flush_callback, stream_flush_callback_t, \
568fec5b1e629f25d288b48007485b9aa4a018b1Timo Sirainenvoid o_stream_unset_flush_callback(struct ostream *stream);
8b1a9a4d63b0abccdf7cb1acb8359d5396dd657bTimo Sirainen/* Change the maximum size for stream's output buffer to grow. */
62fc0b4f07eb6f18a3bff4b1fccb636e6fae3cf4Timo Sirainenvoid o_stream_set_max_buffer_size(struct ostream *stream, size_t max_size);
568fec5b1e629f25d288b48007485b9aa4a018b1Timo Sirainen/* Delays sending as far as possible, writing only full buffers. Also sets
62fc0b4f07eb6f18a3bff4b1fccb636e6fae3cf4Timo Sirainen TCP_CORK on if supported. */
568fec5b1e629f25d288b48007485b9aa4a018b1Timo Sirainen/* Flush the output stream, blocks until everything is sent.
568fec5b1e629f25d288b48007485b9aa4a018b1Timo Sirainen Returns 1 if ok, -1 if error. */
568fec5b1e629f25d288b48007485b9aa4a018b1Timo Sirainen/* Set "flush pending" state of stream. If set, the flush callback is called
568fec5b1e629f25d288b48007485b9aa4a018b1Timo Sirainen when more data is allowed to be sent, even if the buffer itself is empty. */
568fec5b1e629f25d288b48007485b9aa4a018b1Timo Sirainenvoid o_stream_set_flush_pending(struct ostream *stream, bool set);
62fc0b4f07eb6f18a3bff4b1fccb636e6fae3cf4Timo Sirainen/* Returns number of bytes currently in buffer. */
568fec5b1e629f25d288b48007485b9aa4a018b1Timo Sirainensize_t o_stream_get_buffer_used_size(struct ostream *stream);
62fc0b4f07eb6f18a3bff4b1fccb636e6fae3cf4Timo Sirainen/* Seek to specified position from beginning of file. This works only for
62fc0b4f07eb6f18a3bff4b1fccb636e6fae3cf4Timo Sirainen files. Returns 1 if successful, -1 if error. */
568fec5b1e629f25d288b48007485b9aa4a018b1Timo Sirainenint o_stream_seek(struct ostream *stream, uoff_t offset);
8b1a9a4d63b0abccdf7cb1acb8359d5396dd657bTimo Sirainen/* Returns number of bytes sent, -1 = error */
568fec5b1e629f25d288b48007485b9aa4a018b1Timo Sirainenssize_t o_stream_send(struct ostream *stream, const void *data, size_t size);
568fec5b1e629f25d288b48007485b9aa4a018b1Timo Sirainenssize_t o_stream_sendv(struct ostream *stream, const struct const_iovec *iov,
568fec5b1e629f25d288b48007485b9aa4a018b1Timo Sirainen unsigned int iov_count);
568fec5b1e629f25d288b48007485b9aa4a018b1Timo Sirainenssize_t o_stream_send_str(struct ostream *stream, const char *str);
8b1a9a4d63b0abccdf7cb1acb8359d5396dd657bTimo Sirainen/* Send data from input stream. Returns number of bytes sent, or -1 if error.
568fec5b1e629f25d288b48007485b9aa4a018b1Timo Sirainen Note that this function may block if either instream or outstream is
62fc0b4f07eb6f18a3bff4b1fccb636e6fae3cf4Timo Sirainen Also note that this function may not add anything to the output buffer, so
568fec5b1e629f25d288b48007485b9aa4a018b1Timo Sirainen if you want the flush callback to be called when more data can be written,
568fec5b1e629f25d288b48007485b9aa4a018b1Timo Sirainen you'll need to call o_stream_set_flush_pending() manually.
62fc0b4f07eb6f18a3bff4b1fccb636e6fae3cf4Timo Sirainen It's also possible to use this function to copy data within same file
568fec5b1e629f25d288b48007485b9aa4a018b1Timo Sirainen descriptor. If the file must be grown, you have to do it manually before
568fec5b1e629f25d288b48007485b9aa4a018b1Timo Sirainen calling this function. */