/*
 * libwbxml, the WBXML Library.
 * Copyright (C) 2002-2005 Aymerick Jehanne <aymerick@jehanne.org>
 * 
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 * 
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 * 
 * LGPL v2.1: http://www.gnu.org/copyleft/lesser.txt
 * 
 * Contact: libwbxml@aymerick.com
 * Home: http://libwbxml.aymerick.com
 */
 
/**
 * @file wbxml_buffers.h 
 * @ingroup wbxml_buffers
 *
 * @author Aymerick Jehanne <libwbxml@aymerick.com>
 * @date 02/03/12
 *
 * @brief Generic Buffers Functions
 *
 * @note Original idea: Kannel Project (http://kannel.3glab.org/)
 */

#ifndef WBXML_BUFFERS_H
#define WBXML_BUFFERS_H

#include <stdio.h>


#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */

/**
 * @brief WBXML Generic Buffer
 */
typedef struct WBXMLBuffer_s WBXMLBuffer;


/** @addtogroup wbxml_buffers  
 *  @{ 
 */

/**
 * @brief Create a Buffer
 * @param data The initial data for buffer
 * @param len Size of data
 * @param malloc_block Size of malloc blocks (tune this parameter to avoid too many rallocations)
 * @return The newly created Buffer, or NULL if not enought memory
 * @warning Do NOT use this function directly, use wbxml_buffer_create() macro instead
 */
WBXML_DECLARE(WBXMLBuffer *) wbxml_buffer_create_real(const WB_UTINY *data, WB_ULONG len, WB_ULONG malloc_block);

/** Wrapper around wbxml_buffer_create_real() to track Memory */
#define wbxml_buffer_create(a,b,c) \
  wbxml_mem_cleam(wbxml_buffer_create_real((const WB_UTINY *)a,b,c))

/** Wrapper around wbxml_buffer_create() when creating buffer with a C String (NULL Terminated) */
#define wbxml_buffer_create_from_cstr(a) \
  wbxml_buffer_create((const WB_UTINY *)a,WBXML_STRLEN(a),WBXML_STRLEN(a))

/**
 * @brief Create a static Buffer
 * @param data Buffer data
 * @param len  Data lenght
 * @return The newly created Buffer, or NULL if not enough memory
 * @note A static buffer can't be modified, so do not use functions dedeicated to dynamic buffers
 *       as wbxml_buffer_insert() or wbxml_buffer_append()
 * @warning Do NOT use this function directly, use wbxml_buffer_sta_create() macro instead
 */
WBXML_DECLARE(WBXMLBuffer *) wbxml_buffer_sta_create_real(const WB_UTINY *data, WB_ULONG len);

/** Wrapper around wbxml_buffer_sta_create_real() to track Memory */
#define wbxml_buffer_sta_create(a,b) \
  wbxml_mem_cleam(wbxml_buffer_sta_create_real((const WB_UTINY *)a,b))

/** Wrapper around wbxml_buffer_sta_create() when creating static buffer with a C String (NULL Terminated) */
#define wbxml_buffer_sta_create_from_cstr(a) \
  wbxml_buffer_sta_create((const WB_UTINY *)a,WBXML_STRLEN(a))

/**
 * @brief Destroy a Buffer
 * @param buff The Buffer to destroy
 */
WBXML_DECLARE(void) wbxml_buffer_destroy(WBXMLBuffer *buff);

/**
 * @brief Destroy a Buffer (used for wbxml_list_destroy())
 * @param buff The Buffer to destroy
 */
WBXML_DECLARE_NONSTD(void) wbxml_buffer_destroy_item(void *buff);

/**
 * Duplicate a Buffer
 *
 * Even if a static buffer is provided, the duplicated buffer is
 * a dynamic buffer.
 *
 * @param buff The Buffer to duplicate
 * @return The duplicated buffer, or NULL if not enough memory
 */
WBXML_DECLARE(WBXMLBuffer *) wbxml_buffer_duplicate(WBXMLBuffer *buff);

/**
 * @brief Get data length of a buffer
 * @param buff The Buffer
 * @return The Buffer data length
 */
WBXML_DECLARE(WB_ULONG) wbxml_buffer_len(WBXMLBuffer *buff);

/**
 * @brief Get a byte from a Buffer
 * @param buff The Buffer
 * @param pos Byte position in buffer
 * @param result The resulting char
 * @return TRUE if OK, or FALSE if error
 */
