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. |