/*
* Copyright (c) 2014, 2018 by Farsight Security, Inc.
*
* Permission is hereby granted, free of charge, to any person obtaining
* a copy of this software and associated documentation files (the
* "Software"), to deal in the Software without restriction, including
* without limitation the rights to use, copy, modify, merge, publish,
* distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so, subject to
* the following conditions:
*
* The above copyright notice and this permission notice shall be included
* in all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*
*/
#ifndef FSTRM_WRITER_H
#define FSTRM_WRITER_H
/**
* \defgroup fstrm_writer fstrm_writer
*
* `fstrm_writer` is an interface for writing Frame Streams data into a byte
* stream. The underlying byte stream I/O operations are abstracted by the
* \ref fstrm_rdwr interface. Thus, the `fstrm_writer` interface can be used to
* write Frame Streams data to any type of output whose read/write operations
* are wrapped by an `fstrm_rdwr` object.
*
* Some basic `fstrm_writer` implementations are already provided in the `fstrm`
* library. See fstrm_file_writer_init() for an implementation that writes to
* a regular file, fstrm_tcp_writer_init() for an implementation that writes to
* a TCP socket, and fstrm_unix_writer_init() for an implementation that writes
* to a Unix socket.
*
* @{
*/
/**
* Initialize an `fstrm_writer_options` object.
*
* \return
* `fstrm_writer_options` object.
*/
struct fstrm_writer_options *
fstrm_writer_options_init(void);
/**
* Destroy an `fstrm_writer_options` object.
*
* \param wopt
* Pointer to `fstrm_writer_options` object.
*/
void
fstrm_writer_options_destroy(
struct fstrm_writer_options **wopt);
/**
* Add a "Content Type" value to the set of content types that can be negotiated
* by the writer. This function makes a copy of the provided string. This
* function may be called multiple times, in which case multiple "Content Type"
* values will be accepted by the reader.
*
* For uni-directional streams like regular files, the negotiated content type
* will simply be the first content type provided to this function. For
* bi-directional streams like sockets, a handshake occurs and the remote end
* determines which content type should be sent. In the latter case, after the
* writer has been successfully opened with a call to fstrm_writer_open(), the
* fstrm_writer_get_control() function should be called with `type` set to
* `FSTRM_CONTROL_ACCEPT` and the control frame queried in order to determine
* the negotiated content type.
*
* \param wopt
* `fstrm_writer_options` object.
* \param content_type
* The "Content Type" string to copy. Note that this string is not
* NUL-terminated and may contain embedded NULs.
* \param len_content_type
* The number of bytes in `content_type`.
*
* \retval #fstrm_res_success
* The "Content Type" field was successfully added.
* \retval #fstrm_res_failure
* The "Content Type" string is too long.
*/
fstrm_res
fstrm_writer_options_add_content_type(
struct fstrm_writer_options *wopt,
const void *content_type,
size_t len_content_type);
/**
* Initialize a new `fstrm_writer` object based on an underlying `fstrm_rdwr`
* object and an `fstrm_writer_options` object.
*
* The underlying `fstrm_rdwr` object MUST have a `write` method. It MAY
* optionally have a `read` method, in which case the stream will be treated as
* a bi-directional, handshaked stream. Otherwise, if there is no `read` method
* the stream will be treated as a uni-directional stream.
*
* This function is useful for implementing functions that return new types of
* `fstrm_writer` objects, such as fstrm_file_writer_init() and
* fstrm_unix_writer_init().
*
* After a successful call to this function, the ownership of the `fstrm_rdwr`
* object passes from the caller to the `fstrm_writer` object. The caller
* should perform no further calls on the `fstrm_rdwr` object. The `fstrm_rdwr`
* object will be cleaned up on a call to fstrm_writer_destroy().
*
* \param wopt
* `fstrm_writer_options` object. May be NULL, in which case default values
* will be used.
*
* \param rdwr
* Pointer to `fstrm_rdwr` object. Must be non-NULL. The `fstrm_rdwr`
* object must have a `write` method, and may optionally have a `read`
* method.
*
* \return
* `fstrm_writer` object.
* \retval
* NULL on failure.
*/
struct fstrm_writer *
fstrm_writer_init(
const struct fstrm_writer_options *wopt,
struct fstrm_rdwr **rdwr);
/**
* Destroy an `fstrm_writer` object. This implicitly calls fstrm_writer_close()
* if necessary.
*
* \param w
* Pointer to `fstrm_writer` object.
*
* \retval #fstrm_res_success
* \retval #fstrm_res_failure
*/
fstrm_res
fstrm_writer_destroy(struct fstrm_writer **w);
/**
* Open an `fstrm_writer` object and prepare it to write data. For
* bi-directional writer implementations, this performs content type
* negotiation.
*
* This function may fail if there was an underlying problem opening the output
* stream.
*
* \param w
* `fstrm_writer` object.
*
* \retval #fstrm_res_success
* \retval #fstrm_res_failure
*/
fstrm_res
fstrm_writer_open(struct fstrm_writer *w);
/**
* Close an `fstrm_writer` object. Open it has been closed, no data frames may
* subsequently be written.
*
* Calling this function is optional; it may be implicitly invoked by a call to
* fstrm_writer_destroy().
*
* \param w
* `fstrm_writer` object.
*
* \retval #fstrm_res_success
* \retval #fstrm_res_failure
*/
fstrm_res
fstrm_writer_close(struct fstrm_writer *w);
/**
* Write a data frame to an `fstrm_writer` object.
*
* This function implicitly calls fstrm_writer_open() if necessary.
*
* \param w
* `fstrm_writer` object.
* \param[in] data
* Buffer containing the data frame payload.
* \param[in] len_data
* The number of bytes in `data`.
*
* \retval #fstrm_res_success
* The data frame was successfully written.
* \retval #fstrm_res_failure
*/
fstrm_res
fstrm_writer_write(
struct fstrm_writer *w,
const void *data,
size_t len_data);
/**
* Write multiple data frames to an `fstrm_writer` object.
*
* This function implicitly calls fstrm_writer_open() if necessary.
*
* Data frames are passed similarly to the `writev()` system call, with an array
* of `struct iovec` objects describing the data frame payloads and their
* lengths. The complete set of data frames will be written to the output
* stream after a successful call.
*
* \param w
* `fstrm_writer` object.
* \param iov
* Array of `struct iovec` objects.
* \param iovcnt
* Number of `struct iovec` objects in `iov`.
*
* \retval #fstrm_res_success
* The data frames were successfully written.
* \retval #fstrm_res_failure
*/
fstrm_res
fstrm_writer_writev(
struct fstrm_writer *w,
const struct iovec *iov,
int iovcnt);
/**
* Obtain a pointer to an `fstrm_control` object used during processing. Objects
* returned by this function are owned by the `fstrm_reader` object and must not
* be modified by the caller. After a call to fstrm_reader_destroy() these
* pointers will no longer be valid.
*
* For example, with bi-directional streams this function can be used to obtain
* a pointer to the ACCEPT control frame, which can be queried to see which
* "Content Type" was negotiated during the opening of the writer.
*
* This function implicitly calls fstrm_writer_open() if necessary.
*
* \param w
* `fstrm_writer` object.
* \param type
* Which control frame to return.
* \param[out] control
* The `fstrm_control` object.
*
* \retval #fstrm_res_success
* If an `fstrm_control` object was returned.
* \retval #fstrm_res_failure
*/
fstrm_res
fstrm_writer_get_control(
struct fstrm_writer *w,
fstrm_control_type type,
struct fstrm_control **control);
/**@}*/
#endif /* FSTRM_WRITER_H */
Mini Shell