fstrm_writer

Detailed Description

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

Functions
struct fstrm_writer_options *	fstrm_writer_options_init (void)
	Initialize an fstrm_writer_options object. More...
void	fstrm_writer_options_destroy (struct fstrm_writer_options **wopt)
	Destroy an fstrm_writer_options object. More...
fstrm_res	fstrm_writer_options_add_content_type (struct fstrm_writer_options *wopt, const void *content_type, size_t len_content_type)
	Add a "Content Type" value to the set of content types that can be negotiated by the writer. More...
struct fstrm_writer *	fstrm_writer_init (const struct fstrm_writer_options *wopt, struct fstrm_rdwr **rdwr)
	Initialize a new fstrm_writer object based on an underlying fstrm_rdwr object and an fstrm_writer_options object. More...
fstrm_res	fstrm_writer_destroy (struct fstrm_writer **w)
	Destroy an fstrm_writer object. More...
fstrm_res	fstrm_writer_open (struct fstrm_writer *w)
	Open an fstrm_writer object and prepare it to write data. More...
fstrm_res	fstrm_writer_close (struct fstrm_writer *w)
	Close an fstrm_writer object. More...
fstrm_res	fstrm_writer_write (struct fstrm_writer *w, const void *data, size_t len_data)
	Write a data frame to an fstrm_writer object. More...
fstrm_res	fstrm_writer_writev (struct fstrm_writer *w, const struct iovec *iov, int iovcnt)
	Write multiple data frames to an fstrm_writer object. More...
fstrm_res	fstrm_writer_get_control (struct fstrm_writer *w, fstrm_control_type type, struct fstrm_control **control)
	Obtain a pointer to an fstrm_control object used during processing. More...

Function Documentation

fstrm_writer_options_init()

struct fstrm_writer_options* fstrm_writer_options_init

(

void

)

Initialize an fstrm_writer_options object.

Returns

fstrm_writer_options object.

fstrm_writer_options_destroy()

void fstrm_writer_options_destroy

(

struct fstrm_writer_options **

wopt

)

Destroy an fstrm_writer_options object.

Parameters

wopt	Pointer to fstrm_writer_options object.

fstrm_writer_options_add_content_type()

fstrm_res fstrm_writer_options_add_content_type	(	struct fstrm_writer_options *	wopt,
		const void *	content_type,
		size_t	len_content_type
	)

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.

Parameters

wopt	fstrm_writer_options object.
content_type	The "Content Type" string to copy. Note that this string is not NUL-terminated and may contain embedded NULs.
len_content_type	The number of bytes in content_type.

Return values

fstrm_res_success	The "Content Type" field was successfully added.
fstrm_res_failure	The "Content Type" string is too long.

fstrm_writer_init()

struct fstrm_writer* fstrm_writer_init	(	const struct fstrm_writer_options *	wopt,
		struct fstrm_rdwr **	rdwr
	)

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

Parameters

wopt	fstrm_writer_options object. May be NULL, in which case default values will be used.
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.

Returns

fstrm_writer object.

Return values

NULL	on failure.

fstrm_writer_destroy()

fstrm_res fstrm_writer_destroy

(

struct fstrm_writer **

w

)

Destroy an fstrm_writer object.

This implicitly calls fstrm_writer_close() if necessary.

Parameters

w	Pointer to fstrm_writer object.

Return values

fstrm_res_success
fstrm_res_failure

fstrm_writer_open()

fstrm_res fstrm_writer_open

(

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.

Parameters

w	fstrm_writer object.

Return values

fstrm_res_success
fstrm_res_failure

fstrm_writer_close()

fstrm_res fstrm_writer_close

(

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

Parameters

w	fstrm_writer object.

Return values

fstrm_res_success
fstrm_res_failure

fstrm_writer_write()

fstrm_res fstrm_writer_write	(	struct fstrm_writer *	w,
		const void *	data,
		size_t	len_data
	)

Write a data frame to an fstrm_writer object.

This function implicitly calls fstrm_writer_open() if necessary.

Parameters

	w	fstrm_writer object.
[in]	data	Buffer containing the data frame payload.
[in]	len_data	The number of bytes in data.

Return values

fstrm_res_success	The data frame was successfully written.
fstrm_res_failure

fstrm_writer_writev()

fstrm_res fstrm_writer_writev	(	struct fstrm_writer *	w,
		const struct iovec *	iov,
		int	iovcnt
	)

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.

Parameters

w	fstrm_writer object.
iov	Array of struct iovec objects.
iovcnt	Number of struct iovec objects in iov.

Return values

fstrm_res_success	The data frames were successfully written.
fstrm_res_failure

fstrm_writer_get_control()

fstrm_res fstrm_writer_get_control	(	struct fstrm_writer *	w,
		fstrm_control_type	type,
		struct fstrm_control **	control
	)

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.

Parameters

	w	fstrm_writer object.
	type	Which control frame to return.
[out]	control	The fstrm_control object.

Return values

fstrm_res_success	If an fstrm_control object was returned.
fstrm_res_failure