Buffer Routines
[Core Library]

---

Detailed Description

The purpose of this module is to make a plain buffering interface that can be used for read/write buffers throughout the application. The first implementation was done to provide the functionality and the interface and I think it can be optimized under the hood as we go using bucket brigades and/or ring buffering techniques.

Functions
switch_status_t	switch_buffer_create (_In_ switch_memory_pool_t *pool, _Out_ switch_buffer_t **buffer, _In_ switch_size_t max_len)
	Allocate a new switch_buffer.
switch_status_t	switch_buffer_create_dynamic (_Out_ switch_buffer_t **buffer, _In_ switch_size_t blocksize, _In_ switch_size_t start_len, _In_ switch_size_t max_len)
	Allocate a new dynamic switch_buffer.
void	switch_buffer_add_mutex (_In_ switch_buffer_t *buffer, _In_ switch_mutex_t *mutex)
void	switch_buffer_lock (_In_ switch_buffer_t *buffer)
switch_status_t	switch_buffer_trylock (_In_ switch_buffer_t *buffer)
void	switch_buffer_unlock (_In_ switch_buffer_t *buffer)
switch_size_t	switch_buffer_len (_In_ switch_buffer_t *buffer)
	Get the length of a switch_buffer_t.
switch_size_t	switch_buffer_freespace (_In_ switch_buffer_t *buffer)
	Get the freespace of a switch_buffer_t.
switch_size_t	switch_buffer_inuse (_In_ switch_buffer_t *buffer)
	Get the in use amount of a switch_buffer_t.
switch_size_t	switch_buffer_read (_In_ switch_buffer_t *buffer, _In_ void *data, _In_ switch_size_t datalen)
	Read data from a switch_buffer_t up to the ammount of datalen if it is available. Remove read data from buffer.
switch_size_t	switch_buffer_read_loop (_In_ switch_buffer_t *buffer, _In_ void *data, _In_ switch_size_t datalen)
	Read data endlessly from a switch_buffer_t.
void	switch_buffer_set_loops (_In_ switch_buffer_t *buffer, _In_ int32_t loops)
	Assign a number of loops to read.
switch_size_t	switch_buffer_write (_In_ switch_buffer_t *buffer, _In_bytecount_(datalen) const void *data, _In_ switch_size_t datalen)
	Write data into a switch_buffer_t up to the length of datalen.
switch_size_t	switch_buffer_toss (_In_ switch_buffer_t *buffer, _In_ switch_size_t datalen)
	Remove data from the buffer.
void	switch_buffer_zero (_In_ switch_buffer_t *buffer)
	Remove all data from the buffer.
void	switch_buffer_destroy (switch_buffer_t **buffer)
	Destroy the buffer.
switch_size_t	switch_buffer_zwrite (_In_ switch_buffer_t *buffer, _In_bytecount_(datalen) const void *data, _In_ switch_size_t datalen)

---

Function Documentation

void switch_buffer_add_mutex (  _In_ switch_buffer_t *  buffer, _In_ switch_mutex_t *  mutex )

switch_status_t switch_buffer_create (  _In_ switch_memory_pool_t *  pool, _Out_ switch_buffer_t **  buffer, _In_ switch_size_t  max_len )

Allocate a new switch_buffer. Parameters: pool  Pool to allocate the buffer from buffer  returned pointer to the new buffer max_len  length required by the buffer Returns: status

switch_status_t switch_buffer_create_dynamic (  _Out_ switch_buffer_t **  buffer, _In_ switch_size_t  blocksize, _In_ switch_size_t  start_len, _In_ switch_size_t  max_len )

Allocate a new dynamic switch_buffer. Parameters: buffer  returned pointer to the new buffer blocksize  length to realloc by as data is added start_len  ammount of memory to reserve initially max_len  length the buffer is allowed to grow to Returns: status

void switch_buffer_destroy (  switch_buffer_t **  buffer  )

Destroy the buffer. Parameters: buffer  buffer to destroy Note: only neccessary on dynamic buffers (noop on pooled ones) { if (buffer && *buffer) { if ((switch_test_flag((*buffer), SWITCH_BUFFER_FLAG_DYNAMIC))) { switch_safe_free((*buffer)->data); free(*buffer); } *buffer = NULL; } }

switch_size_t switch_buffer_freespace (  _In_ switch_buffer_t *  buffer  )

Get the freespace of a switch_buffer_t. Parameters: buffer  any buffer of type switch_buffer_t Returns: int freespace in the buffer.

switch_size_t switch_buffer_inuse (  _In_ switch_buffer_t *  buffer  )

Get the in use amount of a switch_buffer_t. Parameters: buffer  any buffer of type switch_buffer_t Returns: int ammount of buffer curently in use

switch_size_t switch_buffer_len (  _In_ switch_buffer_t *  buffer  )

Get the length of a switch_buffer_t. Parameters: buffer  any buffer of type switch_buffer_t Returns: int size of the buffer.

void switch_buffer_lock (  _In_ switch_buffer_t *  buffer  )

switch_size_t switch_buffer_read (  _In_ switch_buffer_t *  buffer, _In_ void *  data, _In_ switch_size_t  datalen )

Read data from a switch_buffer_t up to the ammount of datalen if it is available. Remove read data from buffer. Parameters: buffer  any buffer of type switch_buffer_t data  pointer to the read data to be returned datalen  amount of data to be returned Returns: int ammount of data actually read

switch_size_t switch_buffer_read_loop (  _In_ switch_buffer_t *  buffer, _In_ void *  data, _In_ switch_size_t  datalen )

Read data endlessly from a switch_buffer_t. Parameters: buffer  any buffer of type switch_buffer_t data  pointer to the read data to be returned datalen  amount of data to be returned Returns: int ammount of data actually read Note: Once you have read all the data from the buffer it will loop around.

void switch_buffer_set_loops (  _In_ switch_buffer_t *  buffer, _In_ int32_t  loops )

Assign a number of loops to read. Parameters: buffer  any buffer of type switch_buffer_t loops  the number of loops (-1 for infinite)

switch_size_t switch_buffer_toss (  _In_ switch_buffer_t *  buffer, _In_ switch_size_t  datalen )

Remove data from the buffer. Parameters: buffer  any buffer of type switch_buffer_t datalen  amount of data to be removed Returns: int size of buffer, or 0 if unable to toss that much data

switch_status_t switch_buffer_trylock (  _In_ switch_buffer_t *  buffer  )

void switch_buffer_unlock (  _In_ switch_buffer_t *  buffer  )

switch_size_t switch_buffer_write (  _In_ switch_buffer_t *  buffer, _In_bytecount_(datalen) const void *  data, _In_ switch_size_t  datalen )

Write data into a switch_buffer_t up to the length of datalen. Parameters: buffer  any buffer of type switch_buffer_t data  pointer to the data to be written datalen  amount of data to be written Returns: int amount of buffer used after the write, or 0 if no space available

void switch_buffer_zero (  _In_ switch_buffer_t *  buffer  )

Remove all data from the buffer. Parameters: buffer  any buffer of type switch_buffer_t

switch_size_t switch_buffer_zwrite (  _In_ switch_buffer_t *  buffer, _In_bytecount_(datalen) const void *  data, _In_ switch_size_t  datalen )

---