lib/silcutil/silcbuffmt.h

   1 /*
   2
   3   silcbuffmt.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 1997 - 2008 Pekka Riikonen
   8
   9   This program is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU General Public License as published by
  11   the Free Software Foundation; version 2 of the License.
  12
  13   This program is distributed in the hope that it will be useful,
  14   but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16   GNU General Public License for more details.
  17
  18 */
  19
  20 /****h* silcutil/SILC Buffer Format Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * SILC Buffer Format API provides functions for formatting different data
  25  * types into a buffer and retrieving different data types from a buffer
  26  * into specified data types.  It is especially useful to encode packets,
  27  * protocol payloads and such.
  28  *
  29  * It also provides many advanced features like calling user specified
  30  * encoder and decoder functions that are free to do anything to the buffer.
  31  * The API also provides powerful regular expression matching capabilities
  32  * within the buffer, enabling caller to not only match regular expressions
  33  * but to make the API behave like Stream Editor (Sed) and Awk.  The buffer
  34  * can be matched against regular expression and then edited.  Caller can
  35  * do anything they want to the buffer after a match.  The SILC_STR_REGEX
  36  * macro provides many different flags that can change the behavior of the
  37  * matching, with capabilities to also mimic Sed behavior.
  38  *
  39  * As the SilcBuffer API is not thread-safe these routines may not be used
  40  * in multithreaded environment with a same SilcBuffer context without
  41  * concurrency control.
  42  *
  43  * EXAMPLE
  44  *
  45  * SilcBufferStruct buffer;
  46  *
  47  * memset(&buffer, 0, sizeof(buffer));
  48  * ret = silc_buffer_format(&buffer,
  49  *                          SILC_STR_UINT32(intval),
  50  *                          SILC_STR_UINT8(charval),
  51  *                          SILC_STR_UINT64(longintval),
  52  *                          SILC_STR_UINT16(str_len),
  53  *                          SILC_STR_DATA(str, str_len),
  54  *                          SILC_STR_END);
  55  * if (ret < 0)
  56  *   error;
  57  *
  58  * // sed 's/foo/bar/', replace first foo with bar
  59  * silc_buffer_format(buffer,
  60  *                    SILC_STR_REGEX("foo", 0),
  61  *                      SILC_STR_STRING("bar"),
  62  *                    SILC_STR_END, SILC_STR_END);
  63  *
  64  ***/
  65
  66 #ifndef SILCBUFFMT_H
  67 #define SILCBUFFMT_H
  68
  69 /****f* silcutil/SilcBufferFormatAPI/SilcBufferFormatFunc
  70  *
  71  * SYNOPSIS
  72  *
  73  *    typedef int (*SilcBuffeSFormatFunc)(SilcStack stack,
  74  *                                        SilcBuffer buffer,
  75  *                                        void *value,
  76  *                                        void *context);
  77  *
  78  * DESCRIPTION
  79  *
  80  *    Formatting function callback given with SILC_STR_FUNC type.  The
  81  *    `buffer' is the buffer being formatted at the location where the
  82  *    SILC_STR_FUNC was placed in formatting.  The function should call
  83  *    silc_buffer_senlarge before it adds the data to the buffer to make
  84  *    sure that it has enough space.  The buffer->head points to the
  85  *    start of the buffer and silc_buffer_headlen() gives the length
  86  *    of the currently formatted data area.  It is also possible to use
  87  *    silc_buffer_sformat with `buffer' which will enlarge the buffer if
  88  *    needed.
  89  *
  90  *    The `value' is the value given to SILC_STR_FUNC that is to be formatted
  91  *    into the buffer.  It may be NULL if the function is not formatting
  92  *    new data into the buffer.  The `context' is caller specific context.
  93  *    Returns -1 on error and length of the formatted value otherwise, and
  94  *    0 if nothing was formatted.
  95  *
  96  ***/
  97 typedef int (*SilcBufferFormatFunc)(SilcStack stack, SilcBuffer buffer,
  98                                     void *value, void *context);
  99
 100 /****f* silcutil/SilcBufferFormatAPI/SilcBufferUnformatFunc
 101  *
 102  * SYNOPSIS
 103  *
 104  *    typedef int (*SilcBufferUnformatFunc)(SilcBuffer buffer,
 105  *                                          void **value,
 106  *                                          void *context);
 107  *
 108  * DESCRIPTION
 109  *
 110  *    Unformatting function callback given with SILC_STR_FUNC type.  The
 111  *    `buffer' is the buffer being unformatted and is at the location where
 112  *    the SILC_STR_FUNC was placed in unformatting.  The function should
 113  *    check there is enough data in the `buffer' before trying to decode
 114  *    from it.
 115  *
 116  *    If this function unformats anything from the buffer its value is to
 117  *    be returned to the `value' pointer.  The implementation should itself
 118  *    decide whether the unformatted value is allocated or not.  If this
 119  *    function does not unformat anything, nothing is returned to `value'
 120  *
 121  *    The `context' is caller specific context.  Returns -1 on error, and
 122  *    length of the unformatted value otherwise, and 0 if nothing was
 123  *    unformatted.
 124  *
 125  ***/
 126 typedef int (*SilcBufferUnformatFunc)(SilcStack stack, SilcBuffer buffer,
 127                                       void **value, void *context);
 128
 129 /* Prototypes */
 130
 131 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_format
 132  *
 133  * SYNOPSIS
 134  *
 135  *    int silc_buffer_format(SilcBuffer dst, ...);
 136  *
 137  * DESCRIPTION
 138  *
 139  *    Formats a buffer from a variable argument list.  Returns -1 if the
 140  *    system is out of memory and the length of the formatted buffer otherwise.
 141  *    The buffer is enlarged automatically during formatting, if it doesn't
 142  *    already have enough space.  Sets silc_errno in case of error.
 143  *
 144  * EXAMPLE
 145  *
 146  *    Three basic ways of using silc_buffer_format:
 147  *
 148  *    // Statically allocated zero size buffer
 149  *    SilcBufferStruct buffer;
 150  *
 151  *    memset(&buffer, 0, sizeof(buffer));
 152  *    ret = silc_buffer_format(&buffer,
 153  *                             SILC_STR_UINT32(intval),
 154  *                             SILC_STR_UINT8(charval),
 155  *                             SILC_STR_UINT32(intval),
 156  *                             SILC_STR_UINT16(str_len),
 157  *                             SILC_STR_DATA(str, str_len),
 158  *                             SILC_STR_END);
 159  *    if (ret < 0)
 160  *      error;
 161  *
 162  *    // Free the allocated data
 163  *    silc_buffer_purge(&buffer);
 164  *
 165  *    // Dynamically allocated zero size buffer
 166  *    SilcBuffer buf;
 167  *    buf = silc_buffer_alloc(0);
 168  *    ret = silc_buffer_format(buf,
 169  *                             SILC_STR_UINT32(intval),
 170  *                             SILC_STR_UINT8(charval),
 171  *                             SILC_STR_END);
 172  *    if (ret < 0)
 173  *      error;
 174  *
 175  *    // Free the allocated buffer
 176  *    silc_buffer_free(buf);
 177  *
 178  *    // Dynamically allocated buffer with enough space
 179  *    SilcBuffer buf;
 180  *    buf = silc_buffer_alloc(2 + str_len);
 181  *    ret = silc_buffer_format(buf,
 182  *                             SILC_STR_UINT16(str_len),
 183  *                             SILC_STR_DATA(str, str_len),
 184  *                             SILC_STR_END);
 185  *    if (ret < 0)
 186  *      error;
 187  *
 188  ***/
 189 int silc_buffer_format(SilcBuffer dst, ...);
 190
 191 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_sformat
 192  *
 193  * SYNOPSIS
 194  *
 195  *    int silc_buffer_sformat(SilcStack stack, SilcBuffer dst, ...);
 196  *
 197  * DESCRIPTION
 198  *
 199  *    Same as silc_buffer_format but uses `stack' to allocate the memory.
 200  *    if `stack' is NULL reverts back to silc_buffer_format call.  Returns
 201  *    -1 if system is out of memory.  Sets silc_errno in case of error.
 202  *
 203  *    Note that this call consumes the `stack'.  The caller should push the
 204  *    stack before calling the function and pop it later.
 205  *
 206  ***/
 207 int silc_buffer_sformat(SilcStack stack, SilcBuffer dst, ...);
 208
 209 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_format_vp
 210  *
 211  * SYNOPSIS
 212  *
 213  *    int silc_buffer_format_vp(SilcBuffer dst, va_list vp);
 214  *
 215  * DESCRIPTION
 216  *
 217  *    Formats a buffer from a variable argument list indicated by the `ap'.
 218  *    Returns -1 if system is out of memory and the length of the formatted
 219  *    buffer otherwise.
 220  *
 221  ***/
 222 int silc_buffer_format_vp(SilcBuffer dst, va_list ap);
 223
 224 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_sformat_vp
 225  *
 226  * SYNOPSIS
 227  *
 228  *    int silc_buffer_sformat_vp(SilcStack stack, SilcBuffer dst, va_list vp);
 229  *
 230  * DESCRIPTION
 231  *
 232  *    Same as silc_buffer_format_vp but uses `stack' to allocate the memory.
 233  *    if `stack' is NULL reverts back to silc_buffer_format_vp call.  Returns
 234  *    -1 if system is out of memory.  Sets silc_errno in case of error.
 235  *
 236  *    Note that this call consumes the `stack'.  The caller should push the
 237  *    stack before calling the function and pop it later.
 238  *
 239  ***/
 240 int silc_buffer_sformat_vp(SilcStack stack, SilcBuffer dst, va_list ap);
 241
 242 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_unformat
 243  *
 244  * SYNOPSIS
 245  *
 246  *    int silc_buffer_unformat(SilcBuffer src, ...);
 247  *
 248  * DESCRIPTION
 249  *
 250  *    Unformats a buffer from a variable argument list.  Returns -1 on error
 251  *    and the length of the unformatted buffer otherwise.  Sets silc_errno
 252  *    in case of error.
 253  *
 254  * EXAMPLE
 255  *
 256  *    ret = silc_buffer_unformat(buffer,
 257  *                               SILC_STR_UINT32(&intval),
 258  *                               SILC_STR_UINT8(&charval),
 259  *                               SILC_STR_OFFSET(4),
 260  *                               SILC_STR_UI16_NSTRING_ALLOC(&str, &str_len),
 261  *                               SILC_STR_END);
 262  *    if (ret < 0)
 263  *      error;
 264  *
 265  ***/
 266 int silc_buffer_unformat(SilcBuffer src, ...);
 267
 268 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_sunformat
 269  *
 270  * SYNOPSIS
 271  *
 272  *    int silc_buffer_sunformat(SilcStack stack, SilcBuffer src, ...);
 273  *
 274  * DESCRIPTION
 275  *
 276  *    Same as silc_buffer_unformat but uses `stack' to allocate the memory.
 277  *    if `stack' is NULL reverts back to silc_buffer_format call.
 278  *
 279  *    Note that this call consumes the `stack'.  The caller should push the
 280  *    stack before calling the function and pop it later.
 281  *
 282  ***/
 283 int silc_buffer_sunformat(SilcStack stack, SilcBuffer src, ...);
 284
 285 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_unformat_vp
 286  *
 287  * SYNOPSIS
 288  *
 289  *    int silc_buffer_unformat_vp(SilcBuffer src, va_list vp);
 290  *
 291  * DESCRIPTION
 292  *
 293  *    Unformats a buffer from a variable argument list indicated by the `ap'.
 294  *    Returns -1 on error and the length of the unformatted buffer otherwise.
 295  *
 296  ***/
 297 int silc_buffer_unformat_vp(SilcBuffer src, va_list ap);
 298
 299 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_sunformat_vp
 300  *
 301  * SYNOPSIS
 302  *
 303  *    int silc_buffer_sunformat_vp(SilcBuffer src, va_list vp);
 304  *
 305  * DESCRIPTION
 306  *
 307  *    Same as silc_buffer_unformat_vp but uses `stack' to allocate the
 308  *    memory.  if `stack' is NULL reverts back to silc_buffer_format_vp call.
 309  *
 310  *    Note that this call consumes the `stack'.  The caller should push the
 311  *    stack before calling the function and pop it later.
 312  *
 313  ***/
 314 int silc_buffer_sunformat_vp(SilcStack stack, SilcBuffer src, va_list ap);
 315
 316 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_strformat
 317  *
 318  * SYNOPSIS
 319  *
 320  *    int silc_buffer_strformat(SilcBuffer dst, ...);
 321  *
 322  * DESCRIPTION
 323  *
 324  *    Formats a buffer from variable argument list of strings.  Each
 325  *    string must be NULL-terminated and the variable argument list must
 326  *    be end with SILC_STRFMT_END argument.  This allows that a string in
 327  *    the list can be NULL, in which case it is skipped.  This automatically
 328  *    allocates the space for the buffer data but `dst' must be already
 329  *    allocated by the caller.  Returns -1 if system is out of memory and
 330  *    sets silc_errno.
 331  *
 332  * EXAMPLE
 333  *
 334  *    ret = silc_buffer_strformat(buffer, "foo", "bar", SILC_STRFMT_END);
 335  *    if (ret < 0)
 336  *      error;
 337  *
 338  ***/
 339 int silc_buffer_strformat(SilcBuffer dst, ...);
 340
 341 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_sstrformat
 342  *
 343  * SYNOPSIS
 344  *
 345  *    int silc_buffer_strformat(SilcStack stack, SilcBuffer dst, ...);
 346  *
 347  * DESCRIPTION
 348  *
 349  *    Formats a buffer from variable argument list of strings.  Each
 350  *    string must be NULL-terminated and the variable argument list must
 351  *    be end with SILC_STRFMT_END argument.  This allows that a string in
 352  *    the list can be NULL, in which case it is skipped.  This automatically
 353  *    allocates the space for the buffer data but `dst' must be already
 354  *    allocated by the caller.  This function is equivalent to
 355  *    silc_buffer_strformat but allocates memory from `stack'.  Returns -1
 356  *    if system is out of memory and sets silc_errno.
 357  *
 358  *    Note that this call consumes the `stack'.  The caller should push the
 359  *    stack before calling the function and pop it later.
 360  *
 361  ***/
 362 int silc_buffer_sstrformat(SilcStack stack, SilcBuffer dst, ...);
 363
 364 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_SINT8
 365  *
 366  * NAME
 367  *
 368  *    #define SILC_STR_SINT8() ...
 369  *
 370  * DESCRIPTION
 371  *
 372  *    One 8-bit signed integer.
 373  *
 374  *    Formatting:    SILC_STR_SINT8(SilcInt8)
 375  *    Unformatting:  SILC_STR_SINT8(SilcInt8 *)
 376  *
 377  ***/
 378 #define SILC_STR_SINT8(x) SILC_PARAM_SINT8, (x)
 379
 380 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_UINT8
 381  *
 382  * NAME
 383  *
 384  *    #define SILC_STR_UINT8() ...
 385  *
 386  * DESCRIPTION
 387  *
 388  *    One 8-bit unsigned integer.
 389  *
 390  *    Formatting:    SILC_STR_UINT8(SilcUInt8)
 391  *    Unformatting:  SILC_STR_UINT8(SilcUInt8 *)
 392  *
 393  ***/
 394 #define SILC_STR_UINT8(x) SILC_PARAM_UINT8, (x)
 395
 396 /* Deprecated */
 397 #define SILC_STR_SI_CHAR(x) SILC_PARAM_SINT8, (x)
 398 #define SILC_STR_UI_CHAR(x) SILC_PARAM_UINT8, (x)
 399
 400 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_SINT16
 401  *
 402  * NAME
 403  *
 404  *    #define SILC_STR_SINT16() ...
 405  *
 406  * DESCRIPTION
 407  *
 408  *    SilcInt16.
 409  *
 410  *    Formatting:    SILC_STR_SINT16(SilcInt16)
 411  *    Unformatting:  SILC_STR_SINT16(SilcInt16 *)
 412  *
 413  ***/
 414 #define SILC_STR_SINT16(x) SILC_PARAM_SINT16, (x)
 415
 416 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_UINT16
 417  *
 418  * NAME
 419  *
 420  *    #define SILC_STR_UINT16() ...
 421  *
 422  * DESCRIPTION
 423  *
 424  *    SilcUInt16.
 425  *
 426  *    Formatting:    SILC_STR_UINT16(SilcUInt16)
 427  *    Unformatting:  SILC_STR_UINT16(SilcUInt16 *)
 428  *
 429  ***/
 430 #define SILC_STR_UINT16(x) SILC_PARAM_UINT16, (x)
 431
 432 /* Deprecated */
 433 #define SILC_STR_SI_SHORT(x) SILC_PARAM_SINT16, (x)
 434 #define SILC_STR_UI_SHORT(x) SILC_PARAM_UINT16, (x)
 435
 436 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_SINT32
 437  *
 438  * NAME
 439  *
 440  *    #define SILC_STR_SINT32() ...
 441  *
 442  * DESCRIPTION
 443  *
 444  *    SilcInt32.
 445  *
 446  *    Formatting:    SILC_STR_SINT32(SilcInt32)
 447  *    Unformatting:  SILC_STR_SINT32(SilcInt32 *)
 448  *
 449  ***/
 450 #define SILC_STR_SINT32(x) SILC_PARAM_SINT32, (x)
 451
 452 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_UINT32
 453  *
 454  * NAME
 455  *
 456  *    #define SILC_STR_UINT32() ...
 457  *
 458  * DESCRIPTION
 459  *
 460  *    SilcUInt32.
 461  *
 462  *    Formatting:    SILC_STR_UINT32(SilcUInt32)
 463  *    Unformatting:  SILC_STR_UINT32(SilcUInt32 *)
 464  *
 465  ***/
 466 #define SILC_STR_UINT32(x) SILC_PARAM_UINT32, (x)
 467
 468 /* Deprecated */
 469 #define SILC_STR_SI_INT(x) SILC_PARAM_SINT32, (x)
 470 #define SILC_STR_UI_INT(x) SILC_PARAM_UINT32, (x)
 471
 472 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_SINT64
 473  *
 474  * NAME
 475  *
 476  *    #define SILC_STR_SINT64() ...
 477  *
 478  * DESCRIPTION
 479  *
 480  *    SilcInt64.
 481  *
 482  *    Formatting:    SILC_STR_SINT64(SilcInt64)
 483  *    Unformatting:  SILC_STR_SINT64(SilcInt64 *)
 484  *
 485  ***/
 486 #define SILC_STR_SI_INT64(x) SILC_PARAM_SINT64, (x)
 487
 488 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_UINT64
 489  *
 490  * NAME
 491  *
 492  *    #define SILC_STR_UINT64() ...
 493  *
 494  * DESCRIPTION
 495  *
 496  *    SilcUInt64.
 497  *
 498  *    Formatting:    SILC_STR_UINT64(SilcUInt64)
 499  *    Unformatting:  SILC_STR_UINT64(SilcUInt64 *)
 500  *
 501  ***/
 502 #define SILC_STR_UI_INT64(x) SILC_PARAM_UINT64, (x)
 503
 504 /* Deprecated */
 505 #define SILC_STR_SI_INT64(x) SILC_PARAM_SINT64, (x)
 506 #define SILC_STR_UI_INT64(x) SILC_PARAM_UINT64, (x)
 507
 508 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_STRING
 509  *
 510  * NAME
 511  *
 512  *    #define SILC_STR_STRING() ...
 513  *
 514  * DESCRIPTION
 515  *
 516  *    Encode NULL terminated string.  Use this only for formatting.
 517  *
 518  *    Formatting:  SILC_STR_STRING(char *)
 519  *
 520  *    For unformatting use one of the SILC_STR_*_STRING macros, which
 521  *    automatically gets the length of the string from the buffer.  Note
 522  *    SILC_STR_STRING does not save the length of the string into the buffer.
 523  *    The caller must do that in order for the unformatting macros to work.
 524  *
 525  *    Example:
 526  *
 527  *    Formatting:    ..., SILC_STR_UINT32(strlen(string)),
 528  *                        SILC_STR_STRING(string), ...
 529  *    Unformatting:  ..., SILC_STR_UI32_STRING(&string), ...
 530  *
 531  ***/
 532 #define SILC_STR_STRING(x) SILC_PARAM_UI8_STRING, (x)
 533
 534 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_*_STRING
 535  *
 536  * NAME
 537  *
 538  *    #define SILC_STR_UI8_STRING() ...
 539  *    #define SILC_STR_UI8_STRING_ALLOC() ...
 540  *    #define SILC_STR_UI16_STRING() ...
 541  *    #define SILC_STR_UI16_STRING_ALLOC() ...
 542  *    #define SILC_STR_UI32_STRING() ...
 543  *    #define SILC_STR_UI32_STRING_ALLOC() ...
 544  *
 545  * DESCRIPTION
 546  *
 547  *    Unsigned NULL terminated string. Note that the string must be
 548  *    NULL terminated because strlen() will be used to get the length of
 549  *    the string.
 550  *
 551  *    Formatting:    SILC_STR_UI32_STRING(unsigned char *)
 552  *    Unformatting:  SILC_STR_UI32_STRING(unsigned char **)
 553  *
 554  *    Unformatting procedure will check for length of the string from the
 555  *    buffer before trying to get the string out. Thus, one *must* format the
 556  *    length as UINT32 or UINT16 or UINT8 into the buffer *before* formatting
 557  *    the actual string to the buffer, and, in unformatting one ignores the
 558  *    length of the string because unformatting procedure will take it
 559  *    automatically.
 560  *
 561  *    Example:
 562  *
 563  *    Formatting:    ..., SILC_STR_UINT32(strlen(string)),
 564  *                        SILC_STR_UI32_STRING(string), ...
 565  *    Unformatting:  ..., SILC_STR_UI32_STRING(&string), ...
 566  *
 567  *    I.e., you can ignore the formatted length field in unformatting.
 568  *
 569  *    UI8, UI16 and UI32 means that the length is considered to be
 570  *    either UINT8, UINT16 or UINT32 in unformatting.
 571  *
 572  *    _ALLOC routines automatically allocates memory for the variable sent
 573  *    as argument in unformatting.
 574  *
 575  ***/
 576 #define SILC_STR_UI8_STRING(x) SILC_PARAM_UI8_STRING, (x)
 577 #define SILC_STR_UI8_STRING_ALLOC(x) SILC_PARAM_UI8_STRING | SILC_PARAM_ALLOC, (x)
 578 #define SILC_STR_UI16_STRING(x) SILC_PARAM_UI16_STRING, (x)
 579 #define SILC_STR_UI16_STRING_ALLOC(x) SILC_PARAM_UI16_STRING | SILC_PARAM_ALLOC, (x)
 580 #define SILC_STR_UI32_STRING(x) SILC_PARAM_UI32_STRING, (x)
 581 #define SILC_STR_UI32_STRING_ALLOC(x) SILC_PARAM_UI32_STRING | SILC_PARAM_ALLOC, (x)
 582
 583 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_*_NSTRING
 584  *
 585  * NAME
 586  *
 587  *    #define SILC_STR_UI8_NSTRING() ...
 588  *    #define SILC_STR_UI8_NSTRING_ALLOC() ...
 589  *    #define SILC_STR_UI16_NSTRING() ...
 590  *    #define SILC_STR_UI16_NSTRING_ALLOC() ...
 591  *    #define SILC_STR_UI32_NSTRING() ...
 592  *    #define SILC_STR_UI32_NSTRING_ALLOC() ...
 593  *
 594  * DESCRIPTION
 595  *
 596  *    Unsigned string. Second argument is the length of the string.
 597  *
 598  *    Formatting:    SILC_STR_UI32_NSTRING(unsigned char *, SilcUInt32)
 599  *    Unformatting:  SILC_STR_UI32_NSTRING(unsigned char **, SilcUInt32 *)
 600  *
 601  *    Unformatting procedure will check for length of the string from the
 602  *    buffer before trying to get the string out. Thus, one *must* format the
 603  *    length as UINT32 or UINT16 or UINT8 into the buffer *before* formatting
 604  *    the actual string to the buffer, and, in unformatting one ignores the
 605  *    length of the string because unformatting procedure will take it
 606  *    automatically.
 607  *
 608  *     Example:
 609  *
 610  *     Formatting:    ..., SILC_STR_UINT32(strlen(string)),
 611  *                         SILC_STR_UI32_NSTRING(string, strlen(string)), ...
 612  *     Unformatting:  ..., SILC_STR_UI32_NSTRING(&string, &len), ...
 613  *
 614  *    I.e., you can ignore the formatted length field in unformatting. The
 615  *    length taken from the buffer is returned to the pointer sent as
 616  *    argument (&len in above example).
 617  *
 618  *    UI8, UI16 and UI32 means that the length is considered to be
 619  *    either UINT8, UINT16 or UINT32 in unformatting.
 620  *
 621  *    _ALLOC routines automatically allocates memory for the variable sent
 622  *    as argument in unformatting.
 623  *
 624  ***/
 625 #define SILC_STR_UI8_NSTRING(x, l) SILC_PARAM_UI8_NSTRING, (x), (l)
 626 #define SILC_STR_UI8_NSTRING_ALLOC(x, l) \
 627   SILC_PARAM_UI8_NSTRING | SILC_PARAM_ALLOC, (x), (l)
 628 #define SILC_STR_UI16_NSTRING(x, l) SILC_PARAM_UI16_NSTRING, (x), (l)
 629 #define SILC_STR_UI16_NSTRING_ALLOC(x, l) \
 630   SILC_PARAM_UI16_NSTRING | SILC_PARAM_ALLOC, (x), (l)
 631 #define SILC_STR_UI32_NSTRING(x, l) SILC_PARAM_UI32_NSTRING, (x), (l)
 632 #define SILC_STR_UI32_NSTRING_ALLOC(x, l) \
 633   SILC_PARAM_UI32_NSTRING | SILC_PARAM_ALLOC, (x), (l)
 634
 635 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_DATA
 636  *
 637  * NAME
 638  *
 639  *    #define SILC_STR_DATA() ...
 640  *    #define SILC_STR_DATA_ALLOC() ...
 641  *
 642  * DESCRIPTION
 643  *
 644  *    Binary data formatting.  Second argument is the length of the data.
 645  *
 646  *    Formatting:    SILC_STR_DATA(unsigned char *, SilcUInt32)
 647  *    Unformatting:  SILC_STR_DATA(unsigned char **, SilcUInt32)
 648  *
 649  *    This type can be used to take arbitrary size data block from the buffer
 650  *    by sending the requested amount of bytes as argument.
 651  *
 652  *    _ALLOC routines automatically allocates memory for the variable sent
 653  *    as argument in unformatting.
 654  *
 655  ***/
 656 #define SILC_STR_DATA(x, l) SILC_PARAM_UICHAR, (x), (l)
 657 #define SILC_STR_DATA_ALLOC(x, l) SILC_PARAM_UICHAR | SILC_PARAM_ALLOC, (x), (l)
 658
 659 /* Deprecated */
 660 #define SILC_STR_UI_XNSTRING(x, l) SILC_PARAM_UICHAR, (x), (l)
 661 #define SILC_STR_UI_XNSTRING_ALLOC(x, l) SILC_PARAM_UICHAR | SILC_PARAM_ALLOC, (x), (l)
 662
 663 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_BUFFER
 664  *
 665  * NAME
 666  *
 667  *    #define SILC_STR_BUFFER() ...
 668  *    #define SILC_STR_BUFFER_ALLOC() ...
 669  *
 670  * DESCRIPTION
 671  *
 672  *    SilcBuffer formatting.
 673  *
 674  *    Formatting:    SILC_STR_BUFFER(SilcBuffer)
 675  *    Unformatting:  SILC_STR_BUFFER(SilcBuffer)
 676  *
 677  *    This type can be used to format and unformat SilcBuffer.  Note that, the
 678  *    length of the buffer will be automatically encoded into the buffer as
 679  *    a 32-bit integer.  In unformatting the SilcBuffer context must be
 680  *    pre-allocated.
 681  *
 682  *    _ALLOC routines automatically allocates memory inside SilcBuffer in
 683  *    unformatting.
 684  *
 685  ***/
 686 #define SILC_STR_BUFFER(x) SILC_PARAM_BUFFER, (x)
 687 #define SILC_STR_BUFFER_ALLOC(x) SILC_PARAM_BUFFER | SILC_PARAM_ALLOC, (x)
 688
 689 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_REPLACE
 690  *
 691  * NAME
 692  *
 693  *    #define SILC_STR_REPLACE(unsigned char *data, SilcUInt32 len) ...
 694  *
 695  * DESCRIPTION
 696  *
 697  *    Encode the `data' of length of `len' bytes into the buffer, replacing
 698  *    existing data.
 699  *
 700  *    If the length of the current data area is equal to `len' the data area
 701  *    is replaced with `data'.
 702  *
 703  *    If `len' is longer than the data area, it will be enlarged to fit the
 704  *    `data'.  If there is data in the tail area, it will not be replaced,
 705  *    but the buffer is enlarged and the old tail area will be copied to the
 706  *    new tail area, thus preserving any data in the buffer (the data is
 707  *    in effect appended to the current data area).
 708  *
 709  *    If `len' is shorter than than the data area, only the bytes in `data'
 710  *    are replaced, and rest are deleted from the data area.  The buffer size
 711  *    is also reduced but no other data is lost in the process.
 712  *
 713  *    If `len' is 0 but `data' is non-NULL, this will delete all bytes from
 714  *    the current data area.  If `data' is NULL this macro has no effect to
 715  *    the buffer.
 716  *
 717  *    Use this only for formatting.
 718  *
 719  *    Formatting:  SILC_STR_REPLACE(unsigned char *, SilcUInt32)
 720  *
 721  *    Example:
 722  *
 723  *    Before replacing
 724  *    -------------------------
 725  *    | head  | 12345 | 67890 |
 726  *    -------------------------
 727  *
 728  *    After replacing with 12345XXX (appends)
 729  *    ----------------------------
 730  *    | head  | 12345XXX | 67890 |
 731  *    ----------------------------
 732  *
 733  *    After replacing with YYY (deletes)
 734  *    -----------------------
 735  *    | head  | YYY | 67890 |
 736  *    -----------------------
 737  *
 738  ***/
 739 #define SILC_STR_REPLACE(x, l) SILC_PARAM_UICHAR | SILC_PARAM_REPLACE, (x), (l)
 740
 741 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_FUNC
 742  *
 743  * NAME
 744  *
 745  *    #define SILC_STR_FUNC() ...
 746  *
 747  * DESCRIPTION
 748  *
 749  *    Formatting and unformatting of arbitrary data.
 750  *
 751  *    Formatting:    SILC_STR_FUNC(function, void *value, void *context)
 752  *    Unformatting:  SILC_STR_FUNC(function, void **value, void *context)
 753  *
 754  *    This type can be used to call the `function' of the type
 755  *    SilcBufferFormatFunc or SilcBufferUnformatFunc to encode or decode
 756  *    the `value'.  In encoding the `value' will be passed to the `function'
 757  *    and can be encoded into the buffer.  The buffer will be passed as
 758  *    well to the `function' at the location where SILC_STR_FUNC is placed
 759  *    in formatting.  The `context' delivers caller specific context to
 760  *    the `function'
 761  *
 762  *    In unformatting the `function' will decode the encoded type and
 763  *    return it to `value' pointer.  The decoding function should decide
 764  *    itself whether to allocate or not the decoded value.
 765  *
 766  *    The `function' does not have to encode anything and passing `value'
 767  *    as NULL is allowed.  The `function' could for example modify the
 768  *    existing buffer.
 769  *
 770  * EXAMPLE
 771  *
 772  *    // Encode payload, encrypt and compute MAC.
 773  *    silc_buffer_format(buf,
 774  *                       SILC_STR_FUNC(foo_encode_id, id, ctx),
 775  *                       SILC_STR_UINT16(len),
 776  *                       SILC_STR_DATA(data, len),
 777  *                       SILC_STR_FUNC(foo_buf_encrypt, NULL, key),
 778  *                       SILC_STR_FUNC(foo_buf_hmac, NULL, hmac),
 779  *                       SILC_STR_DATA(iv, iv_len);
 780  *                       SILC_STR_END);
 781  *
 782  *    // Check MAC, decrypt and decode payload
 783  *    silc_buffer_unformat(buf,
 784  *                         SILC_STR_FUNC(foo_buf_hmac, NULL, hmac),
 785  *                         SILC_STR_FUNC(foo_buf_decrypt, NULL, key),
 786  *                         SILC_STR_FUNC(foo_decode_id, &id, ctx),
 787  *                         SILC_STR_UINT16(&len),
 788  *                         SILC_STR_END);
 789  *
 790  ***/
 791 #define SILC_STR_FUNC(func, val, context) SILC_PARAM_FUNC, \
 792     func, (val), (context)
 793
 794 /****d* silcutil/SilcBufferFormatAPI/SilcBufferRegexFlags
 795  *
 796  * NAME
 797  *
 798  *    typedef enum { ... } SilcBufferRegexFlags;
 799  *
 800  * DESCRIPTION
 801  *
 802  *    Regular expression flags for SILC_STR_REGEX macro.  The flags can be
 803  *    used to manipulate the behavior of the SILC_STR_REGEX.  All flags
 804  *    may be combined unless otherwise stated.
 805  *
 806  * SOURCE
 807  */
 808 typedef enum {
 809   SILC_STR_REGEX_NONE                 = 0x00000000,
 810
 811   /* By default mismatch will be skipped.  Skipping means that none of the
 812      operations inside the SILC_STR_REGEX are executed.  Set this flag if
 813      mismatch should cause error and stopping of the formatting/unformatting. */
 814   SILC_STR_REGEX_MISMATCH             = 0x00000001,
 815
 816   /* By default only the first match is found.  Set this flag to find
 817      all matches. */
 818   SILC_STR_REGEX_ALL                  = 0x00000002,
 819
 820   /* By default the buffer position is advanced to the position of the
 821      first match.  Set this flag if the buffer should not be advanced to
 822      the match. */
 823   SILC_STR_REGEX_NO_ADVANCE           = 0x00000004,
 824
 825   /* By default SILC_STR_REGEX performs the match on the whole buffer.  Set
 826      this flag to make it behave like sed and match line by line.  Each line
 827      must end with '\n'.  If buffer doesn't have '\n' it is considered to be
 828      one line.  Note that, any formatting done immediately after SILC_STR_REGEX
 829      block with this flag will be formatted to the end of the buffer (after
 830      last line).  Use SILC_STR_OFFSET* macros to change the position if
 831      needed.  Also note that, any encoding macro inside the SILC_STR_REGEX
 832      block will see only the matched line (including '\n'), instead of whole
 833      buffer after the match. */
 834   SILC_STR_REGEX_NL                   = 0x00000008,
 835
 836   /* Set this flag to not match the regular expression, but to match everything
 837      else.  When combined with SILC_STR_REGEX_NL this flag matches all other
 838      lines except the ones with matching regular expression. */
 839   SILC_STR_REGEX_NOT                  = 0x00000010,
 840
 841   /* By default the buffer is advanced to the first match and the rest of the
 842      buffer remains as is.  Set this flag to pass the exact match to the
 843      SILC_STR_* macros in the SILC_STR_REGEX block; macros see the start of
 844      the match and the end of the match, but not rest of the buffer (ie. with
 845      match 'foo' the size of the buffer is 3 bytes). */
 846   SILC_STR_REGEX_INCLUSIVE            = 0x00000020,
 847 } SilcBufferRegexFlags;
 848 /***/
 849
 850 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_REGEX
 851  *
 852  * NAME
 853  *
 854  *    #define SILC_STR_REGEX() ...
 855  *
 856  * DESCRIPTION
 857  *
 858  *    Regular expression matching within the buffer.
 859  *
 860  *    Formatting:    SILC_STR_REGEX(char *regex, SilcBufferRegexFlags flags)
 861  *    Unformatting:  SILC_STR_REGEX(char *regex, SilcBufferRegexFlags flags)
 862  *
 863  *    SILC_STR_REGEX can be used to do regular expression matching within
 864  *    the SilcBuffer.  When the string in the buffer matches the regular
 865  *    expression the position of the buffer is advanced to the position of
 866  *    the first match (rest of the buffer remains intact).  If the regular
 867  *    expression does not match it is skipped, unless the flags specify
 868  *    otherwise.  If flags are not needed they can be set to 0.
 869  *
 870  *    In addition of matching regular expressions it can be used in a
 871  *    Stream Editor (sed) and Awk like fashion.  The regular expression can be
 872  *    matched and then edited by any of the SILC_STR_* macros.  The flags
 873  *    can be used to perform complex operations on the data.  Some sed
 874  *    features that cannot be directly done with the flags can be done with
 875  *    SILC_STR_FUNC and other macros (the SILC_STR_FUNC could do anything
 876  *    after the match).
 877  *
 878  *    The SILC_STR_REGEX itself is used as an opening of a block of encoding
 879  *    macros and must be closed with SILC_STR_END.  This means that for
 880  *    each SILC_STR_REGEX there must be one SILC_STR_END.  See examples for
 881  *    more information.
 882  *
 883  *    The SILC_STR_REGEX can be used in buffer unformatting also to do
 884  *    string matching and parsing, but not editing, except with SILC_STR_FUNC
 885  *    macro, which can do anything caller wants.
 886  *
 887  *    Typically the following encoding macros are used with SILC_STR_REGEX:
 888  *    SILC_STR_REPLACE, SILC_STR_STRING and SILC_STR_FUNC.  If you use
 889  *    SILC_STR_REPLACE always set SILC_STR_REGEX_INCLUSIVE.
 890  *
 891  * EXAMPLE
 892  *
 893  *    // sed 's/foo/bar/', replace first foo with bar
 894  *    silc_buffer_format(buffer,
 895  *                       SILC_STR_REGEX("foo", 0),
 896  *                         SILC_STR_STRING("bar"),
 897  *                       SILC_STR_END, SILC_STR_END);
 898  *
 899  *    // sed 's/foo/barbar/g', replace all foo's with barbar, without
 900  *    // overwriting any data in the buffer, but appending it.  The match
 901  *    // must be inclusive to make appending work.
 902  *    silc_buffer_format(buffer,
 903  *                       SILC_STR_REGEX("foo", SILC_STR_REGEX_ALL |
 904  *                                             SILC_STR_REGEX_INCLUSIVE),
 905  *                         SILC_STR_REPLACE("barbar", 5),
 906  *                       SILC_STR_END, SILC_STR_END);
 907  *
 908  *    // sed 's/foo/B/', replace foo with B, deleting rest of the match from
 909  *    // the buffer.  The match must be inclusive to make deleting work.
 910  *    silc_buffer_format(buffer,
 911  *                       SILC_STR_REGEX("foo", SILC_STR_REGEX_ALL |
 912  *                                             SILC_STR_REGEX_INCLUSIVE),
 913  *                         SILC_STR_REPLACE("B", 1),
 914  *                       SILC_STR_END, SILC_STR_END);
 915  *
 916  *    // sed '/baz/s/foo/bar/g, replace all foo's with bar on lines with baz
 917  *    silc_buffer_format(buffer,
 918  *                       SILC_STR_REGEX("baz", SILC_STR_REGEX_NL),
 919  *                         SILC_STR_REGEX("foo", SILC_STR_REGEX_ALL),
 920  *                           SILC_STR_STRING("bar"),
 921  *                         SILC_STR_END,
 922  *                       SILC_STR_END, SILC_STR_END);
 923  *
 924  *    // Print all lines that start with 'R'
 925  *    int print(SilcStack stack, SilcBuffer buf, void *value, void *context)
 926  *    {
 927  *      return fwrite(silc_buffer_data(buf), 1, silc_buffer_len(buf), stdout);
 928  *    }
 929  *
 930  *    silc_buffer_unformat(buffer,
 931  *                         SILC_STR_REGEX("^R", SILC_STR_REGEX_NL),
 932  *                           SILC_STR_FUNC(print, NULL, NULL),
 933  *                         SILC_STR_END, SILC_STR_END);
 934  *
 935  ***/
 936 #define SILC_STR_REGEX(regex, flags) SILC_PARAM_REGEX, (regex), (flags)
 937
 938 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_DELETE
 939  *
 940  * NAME
 941  *
 942  *    #define SILC_STR_DELETE(n) ...
 943  *
 944  * DESCRIPTION
 945  *
 946  *    Deletes bytes from the buffer by moving data in order to delete it.
 947  *    The size of the buffer is also reduced, but no data is lost in the
 948  *    process.
 949  *
 950  *    The `n' specifies the number of bytes to delete from the current
 951  *    data area.  If `n' is -1 this deletes all bytes from the data area.
 952  *    This effectively moves the data from the tail area into the current
 953  *    data area.  The length of the data area after this is 0.
 954  *
 955  *    Use this only for formatting.
 956  *
 957  *    Formatting:  SILC_STR_DELETE(int bytes)
 958  *
 959  ***/
 960 #define SILC_STR_DELETE(x) SILC_PARAM_DELETE, (x)
 961
 962 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_OFFSET
 963  *
 964  * NAME
 965  *
 966  *    #define SILC_STR_OFFSET() ...
 967  *
 968  * DESCRIPTION
 969  *
 970  *    Offset in buffer.  This can be used in formatting and unformatting to
 971  *    move the data pointer of the buffer either forwards (positive offset)
 972  *    or backwards (negative offset).  It can be used to for example skip
 973  *    some types during unformatting.
 974  *
 975  *    Example:
 976  *
 977  *    ..., SILC_STR_OFFSET(5), ...
 978  *    ..., SILC_STR_OFFSET(-3), ...
 979  *
 980  *    Moves the data pointer at the point of the offset either forward
 981  *    or backward and then moves to the next type.  Multiple SILC_STR_OFFSETs
 982  *    can be used in formatting and unformatting at the same time.
 983  *
 984  ***/
 985 #define SILC_STR_OFFSET(x) SILC_PARAM_OFFSET, (x)
 986
 987 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_OFFSET_START
 988  *
 989  * NAME
 990  *
 991  *    #define SILC_STR_OFFSET_START ...
 992  *
 993  * DESCRIPTION
 994  *
 995  *    Moves the buffer position to the start of the data area.
 996  *
 997  *    Example:
 998  *
 999  *    ..., SILC_STR_OFFSET_START, ...
1000  *
1001  ***/
1002 #define SILC_STR_OFFSET_START SILC_PARAM_OFFSET_START
1003
1004 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_OFFSET_END
1005  *
1006  * NAME
1007  *
1008  *    #define SILC_STR_OFFSET_END ...
1009  *
1010  * DESCRIPTION
1011  *
1012  *    Moves the buffer position to the end of the data area.
1013  *
1014  *    Example:
1015  *
1016  *    ..., SILC_STR_OFFSET_END, ...
1017  *
1018  ***/
1019 #define SILC_STR_OFFSET_END SILC_PARAM_OFFSET_END
1020
1021 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_ADVANCE
1022  *
1023  * NAME
1024  *
1025  *    #define SILC_STR_ADVANCE ...
1026  *
1027  * DESCRIPTION
1028  *
1029  *    Advance the buffer to the end of the data after the formatting is
1030  *    done.  In normal operation when the formatted data is written the
1031  *    buffer is positioned at the start of the data.  With SILC_STR_ADVANCE
1032  *    the buffer will be positioned at the end of the data.  This makes it
1033  *    easy to add new data immediately after the previously added data.
1034  *    The SILC_STR_ADVANCE may also be used in unformatting.
1035  *
1036  * EXAMPLE
1037  *
1038  *    do {
1039  *      len = read(fd, buf, sizeof(buf));
1040  *      if (len > 0)
1041  *        // Add read data to the buffer
1042  *        silc_buffer_format(buffer,
1043  *                           SILC_STR_ADVANCE,
1044  *                           SILC_STR_DATA(buf, len),
1045  *                           SILC_STR_END);
1046  *    } while (len > 0);
1047  *
1048  *    // Move to beginning of buffer
1049  *    silc_buffer_start(buffer);
1050  *
1051  ***/
1052 #define SILC_STR_ADVANCE SILC_PARAM_ADVANCE
1053
1054 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_END
1055  *
1056  * NAME
1057  *
1058  *    #define SILC_STR_END ...
1059  *
1060  * DESCRIPTION
1061  *
1062  *    Marks end of the argument list. This must be at the end of the
1063  *    argument list or error will occur.
1064  *
1065  ***/
1066 #define SILC_STR_END SILC_PARAM_END
1067
1068 /****d* silcutil/SilcBufferFormatAPI/SILC_STRFMT_END
1069  *
1070  * NAME
1071  *
1072  *    #define SILC_STRFMT_END ...
1073  *
1074  * DESCRIPTION
1075  *
1076  *    Marks end of the argument list in silc_buffer_strformat function.
1077  *    This must be at the end of the argument list or error will occur.
1078  *
1079  ***/
1080 #define SILC_STRFMT_END (void *)SILC_STR_END
1081
1082 #endif  /* !SILCBUFFMT_H */