1 files changed, 94 insertions, 0 deletions
diff --git a/include/serd/output_stream.h b/include/serd/output_stream.h
new file mode 100644
index 00000000..91c04e6b
--- /dev/null
+++ b/include/serd/output_stream.h
@@ -0,0 +1,94 @@
+// Copyright 2011-2022 David Robillard <d@drobilla.net>
+// SPDX-License-Identifier: ISC
+
+#ifndef SERD_OUTPUT_STREAM_H
+#define SERD_OUTPUT_STREAM_H
+
+#include "serd/attributes.h"
+#include "serd/buffer.h"
+#include "serd/status.h"
+#include "serd/stream.h"
+#include "zix/attributes.h"
+
+SERD_BEGIN_DECLS
+
+/**
+   @defgroup serd_output_stream Output Streams
+   @ingroup serd_reading_writing
+   @{
+*/
+
+/**
+   An output stream that receives bytes.
+
+   An output stream is used for writing output as a raw stream of bytes.  It is
+   compatible with standard C `FILE` streams, but allows different functions to
+   be provided for things like writing to a buffer or a socket.
+
+   Output from serd is UTF-8 encoded text.
+*/
+typedef struct {
+  void* ZIX_NULLABLE         stream; ///< Opaque parameter for functions
+  SerdWriteFunc ZIX_NONNULL  write;  ///< Write bytes to output
+  SerdErrorFunc ZIX_NULLABLE error;  ///< Stream error accessor
+  SerdCloseFunc ZIX_NULLABLE close;  ///< Close output
+} SerdOutputStream;
+
+/**
+   Open a stream that writes to a provided function.
+
+   @param write_func Function to write bytes to the stream.
+   @param error_func Function to detect errors in the stream.
+   @param close_func Function to close the stream.
+   @param stream Stream parameter passed to `write_func` and `close_func`.
+   @return An opened output stream, or all zeros on error.
+*/
+SERD_CONST_API SerdOutputStream
+serd_open_output_stream(SerdWriteFunc ZIX_NONNULL  write_func,
+                        SerdErrorFunc ZIX_NULLABLE error_func,
+                        SerdCloseFunc ZIX_NULLABLE close_func,
+                        void* ZIX_NULLABLE         stream);
+
+/**
+   Open a stream that writes to a buffer.
+
+   The `buffer` is owned by the caller, but will be expanded using `realloc` as
+   necessary.  Note that the string in the buffer will not be null terminated
+   until the stream is closed.
+
+   @param buffer Buffer to write output to.
+   @return An opened output stream, or all zeros on error.
+*/
+SERD_CONST_API SerdOutputStream
+serd_open_output_buffer(SerdBuffer* ZIX_NONNULL buffer);
+
+/**
+   Open a stream that writes to a file.
+
+   An arbitrary `FILE*` can be used with serd_open_output_stream() as well,
+   this convenience function opens the file properly for writing with serd, and
+   sets flags for optimized I/O if possible.
+
+   @param path Path of file to open and write to.
+*/
+SERD_API SerdOutputStream
+serd_open_output_file(const char* ZIX_NONNULL path);
+
+/**
+   Close an output stream.
+
+   This will call the close function, and reset the stream internally so that
+   no further writes can be made.  For convenience, this is safe to call on
+   NULL, and safe to call several times on the same output.  Failure is
+   returned in both of those cases.
+*/
+SERD_API SerdStatus
+serd_close_output(SerdOutputStream* ZIX_NULLABLE output);
+
+/**
+   @}
+*/
+
+SERD_END_DECLS
+
+#endif // SERD_OUTPUT_STREAM_H