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