cu/dsink.h: Generic Data Sink
[Data Sequences]

Data Structures

struct  cu_dsink
struct  cu_dcountsink
struct  cu_dbufsink

Sink API



void cu_dsink_init (cu_dsink_t sink, cu_word_t(*control)(cu_dsink_t, int, va_list), size_t(*write)(cu_dsink_t, void const *, size_t))
size_t cu_dsink_write (cu_dsink_t sink, void const *buf, size_t max_size)
cu_word_t cu_dsink_control_va (cu_dsink_t sink, int fn, va_list va)
cu_word_t cu_dsink_control (cu_dsink_t sink, int fn,...)
cu_bool_t cu_dsink_is_clogfree (cu_dsink_t sink)
void cu_dsink_assert_clogfree (cu_dsink_t sink)
void cu_dsink_flush (cu_dsink_t sink)
void * cu_dsink_finish (cu_dsink_t sink)
void cu_dsink_discard (cu_dsink_t sink)

Sink Implementations



cu_dsink_t cu_dsink_stack_buffer (cu_dsink_t subsink)
cu_dsink_t cu_dsink_new_str (void)
cu_dsink_t cu_dsink_new_wstring (void)
cu_dsink_t cu_dcountsink_to_dsink (cu_dcountsink_t sink)
void cu_dcountsink_init (cu_dcountsink_t sink)
size_t cu_dcountsink_count (cu_dcountsink_t sink)
cu_dsink_t cu_dbufsink_to_dsink (cu_dbufsink_t sink)
void cu_dbufsink_init (cu_dbufsink_t sink)
cu_buffer_t cu_dbufsink_buffer (cu_dbufsink_t sink)

Function Codes



#define CU_DSINK_FN_IS_CLOGFREE   0
#define CU_DSINK_FN_FLUSH   1
#define CU_DSINK_FN_DISCARD   2
#define CU_DSINK_FN_FINISH   3
#define CU_DSINK_FN_DEBUG_DUMP   4

Function Exit Codes



#define CU_DSINK_ST_UNIMPL   ((cu_word_t)-3)
#define CU_DSINK_ST_FAILURE   ((cu_word_t)-1)
#define CU_DSINK_ST_SUCCESS   0

Detailed Description

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 Documentation

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


Function Documentation

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.

Generated 2009-11-23 for culibs-0.25 using Doxygen. Maintained by Petter Urkedal.