1 /* 2 * libwbxml, the WBXML Library. 3 * Copyright (C) 2002-2008 Aymerick Jehanne <aymerick@jehanne.org> 4 * Copyright (C) 2011 Michael Bell <michael.bell@opensync.org> 5 * 6 * This library is free software; you can redistribute it and/or 7 * modify it under the terms of the GNU Lesser General Public 8 * License as published by the Free Software Foundation; either 9 * version 2.1 of the License, or (at your option) any later version. 10 * 11 * This library is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 * Lesser General Public License for more details. 15 * 16 * You should have received a copy of the GNU Lesser General Public 17 * License along with this library; if not, write to the Free Software 18 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA 19 * 20 * LGPL v2.1: http://www.gnu.org/copyleft/lesser.txt 21 * 22 * Contact: aymerick@jehanne.org 23 * Home: http://libwbxml.aymerick.com 24 */ 25 26 /** 27 * @file wbxml_buffers.h 28 * @ingroup wbxml_buffers 29 * 30 * @author Aymerick Jehanne <aymerick@jehanne.org> 31 * @date 02/03/12 32 * 33 * @brief Generic Buffers Functions 34 * 35 * @note Original idea: Kannel Project (http://kannel.3glab.org/) 36 */ 37 38 #ifndef WBXML_BUFFERS_H 39 #define WBXML_BUFFERS_H 40 41 #include <stdio.h> 42 43 #include "wbxml.h" 44 #include "wbxml_lists.h" 45 46 #ifdef __cplusplus 47 extern "C" { 48 #endif /* __cplusplus */ 49 50 /** 51 * @brief WBXML Generic Buffer 52 */ 53 typedef struct WBXMLBuffer_s WBXMLBuffer; 54 55 56 /** @addtogroup wbxml_buffers 57 * @{ 58 */ 59 60 /** 61 * @brief Create a Buffer 62 * @param data The initial data for buffer 63 * @param len Size of data 64 * @param malloc_block Size of the initial malloc block (tune this parameter to avoid too many reallocations) 65 * @return The newly created Buffer, or NULL if not enought memory 66 * @warning Do NOT use this function directly, use wbxml_buffer_create() macro instead 67 */ 68 WBXML_DECLARE(WBXMLBuffer *) wbxml_buffer_create_real(const WB_UTINY *data, WB_ULONG len, WB_ULONG malloc_block); 69 70 /** Wrapper around wbxml_buffer_create_real() to track Memory */ 71 #define wbxml_buffer_create(a,b,c) \ 72 wbxml_mem_cleam(wbxml_buffer_create_real((const WB_UTINY *)a,b,c)) 73 74 /** Wrapper around wbxml_buffer_create() when creating buffer with a C String (NULL Terminated) */ 75 #define wbxml_buffer_create_from_cstr(a) \ 76 wbxml_buffer_create((const WB_UTINY *)a,WBXML_STRLEN(a),WBXML_STRLEN(a)) 77 78 /** 79 * @brief Create a static Buffer 80 * @param data Buffer data 81 * @param len Data lenght 82 * @return The newly created Buffer, or NULL if not enough memory 83 * @note A static buffer can't be modified, so do not use functions dedeicated to dynamic buffers 84 * as wbxml_buffer_insert() or wbxml_buffer_append() 85 * @warning Do NOT use this function directly, use wbxml_buffer_sta_create() macro instead 86 */ 87 WBXML_DECLARE(WBXMLBuffer *) wbxml_buffer_sta_create_real(const WB_UTINY *data, WB_ULONG len); 88 89 /** Wrapper around wbxml_buffer_sta_create_real() to track Memory */ 90 #define wbxml_buffer_sta_create(a,b) \ 91 wbxml_mem_cleam(wbxml_buffer_sta_create_real((const WB_UTINY *)a,b)) 92 93 /** Wrapper around wbxml_buffer_sta_create() when creating static buffer with a C String (NULL Terminated) */ 94 #define wbxml_buffer_sta_create_from_cstr(a) \ 95 wbxml_buffer_sta_create((const WB_UTINY *)a,WBXML_STRLEN(a)) 96 97 /** 98 * @brief Destroy a Buffer 99 * @param buff The Buffer to destroy 100 */ 101 WBXML_DECLARE(void) wbxml_buffer_destroy(WBXMLBuffer *buff); 102 103 /** 104 * @brief Destroy a Buffer (used for wbxml_list_destroy()) 105 * @param buff The Buffer to destroy 106 */ 107 WBXML_DECLARE_NONSTD(void) wbxml_buffer_destroy_item(void *buff); 108 109 /** 110 * Duplicate a Buffer 111 * 112 * Even if a static buffer is provided, the duplicated buffer is 113 * a dynamic buffer. 114 * 115 * @param buff The Buffer to duplicate 116 * @return The duplicated buffer, or NULL if not enough memory 117 */ 118 WBXML_DECLARE(WBXMLBuffer *) wbxml_buffer_duplicate(WBXMLBuffer *buff); 119 120 /** 121 * @brief Get data length of a buffer 122 * @param buff The Buffer 123 * @return The Buffer data length 124 */ 125 WBXML_DECLARE(WB_ULONG) wbxml_buffer_len(WBXMLBuffer *buff); 126 127 /** 128 * @brief Get a byte from a Buffer 129 * @param buff The Buffer 130 * @param pos Byte position in buffer 131 * @param result The resulting char 132 * @return TRUE if OK, or FALSE if error 133 */ 134 WBXML_DECLARE(WB_BOOL) wbxml_buffer_get_char(WBXMLBuffer *buff, WB_ULONG pos, WB_UTINY *result); 135 136 /** 137 * @brief Set a byte in a dynamic Buffer 138 * @param buff The Buffer 139 * @param pos Byte position in buffer 140 * @param ch The character to set 141 */ 142 WBXML_DECLARE(WB_BOOL) wbxml_buffer_set_char(WBXMLBuffer *buff, WB_ULONG pos, WB_UTINY ch); 143 144 /** 145 * @brief Get pointer to internal buffer data 146 * @param buff The Buffer 147 * @return Pointer to buffer data, or "" if buffer is NULL or empty 148 */ 149 WBXML_DECLARE(WB_UTINY *) wbxml_buffer_get_cstr(WBXMLBuffer *buff); 150 151 /** 152 * @brief Insert a Buffer into a dynamic Buffer 153 * @param to The Buffer to modify 154 * @param buff The Buffer to insert 155 * @param pos The position of insertion in 'to' 156 * @return TRUE if data inserted, FALSE otherwise 157 */ 158 WBXML_DECLARE(WB_BOOL) wbxml_buffer_insert(WBXMLBuffer *to, WBXMLBuffer *buff, WB_ULONG pos); 159 160 /** 161 * @brief Insert a C String into a dynamic Buffer 162 * @param to The Buffer to modify 163 * @param str The BC String to insert 164 * @param pos The position of insertion in 'to' 165 * @return TRUE if data inserted, FALSE otherwise 166 */ 167 WBXML_DECLARE(WB_BOOL) wbxml_buffer_insert_cstr(WBXMLBuffer *to, const WB_UTINY *str, WB_ULONG pos); 168 169 /** 170 * @brief Append a Buffer to a dynamic Buffer 171 * @param dest The destination Buffer 172 * @param buff The Buffer to append 173 * @return TRUE if buffer appended, FALSE otherwise 174 */ 175 WBXML_DECLARE(WB_BOOL) wbxml_buffer_append(WBXMLBuffer *dest, WBXMLBuffer *buff); 176 177 178 /** 179 * @brief Append data to a dynamic Buffer 180 * @param buff The Buffer 181 * @param data Data to append 182 * @param len Data length 183 * @return TRUE if data appended, FALSE otherwise 184 */ 185 WBXML_DECLARE(WB_BOOL) wbxml_buffer_append_data_real(WBXMLBuffer *buff, const WB_UTINY *data, WB_ULONG len); 186 187 /** Wrapper around wbxml_buffer_append_data_real() to avoid Casts in code */ 188 #define wbxml_buffer_append_data(a,b,c) wbxml_buffer_append_data_real(a,(const WB_UTINY *)b,c) 189 190 /** 191 * @brief Append a C String (NULL terminated) to a dynamic Buffer 192 * @param buff The Buffer 193 * @param data String to append 194 * @return TRUE if data appended, FALSE otherwise 195 */ 196 WBXML_DECLARE(WB_BOOL) wbxml_buffer_append_cstr_real(WBXMLBuffer *buff, const WB_UTINY *data); 197 198 /** Wrapper around wbxml_buffer_append_cstr_real() to avoid Casts in code */ 199 #define wbxml_buffer_append_cstr(a,b) wbxml_buffer_append_cstr_real(a,(const WB_UTINY *)b) 200 201 202 /** 203 * @brief Append a byte to a dynamic Buffer 204 * @param buff The Buffer 205 * @param ch Byte to append 206 * @return TRUE if byte appended, FALSE otherwise 207 */ 208 WBXML_DECLARE(WB_BOOL) wbxml_buffer_append_char(WBXMLBuffer *buff, WB_UTINY ch); 209 210 /** 211 * @brief Append a Multibyte Integer to a dynamic Buffer 212 * @param buff The Buffer 213 * @param value The value to append 214 * @return TRUE if value appended, FALSE otherwise 215 */ 216 WBXML_DECLARE(WB_BOOL) wbxml_buffer_append_mb_uint_32(WBXMLBuffer *buff, WB_ULONG value); 217 218 /** 219 * @brief Delete a range of Bytes in a dynamicBuffer 220 * @param buff The Buffer 221 * @param pos Position where to start deletion 222 * @param len Number of bytes to delete 223 */ 224 WBXML_DECLARE(WB_BOOL) wbxml_buffer_delete(WBXMLBuffer *buff, WB_ULONG pos, WB_ULONG len); 225 226 /** 227 * @brief Shrink all spaces in a dynamicBuffer 228 * @param buff The Buffer to shrink 229 * @note Replace every consecutive sequence of spaces into one unique whitespace 230 */ 231 WBXML_DECLARE(WB_BOOL) wbxml_buffer_shrink_blanks(WBXMLBuffer *buff); 232 233 /** 234 * @brief Remove whitespaces at beginning and end of a dynamic Buffer 235 * @param buff The Buffer to strip 236 */ 237 WBXML_DECLARE(WB_BOOL) wbxml_buffer_strip_blanks(WBXMLBuffer *buff); 238 239 /** 240 * @brief Compare two Buffers 241 * @param buff1 242 * @param buff2 243 * @return 0 if they are equal, negative if `buff1' is less than `buff2' and positive if greater 244 */ 245 WBXML_DECLARE(WB_LONG) wbxml_buffer_compare(WBXMLBuffer *buff1, WBXMLBuffer *buff2); 246 247 /** 248 * @brief Compare a WBXML Buffer with a C String 249 * @param buff The WBXML Buffer 250 * @param str The C String 251 * @return 0 if they are equal, negative if `buff' is less than `str' and positive if greater 252 */ 253 WBXML_DECLARE(WB_LONG) wbxml_buffer_compare_cstr(WBXMLBuffer *buff, const WB_TINY *str); 254 255 /** 256 * @brief Split a Buffer into words at whitespace 257 * @param buff The buffer to split 258 * @return The List of splitted Words, or NULL if not enough memory 259 * @warning Do NOT use this function directly, use wbxml_buffer_split_words() macro instead 260 */ 261 WBXML_DECLARE(WBXMLList *) wbxml_buffer_split_words_real(WBXMLBuffer *buff); 262 #define wbxml_buffer_split_words(a) wbxml_mem_cleam(wbxml_buffer_split_words_real(a)) 263 264 /** 265 * @brief Search a char in Buffer 266 * @param to The buffer to search into 267 * @param ch The char to search 268 * @param pos Position to start searching in 'to' buffer 269 * @param result The start position of char in 'to' buffer 270 * @return TRUE if char successfully found in 'to' buffer, FALSE otherwise 271 */ 272 WBXML_DECLARE(WB_BOOL) wbxml_buffer_search_char(WBXMLBuffer *to, const WB_UTINY ch, WB_ULONG pos, WB_ULONG *result); 273 274 /** 275 * @brief Search a Buffer in another Buffer 276 * @param to The buffer to search into 277 * @param search The buffer to search 278 * @param pos Position to start searching in 'to' buffer 279 * @param result The start position of 'search' buffer in 'to' buffer 280 * @return TRUE if successfully found 'search' in 'to' buffer, FALSE otherwise 281 */ 282 WBXML_DECLARE(WB_BOOL) wbxml_buffer_search(WBXMLBuffer *to, WBXMLBuffer *search, WB_ULONG pos, WB_ULONG *result); 283 284 /** 285 * @brief Search a C String in a WBXMLBuffer Buffer 286 * @param to The buffer to search into 287 * @param search The C String to search 288 * @param pos Position to start searching in 'to' buffer 289 * @param result The start position of 'search' buffer in 'to' buffer 290 * @return TRUE if successfully found 'search' in 'to' buffer, FALSE otherwise 291 */ 292 WBXML_DECLARE(WB_BOOL) wbxml_buffer_search_cstr(WBXMLBuffer *to, const WB_UTINY *search, WB_ULONG pos, WB_ULONG *result); 293 294 /** 295 * @brief Check if a buffer contains only Whitespaces 296 * @param buffer The buffer to check 297 * @return TRUE if it contains only whitespaces, FALSE otherwise 298 */ 299 WBXML_DECLARE(WB_BOOL) wbxml_buffer_contains_only_whitespaces(WBXMLBuffer *buffer); 300 301 /** 302 * @brief Convert an Hexa dynamic buffer to Binary 303 * @param buffer The buffer to convert 304 */ 305 WBXML_DECLARE(WB_BOOL) wbxml_buffer_hex_to_binary(WBXMLBuffer *buffer); 306 307 /** 308 * @brief Convert an Binary dynamic buffer to Hexa 309 * @param buffer The buffer to convert 310 * @param uppercase Do we convert to Uppercase Hexa ? 311 * @return TRUE if converted, FALSE otherwise 312 */ 313 WBXML_DECLARE(WB_BOOL) wbxml_buffer_binary_to_hex(WBXMLBuffer *buffer, WB_BOOL uppercase); 314 315 /** 316 * @brief Convert base64 encoded data to binary data 317 * @param buffer The buffer to convert 318 * @return TRUE if converted, FALSE otherwise 319 */ 320 WBXML_DECLARE(WBXMLError) wbxml_buffer_decode_base64(WBXMLBuffer *buffer); 321 322 /** 323 * @brief Convert binary data to base64 encoded data 324 * @param buffer The buffer to convert 325 * @return TRUE if converted, FALSE otherwise 326 */ 327 WBXML_DECLARE(WBXMLError) wbxml_buffer_encode_base64(WBXMLBuffer *buffer); 328 329 /** 330 * @brief Remove trailing Zeros from a dynamic Buffer 331 * @param buffer The buffer 332 */ 333 WBXML_DECLARE(WB_BOOL) wbxml_buffer_remove_trailing_zeros(WBXMLBuffer *buffer); 334 335 /** @} */ 336 337 #ifdef __cplusplus 338 } 339 #endif /* __cplusplus */ 340 341 #endif /* WBXML_BUFFERS_H */ 342