include/yaz/wrbuf.h

   1 /* This file is part of the YAZ toolkit.
   2  * Copyright (C) Index Data.
   3  * All rights reserved.
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions are met:
   6  *
   7  *     * Redistributions of source code must retain the above copyright
   8  *       notice, this list of conditions and the following disclaimer.
   9  *     * Redistributions in binary form must reproduce the above copyright
  10  *       notice, this list of conditions and the following disclaimer in the
  11  *       documentation and/or other materials provided with the distribution.
  12  *     * Neither the name of Index Data nor the names of its contributors
  13  *       may be used to endorse or promote products derived from this
  14  *       software without specific prior written permission.
  15  *
  16  * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY
  17  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  18  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  19  * DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS BE LIABLE FOR ANY
  20  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  21  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  22  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  23  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  24  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  25  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26  */
  27
  28 /**
  29  * \file wrbuf.h
  30  * \brief Header for WRBUF (growing buffer)
  31  */
  32
  33 #ifndef WRBUF_H
  34 #define WRBUF_H
  35
  36 #include <yaz/xmalloc.h>
  37 #include <yaz/yaz-iconv.h>
  38
  39 YAZ_BEGIN_CDECL
  40
  41 /** \brief string buffer */
  42 typedef struct wrbuf
  43 {
  44     char *buf;
  45     size_t pos;
  46     size_t size;
  47 } wrbuf, *WRBUF;
  48
  49 /** \brief construct WRBUF
  50     \returns WRBUF
  51  */
  52 YAZ_EXPORT WRBUF wrbuf_alloc(void);
  53
  54 /** \brief destroy WRBUF and its buffer
  55     \param b WRBUF
  56
  57     For YAZ 4.0.2 WRBUF b may be NULL.
  58  */
  59 YAZ_EXPORT void wrbuf_destroy(WRBUF b);
  60
  61 /** \brief empty WRBUF content (length of buffer set to 0)
  62     \param b WRBUF
  63  */
  64 YAZ_EXPORT void wrbuf_rewind(WRBUF b);
  65
  66 /** \brief append constant size buffer to WRBUF
  67     \param b WRBUF
  68     \param buf buffer
  69     \param size size of buffer
  70  */
  71 YAZ_EXPORT void wrbuf_write(WRBUF b, const char *buf, size_t size);
  72
  73 /** \brief inserts buffer into WRBUF at some position
  74     \param b WRBUF
  75     \param pos position (0=beginning)
  76     \param buf buffer
  77     \param size size of buffer
  78  */
  79 YAZ_EXPORT void wrbuf_insert(WRBUF b, size_t pos, const char *buf, size_t size);
  80
  81 /** \brief appends C-string to WRBUF
  82     \param b WRBUF
  83     \param buf C-string (0-terminated)
  84  */
  85 YAZ_EXPORT void wrbuf_puts(WRBUF b, const char *buf);
  86
  87 /** \brief appends C-string to WRBUF - void pointer variant
  88     \param buf C-string
  89     \param client_data assumed WRBUF
  90 */
  91 YAZ_EXPORT void wrbuf_vp_puts(const char *buf, void *client_data);
  92
  93 /** \brief writes buffer of certain size to WRBUF and XML encode (as CDATA)
  94     \param b WRBUF
  95     \param cp CDATA
  96     \param size size of CDATA
  97  */
  98 YAZ_EXPORT void wrbuf_xmlputs_n(WRBUF b, const char *cp, size_t size);
  99
 100 /** \brief writes C-String to WRBUF and XML encode (as CDATA)
 101     \param b WRBUF
 102     \param cp CDATA buffer (0-terminated)
 103  */
 104 YAZ_EXPORT void wrbuf_xmlputs(WRBUF b, const char *cp);
 105
 106 /** \brief puts buf to WRBUF and replaces a single char
 107     \param b WRBUF
 108     \param buf buffer to append (C-string)
 109     \param from character "from"
 110     \param to charcter "to"
 111 */
 112 YAZ_EXPORT void wrbuf_puts_replace_char(WRBUF b, const char *buf,
 113                                         const char from, const char to);
 114
 115 /** \brief writes C-string to WRBUF and escape non-ASCII characters
 116     \param b WRBUF
 117     \param str C-string
 118
 119     Non-ASCII characters will be presented as \\xDD .
 120  */
 121 YAZ_EXPORT void wrbuf_puts_escaped(WRBUF b, const char *str);
 122
 123 /** \brief writes buffer to WRBUF and escape non-ASCII characters
 124     \param b WRBUF
 125     \param buf buffer
 126     \param len size of buffer
 127
 128     Non-ASCII characters will be presented as \\xDD .
 129  */
 130 YAZ_EXPORT void wrbuf_write_escaped(WRBUF b, const char *buf, size_t len);
 131
 132 /** \brief writes printf result to WRBUF
 133     \param b WRBUF
 134     \param fmt printf-like format
 135  */
 136 YAZ_EXPORT void wrbuf_printf(WRBUF b, const char *fmt, ...)
 137 #ifdef __GNUC__
 138         __attribute__ ((format (printf, 2, 3)))
 139 #endif
 140         ;
 141
 142 /** \brief General writer of string using iconv and cdata
 143     \param b WRBUF
 144     \param cd iconv handle (0 for no conversion)
 145     \param buf buffer
 146     \param size size of buffer
 147     \param wfunc write handler (that takes WRBUF only)
 148     \returns -1 if invalid sequence was encountered (truncation in effect)
 149     \returns 0 if buffer could be converted and written
 150 */
 151 int wrbuf_iconv_write2(WRBUF b, yaz_iconv_t cd, const char *buf,
 152                        size_t size,
 153                        void (*wfunc)(WRBUF, const char *, size_t));
 154
 155 /** \brief writer of string using iconv and cdata
 156
 157     Obsolete: use wrbuf_iconv_write2 instead.
 158     \param b WRBUF
 159     \param cd iconv handle (0 for no conversion)
 160     \param buf buffer
 161     \param size size of buffer
 162     \param cdata non-zero for CDATA; 0 for cdata
 163     \returns -1 if invalid sequence was encountered (truncation in effect)
 164     \returns 0 if buffer could be converted and written
 165 */
 166 int wrbuf_iconv_write_x(WRBUF b, yaz_iconv_t cd, const char *buf,
 167                         size_t size, int cdata)
 168 #ifdef __GNUC__
 169     __attribute__ ((deprecated))
 170 #endif
 171     ;
 172
 173 /** \brief Converts buffer using iconv and appends to WRBUF
 174     \param b WRBUF
 175     \param cd iconv handle
 176     \param buf buffer
 177     \param size size of buffer
 178 */
 179 YAZ_EXPORT void wrbuf_iconv_write(WRBUF b, yaz_iconv_t cd, const char *buf,
 180                                  size_t size);
 181
 182 /** \brief Converts buffer using iconv and appends to WRBUF as XML CDATA
 183     \param b WRBUF
 184     \param cd iconv handle
 185     \param buf buffer
 186     \param size size of buffer
 187 */
 188 YAZ_EXPORT void wrbuf_iconv_write_cdata(WRBUF b, yaz_iconv_t cd,
 189                                        const char *buf, size_t size);
 190
 191 /** \brief iconv converts C-string and appends to WRBUF
 192     \param b WRBUF
 193     \param cd iconv handle
 194     \param str C-string
 195 */
 196 YAZ_EXPORT void wrbuf_iconv_puts(WRBUF b, yaz_iconv_t cd, const char *str);
 197
 198 /** \brief iconv converts C-string and appends to WRBUF as XML CDATA
 199     \param b WRBUF
 200     \param cd iconv handle
 201     \param str C-string
 202 */
 203 YAZ_EXPORT void wrbuf_iconv_puts_cdata(WRBUF b, yaz_iconv_t cd,
 204                                        const char *str);
 205
 206 /** \brief iconv converts character and appends to WRBUF
 207     \param b WRBUF
 208     \param cd iconv handle
 209     \param ch character
 210 */
 211 YAZ_EXPORT void wrbuf_iconv_putchar(WRBUF b, yaz_iconv_t cd, int ch);
 212
 213 /** \brief iconv reset(flush) to WRBUF
 214     \param b
 215     \param cd iconv handle
 216
 217     This function calls iconv(cd, 0, 0, ..) to make it
 218     flush any remaining content.
 219 */
 220 YAZ_EXPORT void wrbuf_iconv_reset(WRBUF b, yaz_iconv_t cd);
 221
 222 /** \brief chips traling blanks away from WRBUF
 223     \param b WRBUF
 224 */
 225 YAZ_EXPORT void wrbuf_chop_right(WRBUF b);
 226
 227 /** \brief cut size of WRBUF
 228     \param b WRBUF
 229     \param no_to_remove number of bytes to remove
 230  */
 231 YAZ_EXPORT void wrbuf_cut_right(WRBUF b, size_t no_to_remove);
 232
 233 /** \brief grow WRBUF larger
 234     \param b WRBUF
 235     \param minsize make WRBUF at least this size
 236
 237     This function is normally not used by applications
 238 */
 239 YAZ_EXPORT int wrbuf_grow(WRBUF b, size_t minsize);
 240
 241 #define wrbuf_len(b) ((b)->pos)
 242 #define wrbuf_buf(b) ((b)->buf)
 243
 244 /** \brief returns WRBUF content as C-string
 245     \param b WRBUF (may not be NULL)
 246     \returns C-string
 247 */
 248 YAZ_EXPORT const char *wrbuf_cstr(WRBUF b);
 249
 250 /** \brief returns WRBUF content as C-string or NULL
 251     \param b WRBUF
 252     \returns C-string or NULL
 253
 254     This function returns NULL if either b is NULL or length of buffer is 0
 255 */
 256 YAZ_EXPORT
 257 const char *wrbuf_cstr_null(WRBUF b);
 258
 259 #define wrbuf_putc(b, c) \
 260     ((void) ((b)->pos >= (b)->size ? wrbuf_grow(b, 1) : 0),  \
 261     (b)->buf[(b)->pos++] = (c), 0)
 262
 263
 264 /** \brief writes JSON text to WRBUF with escaping
 265     \param b result
 266     \param str input string to be encoded
 267 */
 268 YAZ_EXPORT
 269 void wrbuf_json_puts(WRBUF b, const char *str);
 270
 271 /** \brief writes JSON text to WRBUF with escaping
 272     \param b result
 273     \param cp char buffer
 274     \param sz size of char buffer
 275 */
 276 YAZ_EXPORT
 277 void wrbuf_json_write(WRBUF b, const char *cp, size_t sz);
 278
 279 YAZ_EXPORT
 280 void wrbuf_iconv_json_write(WRBUF b, yaz_iconv_t cd,
 281                             const char *buf, size_t size);
 282
 283 YAZ_EXPORT
 284 void wrbuf_iconv_json_puts(WRBUF b, yaz_iconv_t cd, const char *strz);
 285
 286 /** \brief writes SHA1 text to WRBUF
 287     \param b result
 288     \param cp char buffer
 289     \param sz size of char buffer
 290     \param hexit 1=hex mode; 0=binary
 291     \returns 0 if successful
 292     \returns -1 on error
 293 */
 294 YAZ_EXPORT
 295 int wrbuf_sha1_write(WRBUF b, const char *cp, size_t sz, int hexit);
 296
 297 /** \brief writes SHA1 text to WRBUF
 298     \param b result
 299     \param cp C-string
 300     \param hexit 1=hex mode; 0=binary
 301     \returns 0 if successful
 302     \returns -1 on error
 303 */
 304 YAZ_EXPORT
 305 int wrbuf_sha1_puts(WRBUF b, const char *cp, int hexit);
 306
 307 YAZ_END_CDECL
 308
 309 #endif
 310 /*
 311  * Local variables:
 312  * c-basic-offset: 4
 313  * c-file-style: "Stroustrup"
 314  * indent-tabs-mode: nil
 315  * End:
 316  * vim: shiftwidth=4 tabstop=8 expandtab
 317  */
 318