/*
* Copyright (c) 2014 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_RDWR_H
#define FSTRM_RDWR_H
/**
* \defgroup fstrm_rdwr fstrm_rdwr
*
* `fstrm_rdwr` is an interface for abstracting the process of reading and
* writing data to byte streams. It allows extending the `fstrm` library to
* support reading and writing Frame Streams data to new kinds of byte stream
* transports. (It also allows building mock interfaces for testing the correct
* functioning of the library.)
*
* `fstrm_rdwr` is a low-level interface that is used in conjunction with the
* higher level \ref fstrm_reader and \ref fstrm_writer interfaces. The
* following methods need to be defined for `fstrm_rdwr` implementations:
*
* Method name | Method type | Method description
* ------------ | ----------------------------- | ------------------
* `destroy` | #fstrm_rdwr_destroy_func | Destroys the instance.
* `open` | #fstrm_rdwr_open_func | Opens the stream.
* `close` | #fstrm_rdwr_close_func | Closes the stream.
* `read` | #fstrm_rdwr_read_func | Reads bytes from the stream.
* `write` | #fstrm_rdwr_write_func | Writes bytes to the stream.
*
* The `destroy` method is optional. It cleans up any remaining resources
* associated with the instance.
*
* The `open` method is required. It should perform the actual opening of the
* byte stream and prepare it to read or write data.
*
* The `close` method is required. It should perform the actual closing of the
* byte stream.
*
* If the `fstrm_rdwr` object is to be used in an `fstrm_reader` object, it must
* have a `read` method. If the `fstrm_rdwr` object embedded in an
* `fstrm_reader` object also has a `write` method, the stream will be
* considered bi-directional (that is, it supports both reading and writing) and
* handshaking will be performed. If a `read` method is supplied but a `write`
* method is not, the reader's stream will instead be considered
* uni-directional. See \ref fstrm_reader for details.
*
* If the `fstrm_rdwr` object is to be used in an `fstrm_writer` object, it must
* have a `write` method. If the `fstrm_rdwr` object embedded in an
* `fstrm_writer` object also has a `read` method, the stream will be considered
* bi-directional and shaking will be performed. If a `write` method is supplied
* but a `read` method is not, the writer's stream will instead be considered
* uni-directional. See \ref fstrm_writer for details.
*
* An `fstrm_rdwr` instance is created with a call to `fstrm_rdwr_init()`,
* optionally passing a pointer to some state object associated with the
* instance. This pointer will be passed as the first argument to each of the
* methods described above. Then, the various `fstrm_rdwr_set_*()` functions
* should be used to configure the functions to be used to invoke the methods
* required for the `fstrm_rdwr` object.
*
* @{
*/
/**
* `destroy` method function type. This method is invoked to deallocate any
* per-stream resources used by an `fstrm_rdwr` implementation.
*
* \see fstrm_rdwr_set_destroy()
*
* \param obj
* The `obj` value passed to `fstrm_rdwr_init()`.
*
* \retval #fstrm_res_success
* \retval #fstrm_res_failure
*/
typedef fstrm_res
(*fstrm_rdwr_destroy_func)(void *obj);
/**
* `open` method function type. This method is invoked to open the stream and
* prepare it for reading or writing. For example, if an `fstrm_rdwr`
* implementation is backed by file I/O, this method might be responsible for
* opening a file descriptor.
*
* \see fstrm_rdwr_set_open()
*
* \param obj
* The `obj` value passed to `fstrm_rdwr_init()`.
*
* \retval #fstrm_res_success
* \retval #fstrm_res_failure
*/
typedef fstrm_res
(*fstrm_rdwr_open_func)(void *obj);
/**
* `close` method function type. This method is invoked to close the stream. For
* example, if an `fstrm_rdwr` implementation is backed by file I/O, this method
* might be responsible for closing a file descriptor.
*
* \see fstrm_rdwr_set_close()
*
* \param obj
* The `obj` value passed to `fstrm_rdwr_init()`.
*
* \retval #fstrm_res_success
* \retval #fstrm_res_failure
*/
typedef fstrm_res
(*fstrm_rdwr_close_func)(void *obj);
/**
* `read` method function type. This method is used to read data from a stream.
* It must satisfy the full amount of data requested, unless the stream has
* ended.
*
* \see fstrm_rdwr_set_read()
*
* \param obj
* The `obj` value passed to `fstrm_rdwr_init()`.
* \param data
* The buffer in which to place the data read.
* \param count
* The number of bytes requested.
*
* \retval #fstrm_res_success
* The data was read successfully.
* \retval #fstrm_res_failure
* An unexpected failure occurred.
* \retval #fstrm_res_stop
* The end of the stream has occurred.
*/
typedef fstrm_res
(*fstrm_rdwr_read_func)(void *obj, void *data, size_t count);
/**
* `write` method function type. This method is used to write data to a stream.
* It must perform the full write of all data, unless an error has occurred.
*
* \see fstrm_rdwr_set_write()
*
* \param obj
* The `obj` value passed to `fstrm_rdwr_init()`.
* \param iov
* Array of `struct iovec` objects.
* \param iovcnt
* Number of `struct iovec` objects in `iov`.
*
* \return #fstrm_res_success
* \return #fstrm_res_failure
*/
typedef fstrm_res
(*fstrm_rdwr_write_func)(void *obj, const struct iovec *iov, int iovcnt);
/**
* Initialize a new `fstrm_rdwr` object.
*
* \param obj
* Per-object state.
*
* \return
* `fstrm_rdwr` object.
* \retval
* NULL on failure.
*/
struct fstrm_rdwr *
fstrm_rdwr_init(void *obj);
/**
* Destroy an `fstrm_rdwr` object. This invokes the underlying `destroy` method
* as well.
*
* \param rdwr
* Pointer to an `fstrm_rdwr` object.
*
* \return #fstrm_res_success
* \return #fstrm_res_failure
*/
fstrm_res
fstrm_rdwr_destroy(struct fstrm_rdwr **rdwr);
/**
* Invoke the `open` method on an `fstrm_rdwr` object.
*
* \param rdwr
* The `fstrm_rdwr` object.
*
* \return #fstrm_res_success
* \return #fstrm_res_failure
*/
fstrm_res
fstrm_rdwr_open(struct fstrm_rdwr *rdwr);
/**
* Invoke the `close` method on an `fstrm_rdwr` object.
*
* \param rdwr
* The `fstrm_rdwr` object.
*
* \return #fstrm_res_success
* \return #fstrm_res_failure
*/
fstrm_res
fstrm_rdwr_close(struct fstrm_rdwr *rdwr);
/**
* Invoke the `read` method on an `fstrm_rdwr` object.
*
* \param rdwr
* The `fstrm_rdwr` object.
* \param data
* The buffer in which to place the data read.
* \param count
* The number of bytes to read.
*
* \return #fstrm_res_success
* \return #fstrm_res_failure
* \return #fstrm_res_stop
*/
fstrm_res
fstrm_rdwr_read(struct fstrm_rdwr *rdwr, void *data, size_t count);
/**
* Invoke the `write` method on an `fstrm_rdwr` object.
*
* \param rdwr
* The `fstrm_rdwr` object.
* \param iov
* Array of `struct iovec` objects.
* \param iovcnt
* Number of `struct iovec` objects in `iov`.
*
* \return #fstrm_res_success
* \return #fstrm_res_failure
*/
fstrm_res
fstrm_rdwr_write(struct fstrm_rdwr *rdwr, const struct iovec *iov, int iovcnt);
/**
* Set the `destroy` method for an `fstrm_rdwr` object.
*
* \param rdwr
* The `fstrm_rdwr` object.
* \param fn
* Function to use.
*/
void
fstrm_rdwr_set_destroy(
struct fstrm_rdwr *rdwr,
fstrm_rdwr_destroy_func fn);
/**
* Set the `open` method for an `fstrm_rdwr` object.
*
* \param rdwr
* The `fstrm_rdwr` object.
* \param fn
* Function to use.
*/
void
fstrm_rdwr_set_open(
struct fstrm_rdwr *rdwr,
fstrm_rdwr_open_func fn);
/**
* Set the `close` method for an `fstrm_rdwr` object.
*
* \param rdwr
* The `fstrm_rdwr` object.
* \param fn
* Function to use.
*/
void
fstrm_rdwr_set_close(
struct fstrm_rdwr *rdwr,
fstrm_rdwr_close_func fn);
/**
* Set the `read` method for an `fstrm_rdwr` object.
*
* \param rdwr
* The `fstrm_rdwr` object.
* \param fn
* Function to use.
*/
void
fstrm_rdwr_set_read(
struct fstrm_rdwr *rdwr,
fstrm_rdwr_read_func fn);
/**
* Set the `write` method for an `fstrm_rdwr` object.
*
* \param rdwr
* The `fstrm_rdwr` object.
* \param fn
* Function to use.
*/
void
fstrm_rdwr_set_write(
struct fstrm_rdwr *rdwr,
fstrm_rdwr_write_func fn);
/**@}*/
#endif /* FSTRM_RDWR_H */
Mini Shell