fstrm_rdwr

Detailed Description

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:

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

Typedefs
typedef fstrm_res(*	fstrm_rdwr_destroy_func) (void *obj)
	destroy method function type.
typedef fstrm_res(*	fstrm_rdwr_open_func) (void *obj)
	open method function type.
typedef fstrm_res(*	fstrm_rdwr_close_func) (void *obj)
	close method function type.
typedef fstrm_res(*	fstrm_rdwr_read_func) (void *obj, void *data, size_t count)
	read method function type.
typedef fstrm_res(*	fstrm_rdwr_write_func) (void *obj, const struct iovec *iov, int iovcnt)
	write method function type.

Functions
struct fstrm_rdwr *	fstrm_rdwr_init (void *obj)
	Initialize a new fstrm_rdwr object.
fstrm_res	fstrm_rdwr_destroy (struct fstrm_rdwr **rdwr)
	Destroy an fstrm_rdwr object.
fstrm_res	fstrm_rdwr_open (struct fstrm_rdwr *rdwr)
	Invoke the open method on an fstrm_rdwr object.
fstrm_res	fstrm_rdwr_close (struct fstrm_rdwr *rdwr)
	Invoke the close method on an fstrm_rdwr object.
fstrm_res	fstrm_rdwr_read (struct fstrm_rdwr *rdwr, void *data, size_t count)
	Invoke the read method on an fstrm_rdwr object.
fstrm_res	fstrm_rdwr_write (struct fstrm_rdwr *rdwr, const struct iovec *iov, int iovcnt)
	Invoke the write method on an fstrm_rdwr object.
void	fstrm_rdwr_set_destroy (struct fstrm_rdwr *rdwr, fstrm_rdwr_destroy_func fn)
	Set the destroy method for an fstrm_rdwr object.
void	fstrm_rdwr_set_open (struct fstrm_rdwr *rdwr, fstrm_rdwr_open_func fn)
	Set the open method for an fstrm_rdwr object.
void	fstrm_rdwr_set_close (struct fstrm_rdwr *rdwr, fstrm_rdwr_close_func fn)
	Set the close method for an fstrm_rdwr object.
void	fstrm_rdwr_set_read (struct fstrm_rdwr *rdwr, fstrm_rdwr_read_func fn)
	Set the read method for an fstrm_rdwr object.
void	fstrm_rdwr_set_write (struct fstrm_rdwr *rdwr, fstrm_rdwr_write_func fn)
	Set the write method for an fstrm_rdwr object.

Typedef Documentation

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

obj	The obj value passed to fstrm_rdwr_init().

Return values

fstrm_res_success
fstrm_res_failure

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

obj	The obj value passed to fstrm_rdwr_init().

Return values

fstrm_res_success
fstrm_res_failure

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

obj	The obj value passed to fstrm_rdwr_init().

Return values

fstrm_res_success
fstrm_res_failure

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_res_success	The data was read successfully.
fstrm_res_failure	An unexpected failure occurred.
fstrm_res_stop	The end of the stream has occurred.

fstrm_rdwr_write_func

typedef fstrm_res(* fstrm_rdwr_write_func) (void *obj, const struct iovec *iov, int iovcnt)

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 also

fstrm_rdwr_set_write()

Parameters

obj	The obj value passed to fstrm_rdwr_init().
iov	Array of struct iovec objects.
iovcnt	Number of struct iovec objects in iov.

Returns

fstrm_res_success

fstrm_res_failure

Function Documentation

fstrm_rdwr_init()

struct fstrm_rdwr * fstrm_rdwr_init

(

void *

obj

)

Initialize a new fstrm_rdwr object.

Parameters

obj	Per-object state.

Returns

fstrm_rdwr object.

Return values

NULL	on failure.

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

)

Invoke the open method on an fstrm_rdwr object.

Parameters

rdwr	The fstrm_rdwr object.

Returns

fstrm_res_success

fstrm_res_failure

fstrm_rdwr_close()

fstrm_res fstrm_rdwr_close

(

struct fstrm_rdwr *

rdwr

)

Invoke the close method on an fstrm_rdwr object.

Parameters

rdwr	The fstrm_rdwr object.

Returns

fstrm_res_success

fstrm_res_failure

fstrm_rdwr_read()

fstrm_res fstrm_rdwr_read	(	struct fstrm_rdwr *	rdwr,
		void *	data,
		size_t	count )

Invoke the read method on an fstrm_rdwr object.

Parameters

rdwr	The fstrm_rdwr object.
data	The buffer in which to place the data read.
count	The number of bytes to read.

Returns

fstrm_res_success

fstrm_res_failure

fstrm_res_stop

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()

void fstrm_rdwr_set_destroy	(	struct fstrm_rdwr *	rdwr,
		fstrm_rdwr_destroy_func	fn )

Set the destroy method for an fstrm_rdwr object.

Parameters

rdwr	The fstrm_rdwr object.
fn	Function to use.

fstrm_rdwr_set_open()

void fstrm_rdwr_set_open	(	struct fstrm_rdwr *	rdwr,
		fstrm_rdwr_open_func	fn )

Set the open method for an fstrm_rdwr object.

Parameters

rdwr	The fstrm_rdwr object.
fn	Function to use.

fstrm_rdwr_set_close()

void fstrm_rdwr_set_close	(	struct fstrm_rdwr *	rdwr,
		fstrm_rdwr_close_func	fn )

Set the close method for an fstrm_rdwr object.

Parameters

rdwr	The fstrm_rdwr object.
fn	Function to use.

fstrm_rdwr_set_read()

void fstrm_rdwr_set_read	(	struct fstrm_rdwr *	rdwr,
		fstrm_rdwr_read_func	fn )

Set the read method for an fstrm_rdwr object.

Parameters

rdwr	The fstrm_rdwr object.
fn	Function to use.

fstrm_rdwr_set_write()

void fstrm_rdwr_set_write	(	struct fstrm_rdwr *	rdwr,
		fstrm_rdwr_write_func	fn )

Set the write method for an fstrm_rdwr object.

Parameters

rdwr	The fstrm_rdwr object.
fn	Function to use.