WBXML_DECLARE(WB_BOOL) wbxml_buffer_get_char(WBXMLBuffer *buff, WB_ULONG pos, WB_UTINY *result);

/**
 * @brief Set a byte in a dynamic Buffer
 * @param buff The Buffer
 * @param pos Byte position in buffer
 * @param ch The character to set
 */
WBXML_DECLARE(void) wbxml_buffer_set_char(WBXMLBuffer *buff, WB_ULONG pos, WB_UTINY ch);

/**
 * @brief Get pointer to internal buffer data
 * @param buff The Buffer
 * @return Pointer to buffer data, or "" if buffer is NULL or empty
 */
WBXML_DECLARE(WB_UTINY *) wbxml_buffer_get_cstr(WBXMLBuffer *buff);

/**
 * @brief Insert a Buffer into a dynamic Buffer
 * @param to The Buffer to modify
 * @param buff The Buffer to insert
 * @param pos The position of insertion in 'to'
 * @return TRUE if data inserted, FALSE otherwise
 */
WBXML_DECLARE(WB_BOOL) wbxml_buffer_insert(WBXMLBuffer *to, WBXMLBuffer *buff, WB_ULONG pos);

/**
 * @brief Insert a C String into a dynamic Buffer
 * @param to The Buffer to modify
 * @param str The BC String to insert
 * @param pos The position of insertion in 'to'
 * @return TRUE if data inserted, FALSE otherwise
 */
WBXML_DECLARE(WB_BOOL) wbxml_buffer_insert_cstr(WBXMLBuffer *to, WB_UTINY *str, WB_ULONG pos);

/**
 * @brief Append a Buffer to a dynamic Buffer
 * @param dest The destination Buffer
 * @param buff The Buffer to append
 * @return TRUE if buffer appended, FALSE otherwise
 */
WBXML_DECLARE(WB_BOOL) wbxml_buffer_append(WBXMLBuffer *dest, WBXMLBuffer *buff);


/**
 * @brief Append data to a dynamic Buffer
 * @param buff The Buffer
 * @param data Data to append
 * @param len Data length
 * @return TRUE if data appended, FALSE otherwise
 */
WBXML_DECLARE(WB_BOOL) wbxml_buffer_append_data_real(WBXMLBuffer *buff, const WB_UTINY *data, WB_ULONG len);

/** Wrapper around wbxml_buffer_append_data_real() to avoid Casts in code */
#define wbxml_buffer_append_data(a,b,c) wbxml_buffer_append_data_real(a,(const WB_UTINY *)b,c)

/**
 * @brief Append a C String (NULL terminated) to a dynamic Buffer
 * @param buff The Buffer
 * @param data String to append
 * @return TRUE if data appended, FALSE otherwise
 */
WBXML_DECLARE(WB_BOOL) wbxml_buffer_append_cstr_real(WBXMLBuffer *buff, const WB_UTINY *data);

/** Wrapper around wbxml_buffer_append_cstr_real() to avoid Casts in code */
#define wbxml_buffer_append_cstr(a,b) wbxml_buffer_append_cstr_real(a,(const WB_UTINY *)b)


/**
 * @brief Append a byte to a dynamic Buffer
 * @param buff The Buffer
 * @param ch Byte to append
 * @return TRUE if byte appended, FALSE otherwise
 */
WBXML_DECLARE(WB_BOOL) wbxml_buffer_append_char(WBXMLBuffer *buff, WB_UTINY ch);

/**
 * @brief Append a Multibyte Integer to a dynamic Buffer
 * @param buff The Buffer
 * @param value The value to append
 * @return TRUE if value appended, FALSE otherwise
 */
WBXML_DECLARE(WB_BOOL) wbxml_buffer_append_mb_uint_32(WBXMLBuffer *buff, WB_ULONG value);

/**
 * @brief Delete a range of Bytes in a  dynamicBuffer
 * @param buff The Buffer
 * @param pos Position where to start deletion
 * @param len Number of bytes to delete
 */
WBXML_DECLARE(void) wbxml_buffer_delete(WBXMLBuffer *buff, WB_ULONG pos, WB_ULONG len);

/**
 * @brief Shrink all spaces in a  dynamicBuffer
 * @param buff The Buffer to shrink
 * @note Replace every consecutive sequence of spaces into one unique whitespace
 */
