generic-library/libupnp
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Doxygen on membuffer.

Browse Source
This commit is contained in:
Marcelo Roberto Jimenez 2011-01-14 10:26:45 -02:00
parent 9051731a93
commit 4815e52586
2 changed files with 274 additions and 579 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

294
upnp/src/genlib/util/membuffer.c
View File

@ -29,10 +29,12 @@
* *
******************************************************************************/ ******************************************************************************/
/************************************************************************ /*
* Purpose: This file contains functions that operate on memory and * \file
* buffers, allocation, re-allocation, and modification of the memory *
************************************************************************/ * \brief This file contains functions that operate on memory and buffers,
* allocation, re-allocation, and modification of the memory
*/
#include "config.h" #include "config.h"
#include <assert.h> #include <assert.h>
@ -42,29 +44,7 @@
#include "upnp.h" #include "upnp.h"
#include "unixutil.h" #include "unixutil.h"
/************************************************************************ char *str_alloc(const char *str, size_t str_len)
* string *
************************************************************************/
/************************************************************************
* Function : str_alloc
*
* Parameters :
* IN const char* str ; input string object
* IN size_t str_len ; input string length
*
* Description : Allocate memory and copy information from the input
* string to the newly allocated memory.
*
* Return : char* ;
* Pointer to the newly allocated memory.
* NULL if memory cannot be allocated.
*
* Note :
************************************************************************/
char *
str_alloc( IN const char *str,
IN size_t str_len )
{ {
char *s; char *s;
@ -79,32 +59,7 @@ str_alloc( IN const char *str,
return s; return s;
} }
/************************************************************************ int memptr_cmp(memptr * m, const char *s)
* memptr *
************************************************************************/
/************************************************************************
* Function : memptr_cmp
*
* Parameters :
* IN memptr* m ; input memory object
* IN const char* s ; constatnt string for the memory object to be
* compared with
*
* Description : Compares characters of strings passed for number of
* bytes. If equal for the number of bytes, the length of the bytes
* determines which buffer is shorter.
*
* Return : int ;
* < 0 string1 substring less than string2 substring
* 0 string1 substring identical to string2 substring
* > 0 string1 substring greater than string2 substring
*
* Note :
************************************************************************/
int
memptr_cmp( IN memptr * m,
IN const char *s )
{ {
int cmp; int cmp;
@ -119,29 +74,7 @@ memptr_cmp( IN memptr * m,
return cmp; return cmp;
} }
/************************************************************************ int memptr_cmp_nocase(memptr * m, const char *s)
* Function : memptr_cmp_nocase
*
* Parameters :
* IN memptr* m ; input memory object
* IN const char* s ; constatnt string for the memory object to be
* compared with
*
* Description : Compares characters of 2 strings irrespective of the
* case for a specific count of bytes If the character comparison
* is the same the length of the 2 srings determines the shorter
* of the 2 strings.
*
* Return : int ;
* < 0 string1 substring less than string2 substring
* 0 string1 substring identical to string2 substring
* > 0 string1 substring greater than string2 substring
*
* Note :
************************************************************************/
int
memptr_cmp_nocase( IN memptr * m,
IN const char *s )
{ {
int cmp; int cmp;
@ -155,57 +88,25 @@ memptr_cmp_nocase( IN memptr * m,
return cmp; return cmp;
} }
/************************************************************************ /*!
* membuffer * * \brief Initialize the buffer.
************************************************************************/ */
static UPNP_INLINE void membuffer_initialize(
/************************************************************************ /*! [in,out] Buffer to be initialized. */
* Function : membuffer_initialize membuffer *m)
*
* Parameters :
* INOUT membuffer* m ; buffer to be initialized
*
* Description : Initialize the buffer
*
* Return : void ;
*
* Note :
************************************************************************/
static UPNP_INLINE void
membuffer_initialize( INOUT membuffer * m )
{ {
m->buf = NULL; m->buf = NULL;
m->length = 0; m->length = 0;
m->capacity = 0; m->capacity = 0;
} }
/************************************************************************ int membuffer_set_size(membuffer *m, size_t new_length)
* Function : membuffer_set_size
*
* Parameters :
* INOUT membuffer* m ; buffer whose size is to be modified
* IN size_t new_length ; new size to which the buffer will be
* modified
*
* Description : Increases or decreases buffer cap so that at least
* 'new_length' bytes can be stored
*
* Return : int ;
* UPNP_E_SUCCESS - On Success
* UPNP_E_OUTOF_MEMORY - On failure to allocate memory.
*
* Note :
************************************************************************/
int
membuffer_set_size( INOUT membuffer * m,
IN size_t new_length )
{ {
size_t diff; size_t diff;
size_t alloc_len; size_t alloc_len;
char *temp_buf; char *temp_buf;
if( new_length >= m->length ) /* increase length */ if (new_length >= m->length) { /* increase length */
{
/* need more mem? */ /* need more mem? */
if (new_length <= m->capacity) { if (new_length <= m->capacity) {
return 0; /* have enough mem; done */ return 0; /* have enough mem; done */
@ -213,8 +114,8 @@ membuffer_set_size( INOUT membuffer * m,
diff = new_length - m->length; diff = new_length - m->length;
alloc_len = MAXVAL(m->size_inc, diff) + m->capacity; alloc_len = MAXVAL(m->size_inc, diff) + m->capacity;
} else /* decrease length */ } else { /* decrease length */
{
assert(new_length <= m->length); assert(new_length <= m->length);
/* if diff is 0..m->size_inc, don't free */ /* if diff is 0..m->size_inc, don't free */
@ -247,22 +148,7 @@ membuffer_set_size( INOUT membuffer * m,
return 0; return 0;
} }
/************************************************************************ void membuffer_init(membuffer *m)
* Function : membuffer_init
*
* Parameters :
* INOUT membuffer* m ; buffer to be initialized
*
* Description : Wrapper to membuffer_initialize().
* Set the size of the buffer to MEMBUF_DEF_SIZE_INC
* Initializes m->buf to NULL, length=0
*
* Return : void ;
*
* Note :
************************************************************************/
void
membuffer_init( INOUT membuffer * m )
{ {
assert(m != NULL); assert(m != NULL);
@ -270,20 +156,7 @@ membuffer_init( INOUT membuffer * m )
membuffer_initialize(m); membuffer_initialize(m);
} }
/************************************************************************ void membuffer_destroy(membuffer *m)
* Function : membuffer_destroy
*
* Parameters :
* INOUT membuffer* m ; buffer to be destroyed
*
* Description : Free's memory allocated for membuffer* m.
*
* Return : void ;
*
* Note :
************************************************************************/
void
membuffer_destroy( INOUT membuffer * m )
{ {
if (m == NULL) { if (m == NULL) {
return; return;
@ -293,27 +166,7 @@ membuffer_destroy( INOUT membuffer * m )
membuffer_init(m); membuffer_init(m);
} }
/************************************************************************ int membuffer_assign(membuffer *m, const void *buf, size_t buf_len)
* Function : membuffer_assign
*
* Parameters :
* INOUT membuffer* m ; buffer whose memory is to be allocated and
* assigned.
* IN const void* buf ; source buffer whose contents will be copied
* IN size_t buf_len ; length of the source buffer
*
* Description : Allocate memory to membuffer* m and copy the contents
* of the in parameter IN const void* buf.
*
* Return : int ;
* UPNP_E_SUCCESS
* UPNP_E_OUTOF_MEMORY
*
* Note :
************************************************************************/
int membuffer_assign( INOUT membuffer * m,
IN const void *buf,
IN size_t buf_len )
{ {
int return_code; int return_code;
@ -338,78 +191,25 @@ int membuffer_assign( INOUT membuffer * m,
return 0; return 0;
} }
/************************************************************************ int membuffer_assign_str(membuffer *m, const char *c_str)
* Function : membuffer_assign_str
*
* Parameters :
* INOUT membuffer* m ; buffer to be allocated and assigned
* IN const char* c_str ; source buffer whose contents will be
* copied
*
* Description : Wrapper function for membuffer_assign()
*
* Return : int ;
* UPNP_E_SUCCESS
* UPNP_E_OUTOF_MEMORY
*
* Note :
************************************************************************/
int
membuffer_assign_str( INOUT membuffer * m,
IN const char *c_str )
{ {
return membuffer_assign(m, c_str, strlen(c_str)); return membuffer_assign(m, c_str, strlen(c_str));
} }
/************************************************************************ int membuffer_append(membuffer *m, const void *buf, size_t buf_len)
* Function : membuffer_append
*
* Parameters :
* INOUT membuffer* m ; buffer whose memory is to be appended.
* IN const void* buf ; source buffer whose contents will be
* copied
* IN size_t buf_len ; length of the source buffer
*
* Description : Invokes function to appends data from a constant buffer
* to the buffer
*
* Return : int ;
*
* Note :
************************************************************************/
int
membuffer_append( INOUT membuffer * m,
IN const void *buf,
IN size_t buf_len )
{ {
assert(m != NULL); assert(m != NULL);
return membuffer_insert(m, buf, buf_len, m->length); return membuffer_insert(m, buf, buf_len, m->length);
} }
/************************************************************************ int membuffer_append_str(membuffer *m, const char *c_str)
* Function : membuffer_append_str
*
* Parameters :
* INOUT membuffer* m ; buffer whose memory is to be appended.
* IN const char* c_str ; source buffer whose contents will be
* copied
*
* Description : Invokes function to appends data from a constant string
* to the buffer
*
* Return : int ;
*
* Note :
************************************************************************/
int
membuffer_append_str( INOUT membuffer * m,
IN const char *c_str )
{ {
return membuffer_insert(m, c_str, strlen(c_str), m->length); return membuffer_insert(m, c_str, strlen(c_str), m->length);
} }
int membuffer_insert(membuffer *m, const void *buf, size_t buf_len, size_t index) int membuffer_insert(membuffer * m, const void *buf, size_t buf_len,
size_t index)
{ {
int return_code; int return_code;
@ -467,23 +267,7 @@ void membuffer_delete(membuffer *m, size_t index, size_t num_bytes)
m->buf[new_length] = 0; m->buf[new_length] = 0;
} }
/************************************************************************ char *membuffer_detach(membuffer *m)
* Function : membuffer_detach
*
* Parameters :
* INOUT membuffer* m ; buffer to be returned and updated.
*
* Description : Detaches current buffer and returns it. The caller
* must free the returned buffer using free().
* After this call, length becomes 0.
*
* Return : char* ;
* a pointer to the current buffer
*
* Note :
************************************************************************/
char *
membuffer_detach( INOUT membuffer * m )
{ {
char *buf; char *buf;
@ -497,27 +281,7 @@ membuffer_detach( INOUT membuffer * m )
return buf; return buf;
} }
/************************************************************************ void membuffer_attach(membuffer *m, char *new_buf, size_t buf_len)
* Function : membuffer_attach
*
* Parameters :
* INOUT membuffer* m ; buffer to be updated
* IN char* new_buf ; source buffer which will be assigned to the
* buffer to be updated
* IN size_t buf_len ; length of the source buffer
*
* Description : Free existing memory in membuffer and assign the new
* buffer in its place.
*
* Return : void ;
*
* Note : 'new_buf' must be allocted using malloc or realloc so
* that it can be freed using free()
************************************************************************/
void
membuffer_attach( INOUT membuffer * m,
IN char *new_buf,
IN size_t buf_len )
{ {
assert(m != NULL); assert(m != NULL);

365
upnp/src/inc/membuffer.h
View File

@ -43,19 +43,16 @@
#define MAXVAL( a, b ) ( (a) > (b) ? (a) : (b) ) #define MAXVAL( a, b ) ( (a) > (b) ? (a) : (b) )
/*! pointer to a chunk of memory. */ /*! pointer to a chunk of memory. */
typedef struct typedef struct {
{
/*! start of memory (read/write). */ /*! start of memory (read/write). */
char *buf; char *buf;
/*! length of memory (read-only). */ /*! length of memory (read-only). */
size_t length; size_t length;
} memptr; } memptr;
/*! Maintains a block of dynamically allocated memory /*! Maintains a block of dynamically allocated memory
* note: Total length/capacity should not exceed MAX_INT */ * note: Total length/capacity should not exceed MAX_INT */
typedef struct typedef struct {
{
/*! mem buffer; must not write beyond buf[length-1] (read/write). */ /*! mem buffer; must not write beyond buf[length-1] (read/write). */
char *buf; char *buf;
/*! length of buffer (read-only). */ /*! length of buffer (read-only). */
@ -72,190 +69,136 @@ typedef struct
extern "C" { extern "C" {
#endif /* __cplusplus */ #endif /* __cplusplus */
/************************************************************************ /*!
* Function : str_alloc * \brief Allocate memory and copy information from the input string to the
* newly allocated memory.
* *
* Parameters : * \return Pointer to the newly allocated memory.
* IN const char* str ; input string object
* IN size_t str_len ; input string length
*
* Description : Allocate memory and copy information from the input
* string to the newly allocated memory.
*
* Return : char* ;
* Pointer to the newly allocated memory.
* NULL if memory cannot be allocated. * NULL if memory cannot be allocated.
* */
* Note : char *str_alloc(
************************************************************************/ /*! [in] Input string object. */
char *str_alloc( IN const char* str, IN size_t str_len ); const char *str,
/*! [in] Input string length. */
size_t str_len);
/************************************************************************ /*!
* Function : memptr_cmp * \brief Compares characters of strings passed for number of bytes.
* If equal for the number of bytes, the length of the bytes determines
* which buffer is shorter.
* *
* Parameters : * \return
* IN memptr* m ; input memory object * \li < 0 string1 substring less than string2 substring
* IN const char* s ; constatnt string for the memory object to be * \li == 0 string1 substring identical to string2 substring
* compared with * \li > 0 string1 substring greater than string2 substring
* */
* Description : Compares characters of strings passed for number of int memptr_cmp(
* bytes. If equal for the number of bytes, the length of the bytes /*! [in] Input memory object. */
* determines which buffer is shorter. memptr *m,
* /*! [in] Constatnt string for the memory object to be compared with. */
* Return : int ; const char *s);
* < 0 string1 substring less than string2 substring
* 0 string1 substring identical to string2 substring
* > 0 string1 substring greater than string2 substring
*
* Note :
************************************************************************/
int memptr_cmp( IN memptr* m, IN const char* s );
/************************************************************************ /*!
* Function : memptr_cmp_nocase * \brief Compares characters of 2 strings irrespective of the case for a
* specific count of bytes.
* *
* Parameters : * If the character comparison is the same the length of the 2 srings
* IN memptr* m ; input memory object * determines the shorter of the 2 strings.
* IN const char* s ; constatnt string for the memory object to be
* compared with
* *
* Description : Compares characters of 2 strings irrespective of the * \return
* case for a specific count of bytes If the character comparison * \li < 0 string1 substring less than string2 substring
* is the same the length of the 2 srings determines the shorter * \li == 0 string1 substring identical to string2 substring
* of the 2 strings. * \li > 0 string1 substring greater than string2 substring
* */
* Return : int ; int memptr_cmp_nocase(
* < 0 string1 substring less than string2 substring /*! [in] Input memory object. */
* 0 string1 substring identical to string2 substring memptr *m,
* > 0 string1 substring greater than string2 substring /*! [in] Constatnt string for the memory object to be compared with. */
* const char *s);
* Note :
************************************************************************/
int memptr_cmp_nocase( IN memptr* m, IN const char* s );
/*!
* \brief Increases or decreases buffer cap so that at least 'new_length'
* bytes can be stored.
*
* \return
* \li UPNP_E_SUCCESS - On Success
* \li UPNP_E_OUTOF_MEMORY - On failure to allocate memory.
*/
int membuffer_set_size(
/*! [in,out] buffer whose size is to be modified. */
membuffer *m,
/*! [in] new size to which the buffer will be modified. */
size_t new_length);
/************************************************************************ /*!
* Function : membuffer_set_size * \brief Wrapper to membuffer_initialize().
* *
* Parameters : * Set the size of the buffer to MEMBUF_DEF_SIZE_INC and Initializes
* INOUT membuffer* m ; buffer whose size is to be modified * m->buf to NULL, length = 0.
* IN size_t new_length ; new size to which the buffer will be */
* modified void membuffer_init(
* /*! [in,out] Buffer to be initialized. */
* Description : Increases or decreases buffer cap so that at least membuffer *m);
* 'new_length' bytes can be stored
*
* Return : int ;
* UPNP_E_SUCCESS - On Success
* UPNP_E_OUTOF_MEMORY - On failure to allocate memory.
*
* Note :
************************************************************************/
int membuffer_set_size( INOUT membuffer* m, IN size_t new_length );
/************************************************************************ /*!
* Function : membuffer_init * \brief Free's memory allocated for membuffer* m.
* */
* Parameters : void membuffer_destroy(
* INOUT membuffer* m ; buffer to be initialized /*! [in,out] Buffer to be destroyed. */
* membuffer *m);
* Description : Wrapper to membuffer_initialize().
* Set the size of the buffer to MEMBUF_DEF_SIZE_INC
* Initializes m->buf to NULL, length=0
*
* Return : void ;
*
* Note :
************************************************************************/
void membuffer_init( INOUT membuffer* m );
/************************************************************************ /*!
* Function : membuffer_destroy * \brief Allocate memory to membuffer *m and copy the contents of the in
* parameter const void *buf.
* *
* Parameters : * \return
* INOUT membuffer* m ; buffer to be destroyed * \li UPNP_E_SUCCESS
* * \li UPNP_E_OUTOF_MEMORY
* Description : Free's memory allocated for membuffer* m. */
* int membuffer_assign(
* Return : void ; /*! [in,out] Buffer whose memory is to be allocated and assigned. */
* membuffer *m,
* Note : /*! [in] Source buffer whose contents will be copied. */
************************************************************************/ const void *buf,
void membuffer_destroy( INOUT membuffer* m ); /*! [in] Length of the source buffer. */
size_t buf_len);
/*!
* \brief Wrapper function for membuffer_assign().
*
* \return
* \li UPNP_E_SUCCESS
* \li UPNP_E_OUTOF_MEMORY
*/
int membuffer_assign_str(
/*! [in,out] Buffer to be allocated and assigned. */
membuffer *m,
/*! [in] Source buffer whose contents will be copied. */
const char *c_str);
/************************************************************************ /*!
* Function : membuffer_assign * \brief Invokes function to appends data from a constant buffer to the buffer.
* *
* Parameters : * \return int.
* INOUT membuffer* m ; buffer whose memory is to be allocated and */
* assigned. int membuffer_append(
* IN const void* buf ; source buffer whose contents will be copied /*! [in,out] Buffer whose memory is to be appended. */
* IN size_t buf_len ; length of the source buffer membuffer *m,
* /*! [in] Source buffer whose contents will be copied. */
* Description : Allocate memory to membuffer* m and copy the contents const void *buf,
* of the in parameter IN const void* buf. /*! [in] Length of the source buffer. */
* size_t buf_len);
* Return : int ;
* UPNP_E_SUCCESS
* UPNP_E_OUTOF_MEMORY
*
* Note :
************************************************************************/
int membuffer_assign( INOUT membuffer* m, IN const void* buf, IN size_t buf_len );
/************************************************************************ /*!
* Function : membuffer_assign_str * \brief Invokes function to appends data from a constant string to the buffer.
* *
* Parameters : * \return int.
* INOUT membuffer* m ; buffer to be allocated and assigned */
* IN const char* c_str ; source buffer whose contents will be int membuffer_append_str(
* copied /*! [in,out] Buffer whose memory is to be appended. */
* membuffer *m,
* Description : Wrapper function for membuffer_assign() /*! [in] Source buffer whose contents will be copied. */
* const char *c_str);
* Return : int ;
* UPNP_E_SUCCESS
* UPNP_E_OUTOF_MEMORY
*
* Note :
************************************************************************/
int membuffer_assign_str( INOUT membuffer* m, IN const char* c_str );
/************************************************************************
* Function : membuffer_append
*
* Parameters :
* INOUT membuffer* m ; buffer whose memory is to be appended.
* IN const void* buf ; source buffer whose contents will be
* copied
* IN size_t buf_len ; length of the source buffer
*
* Description : Invokes function to appends data from a constant buffer
* to the buffer
*
* Return : int ;
*
* Note :
************************************************************************/
int membuffer_append( INOUT membuffer* m, IN const void* buf, IN size_t buf_len );
/************************************************************************
* Function : membuffer_append_str
*
* Parameters :
* INOUT membuffer* m ; buffer whose memory is to be appended.
* IN const char* c_str ; source buffer whose contents will be
* copied
*
* Description : Invokes function to appends data from a constant string
* to the buffer
*
* Return : int ;
*
* Note :
************************************************************************/
int membuffer_append_str( INOUT membuffer* m, IN const char* c_str );
/*! /*!
* \brief Allocates memory for the new data to be inserted. Does * \brief Allocates memory for the new data to be inserted. Does
@ -265,69 +208,57 @@ int membuffer_append_str( INOUT membuffer* m, IN const char* c_str );
* \return 0 if successful, error code if error. * \return 0 if successful, error code if error.
*/ */
int membuffer_insert( int membuffer_insert(
/* [in,out] Buffer whose memory size is to be increased and appended. */ /*! [in,out] Buffer whose memory size is to be increased and appended. */
membuffer * m, membuffer * m,
/* [in] source buffer whose contents will be copied. */ /*! [in] source buffer whose contents will be copied. */
const void *buf, const void *buf,
/* [in] size of the source buffer. */ /*! [in] size of the source buffer. */
size_t buf_len, size_t buf_len,
/* [in] index to determine the bounds while movinf the data. */ /*! [in] index to determine the bounds while movinf the data. */
size_t index); size_t index);
/*! /*!
* \brief Shrink the size of the buffer depending on the current size of the * \brief Shrink the size of the buffer depending on the current size of the
* bufer and te input parameters. Move contents from the old buffer to the * bufer and te input parameters. Move contents from the old buffer to the
* new sized buffer. * new sized buffer.
*/ */
void membuffer_delete( void membuffer_delete(
/* [in,out] Buffer whose memory size is to be decreased and copied /*! [in,out] Buffer whose memory size is to be decreased and copied
* to the modified location. */ * to the modified location. */
INOUT membuffer *m, membuffer * m,
/* [in] Index to determine bounds while moving data. */ /*! [in] Index to determine bounds while moving data. */
IN size_t index, size_t index,
/* [in] Number of bytes that the data needs to shrink by. */ /*! [in] Number of bytes that the data needs to shrink by. */
IN size_t num_bytes); size_t num_bytes);
/*
* \brief Detaches current buffer and returns it. The caller must free the
* returned buffer using free(). After this call, length becomes 0.
*
* \return A pointer to the current buffer.
*/
char *membuffer_detach(
/*! [in,out] Buffer to be returned and updated. */
membuffer *m);
/************************************************************************ /*
* Function : membuffer_detach * \brief Free existing memory in membuffer and assign the new buffer in its
* place.
* *
* Parameters : * \note 'new_buf' must be allocted using malloc or realloc so that it can be
* INOUT membuffer* m ; buffer to be returned and updated. * freed using free().
* */
* Description : Detaches current buffer and returns it. The caller void membuffer_attach(
* must free the returned buffer using free(). /*! [in,out] Buffer to be updated. */
* After this call, length becomes 0. membuffer *m,
* /*! [in] Source buffer which will be assigned to the buffer to be
* Return : char* ; * updated. */
* a pointer to the current buffer char *new_buf,
* /*! [in] Length of the source buffer. */
* Note : size_t buf_len);
************************************************************************/
char* membuffer_detach( INOUT membuffer* m );
/************************************************************************
* Function : membuffer_attach
*
* Parameters :
* INOUT membuffer* m ; buffer to be updated
* IN char* new_buf ; source buffer which will be assigned to the
* buffer to be updated
* IN size_t buf_len ; length of the source buffer
*
* Description : Free existing memory in membuffer and assign the new
* buffer in its place.
*
* Return : void ;
*
* Note : 'new_buf' must be allocted using malloc or realloc so
* that it can be freed using free()
************************************************************************/
void membuffer_attach( INOUT membuffer* m, IN char* new_buf, IN size_t buf_len );
#ifdef __cplusplus #ifdef __cplusplus
} /* extern "C" */ } /* extern "C" */
#endif /* __cplusplus */ #endif /* __cplusplus */
#endif /* GENLIB_UTIL_H */ #endif /* GENLIB_UTIL_MEMBUFFER_H */