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 fstrm_reader and fstrm_writer interfaces. The following methods need to be defined for fstrm_rdwr
implementations:
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 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 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.
◆ fstrm_rdwr_destroy_func
typedef fstrm_res(* fstrm_rdwr_destroy_func) (void *obj) |
destroy
method function type.
This method is invoked to deallocate any per-stream resources used by an fstrm_rdwr
implementation.
- See also
- fstrm_rdwr_set_destroy()
- Parameters
-
- Return values
-
◆ fstrm_rdwr_open_func
typedef fstrm_res(* fstrm_rdwr_open_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 also
- fstrm_rdwr_set_open()
- Parameters
-
- Return values
-
◆ fstrm_rdwr_close_func
typedef fstrm_res(* fstrm_rdwr_close_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 also
- fstrm_rdwr_set_close()
- Parameters
-
- Return values
-
◆ fstrm_rdwr_read_func
typedef fstrm_res(* fstrm_rdwr_read_func) (void *obj, void *data, size_t count) |
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 also
- fstrm_rdwr_set_read()
- Parameters
-
obj | The obj value passed to fstrm_rdwr_init() . |
data | The buffer in which to place the data read. |
count | The number of bytes requested. |
- Return values
-
◆ fstrm_rdwr_write_func
typedef fstrm_res(* fstrm_rdwr_write_func) (void *obj, const struct iovec *iov, int iovcnt) |
◆ fstrm_rdwr_init()
struct fstrm_rdwr* fstrm_rdwr_init |
( |
void * |
obj | ) |
|
Initialize a new fstrm_rdwr
object.
- Parameters
-
- Returns
fstrm_rdwr
object.
- Return values
-
◆ fstrm_rdwr_destroy()
fstrm_res fstrm_rdwr_destroy |
( |
struct fstrm_rdwr ** |
rdwr | ) |
|
Destroy an fstrm_rdwr
object.
This invokes the underlying destroy
method as well.
- Parameters
-
rdwr | Pointer to an fstrm_rdwr object. |
- Returns
- fstrm_res_success
-
fstrm_res_failure
◆ fstrm_rdwr_open()
fstrm_res fstrm_rdwr_open |
( |
struct fstrm_rdwr * |
rdwr | ) |
|
◆ fstrm_rdwr_close()
fstrm_res fstrm_rdwr_close |
( |
struct fstrm_rdwr * |
rdwr | ) |
|
◆ fstrm_rdwr_read()
fstrm_res fstrm_rdwr_read |
( |
struct fstrm_rdwr * |
rdwr, |
|
|
void * |
data, |
|
|
size_t |
count |
|
) |
| |
◆ fstrm_rdwr_write()
fstrm_res fstrm_rdwr_write |
( |
struct fstrm_rdwr * |
rdwr, |
|
|
const struct iovec * |
iov, |
|
|
int |
iovcnt |
|
) |
| |
Invoke the write
method on an fstrm_rdwr
object.
- Parameters
-
rdwr | The fstrm_rdwr object. |
iov | Array of struct iovec objects. |
iovcnt | Number of struct iovec objects in iov . |
- Returns
- fstrm_res_success
-
fstrm_res_failure
◆ fstrm_rdwr_set_destroy()
Set the destroy
method for an fstrm_rdwr
object.
- Parameters
-
rdwr | The fstrm_rdwr object. |
fn | Function to use. |
◆ fstrm_rdwr_set_open()
Set the open
method for an fstrm_rdwr
object.
- Parameters
-
rdwr | The fstrm_rdwr object. |
fn | Function to use. |
◆ fstrm_rdwr_set_close()
Set the close
method for an fstrm_rdwr
object.
- Parameters
-
rdwr | The fstrm_rdwr object. |
fn | Function to use. |
◆ fstrm_rdwr_set_read()
Set the read
method for an fstrm_rdwr
object.
- Parameters
-
rdwr | The fstrm_rdwr object. |
fn | Function to use. |
◆ fstrm_rdwr_set_write()
Set the write
method for an fstrm_rdwr
object.
- Parameters
-
rdwr | The fstrm_rdwr object. |
fn | Function to use. |