WBXML_DECLARE(void) wbxml_buffer_shrink_blanks(WBXMLBuffer *buff);

/**
 * @brief Remove whitespaces at beginning and end of a dynamic Buffer
 * @param buff The Buffer to strip
 */
WBXML_DECLARE(void) wbxml_buffer_strip_blanks(WBXMLBuffer *buff);

/**
 * @brief Compare two Buffers
 * @param buff1
 * @param buff2
 * @return 0 if they are equal, negative if `buff1' is less than `buff2' and positive if greater
 */
WBXML_DECLARE(WB_LONG) wbxml_buffer_compare(WBXMLBuffer *buff1, WBXMLBuffer *buff2);

/**
 * @brief Compare a WBXML Buffer with a C String
 * @param buff The WBXML Buffer
 * @param str  The C String
 * @return 0 if they are equal, negative if `buff' is less than `str' and positive if greater
 */
WBXML_DECLARE(WB_LONG) wbxml_buffer_compare_cstr(WBXMLBuffer *buff, const WB_TINY *str);

/**
 * @brief Split a Buffer into words at whitespace
 * @param buff The buffer to split
 * @return The List of splitted Words, or NULL if not enough memory
 * @warning Do NOT use this function directly, use wbxml_buffer_split_words() macro instead
 */
WBXML_DECLARE(WBXMLList *) wbxml_buffer_split_words_real(WBXMLBuffer *buff);
#define wbxml_buffer_split_words(a) wbxml_mem_cleam(wbxml_buffer_split_words_real(a))

/**
 * @brief Search a char in Buffer
 * @param to The buffer to search into
 * @param ch The char to search
 * @param pos Position to start searching in 'to' buffer
 * @param result The start position of char in 'to' buffer
 * @return TRUE if char successfully found in 'to' buffer, FALSE otherwise
 */
WBXML_DECLARE(WB_BOOL) wbxml_buffer_search_char(WBXMLBuffer *to, WB_UTINY ch, WB_ULONG pos, WB_ULONG *result);

/**
 * @brief Search a Buffer in another Buffer
 * @param to The buffer to search into
 * @param search The buffer to search
 * @param pos Position to start searching in 'to' buffer
 * @param result The start position of 'search' buffer in 'to' buffer
 * @return TRUE if successfully found 'search' in 'to' buffer, FALSE otherwise
 */
WBXML_DECLARE(WB_BOOL) wbxml_buffer_search(WBXMLBuffer *to, WBXMLBuffer *search, WB_ULONG pos, WB_ULONG *result);

/**
 * @brief Search a C String in a WBXMLBuffer Buffer
 * @param to The buffer to search into
 * @param search The C String to search
 * @param pos Position to start searching in 'to' buffer
 * @param result The start position of 'search' buffer in 'to' buffer
 * @return TRUE if successfully found 'search' in 'to' buffer, FALSE otherwise
 */
WBXML_DECLARE(WB_BOOL) wbxml_buffer_search_cstr(WBXMLBuffer *to, WB_UTINY *search, WB_ULONG pos, WB_ULONG *result);

/**
 * @brief Check if a buffer contains only Whitespaces
 * @param buffer The buffer to check
 * @return TRUE if it contains only whitespaces, FALSE otherwise
 */
WBXML_DECLARE(WB_BOOL) wbxml_buffer_contains_only_whitespaces(WBXMLBuffer *buffer);

/**
 * @brief Convert an Hexa dynamic buffer to Binary
 * @param buffer The buffer to convert
 */
WBXML_DECLARE(void) wbxml_buffer_hex_to_binary(WBXMLBuffer *buffer);

/**
 * @brief Convert an Binary dynamic buffer to Hexa
 * @param buffer The buffer to convert
 * @param uppercase Do we convert to Uppercase Hexa ?
 * @return TRUE if converted, FALSE otherwise
 */
WBXML_DECLARE(WB_BOOL) wbxml_buffer_binary_to_hex(WBXMLBuffer *buffer, WB_BOOL uppercase);

/**
 * @brief Remove trailing Zeros from a dynamic Buffer
 * @param buffer The buffer
 */
WBXML_DECLARE(void) wbxml_buffer_remove_trailing_zeros(WBXMLBuffer **buffer);

/** @} */

#ifdef __cplusplus
}
#endif /* __cplusplus */

#endif /* WBXML_BUFFERS_H */

.