This header provides a data structure with callbacks for defining data sinks which are consumers of arbitrary byte streams.
A data sink is said to be clog-free if it's write-callback is guaranteed to always cosume all data provided to it. Data sinks derived form cu_dsink may or may not be clog-free. This property may be essential to some callers, and since this is not checked at compile time, it's recommendable that
Any buffer can be turned into a clog-free buffer by stacking a buffer on top of it, as done by cu_dsink_stack_buffer.
| #define CU_DSINK_FN_DISCARD 2 |
Function code for cu_dsink_discard.
| #define CU_DSINK_FN_FINISH 3 |
Function code for cu_dsink_finish.
| #define CU_DSINK_FN_FLUSH 1 |
Function code for cu_dsink_flush.
| #define CU_DSINK_FN_IS_CLOGFREE 0 |
Function code for cu_dsink_is_clogfree, also used by cu_dsink_assert_clogfree. If the sink is guaranteed to be clog-free, the control dispatcher shall indicate this by returning CU_DSINK_ST_SUCCESS as response, otherwise this control need not be implemented.
| #define CU_DSINK_ST_SUCCESS 0 |
Status which may be returned by a dispatches on successful return when no other value is to be returned.
| #define CU_DSINK_ST_UNIMPL ((cu_word_t)-3) |
Status returned by control dispatcher when the requested function is not implemented.
| cu_buffer_t cu_dbufsink_buffer | ( | cu_dbufsink_t | sink | ) |
The underlying buffer of sink.
| void cu_dbufsink_init | ( | cu_dbufsink_t | sink | ) |
Initialise the buffer sink sink.
| size_t cu_dcountsink_count | ( | cu_dcountsink_t | sink | ) |
Returns the number of bytes written to sink.
| void cu_dcountsink_init | ( | cu_dcountsink_t | sink | ) |
Initialise sink.
| void cu_dsink_assert_clogfree | ( | cu_dsink_t | sink | ) |
Control function to check that sink is clog-free. It is recommended to call this once before starting to write to a sink where a clog-free sink is required for correct operation.
| cu_word_t cu_dsink_control | ( | cu_dsink_t | sink, | |
| int | fn, | |||
| ... | ||||
| ) |
Call the control function fn on sink possibly with additional arguments. See the specific control functions below for a safer interface.
| cu_word_t cu_dsink_control_va | ( | cu_dsink_t | sink, | |
| int | fn, | |||
| va_list | va | |||
| ) |
Call the control function fn on sink with any additional arguments wrapped in va.
| void cu_dsink_discard | ( | cu_dsink_t | sink | ) |
Inform sink that no more data will be written, and that the operation is considered failed. This means any buffered data may be discarded and resources closed. Operations on external resources such as file creation or database updates, may or may not be reverted.
| void* cu_dsink_finish | ( | cu_dsink_t | sink | ) |
Inform sink that no more data will be written. This implies flushing any buffered data and closing resources. Some sinks may return constructed data.
| void cu_dsink_flush | ( | cu_dsink_t | sink | ) |
Attempt to write any buffered data and pass down the flush request to sub-sinks.
| void cu_dsink_init | ( | cu_dsink_t | sink, | |
| cu_word_t(*)(cu_dsink_t, int, va_list) | control, | |||
| size_t(*)(cu_dsink_t, void const *, size_t) | write | |||
| ) |
Initialise sink with callbacks control and data. control is a C function which integrates a set of control functions, and write is callback which receives data written to sink.
| cu_bool_t cu_dsink_is_clogfree | ( | cu_dsink_t | sink | ) |
True if sink is clog-free, as reported by the CU_DSINK_FN_IS_CLOGFREE response.
| cu_dsink_t cu_dsink_new_str | ( | void | ) |
Returns a sink on which the call to cu_dsink_finish returns a cu_str_t of the written data. No conversion is done. Writing UTF-8 encoded data gives a text string.
| cu_dsink_t cu_dsink_new_wstring | ( | void | ) |
Returns a sink on which the call to cu_dsink_finish returns a cu_wstring_t of the written data. No conversion is done. Writing cu_wchar_encoding encoded characters gives a text string.
| cu_dsink_t cu_dsink_stack_buffer | ( | cu_dsink_t | subsink | ) |
Creates a clog-free sink of subsink by buffering data.
| size_t cu_dsink_write | ( | cu_dsink_t | sink, | |
| void const * | buf, | |||
| size_t | max_size | |||
| ) |
Tries to write up to max_size bytes starting at buf to the sink, and returns the number of bytes actually consumed. If the sink is clog-free, max_size is returned.