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_FUNC
 690  *
 691  * NAME
 692  *
 693  *    #define SILC_STR_FUNC() ...
 694  *
 695  * DESCRIPTION
 696  *
 697  *    Formatting and unformatting of arbitrary data.
 698  *
 699  *    Formatting:    SILC_STR_FUNC(function, void *value, void *context)
 700  *    Unformatting:  SILC_STR_FUNC(function, void **value, void *context)
 701  *
 702  *    This type can be used to call the `function' of the type
 703  *    SilcBufferFormatFunc or SilcBufferUnformatFunc to encode or decode
 704  *    the `value'.  In encoding the `value' will be passed to the `function'
 705  *    and can be encoded into the buffer.  The buffer will be passed as
 706  *    well to the `function' at the location where SILC_STR_FUNC is placed
 707  *    in formatting.  The `context' delivers caller specific context to
 708  *    the `function'
 709  *
 710  *    In unformatting the `function' will decode the encoded type and
 711  *    return it to `value' pointer.  The decoding function should decide
 712  *    itself whether to allocate or not the decoded value.
 713  *
 714  *    The `function' does not have to encode anything and passing `value'
 715  *    as NULL is allowed.  The `function' could for example modify the
 716  *    existing buffer.
 717  *
 718  * EXAMPLE
 719  *
 720  *    // Encode payload, encrypt and compute MAC.
 721  *    silc_buffer_format(buf,
 722  *                       SILC_STR_FUNC(foo_encode_id, id, ctx),
 723  *                       SILC_STR_UINT16(len),
 724  *                       SILC_STR_DATA(data, len),
 725  *                       SILC_STR_FUNC(foo_buf_encrypt, NULL, key),
 726  *                       SILC_STR_FUNC(foo_buf_hmac, NULL, hmac),
 727  *                       SILC_STR_DATA(iv, iv_len);
 728  *                       SILC_STR_END);
 729  *
 730  *    // Check MAC, decrypt and decode payload
 731  *    silc_buffer_unformat(buf,
 732  *                         SILC_STR_FUNC(foo_buf_hmac, NULL, hmac),
 733  *                         SILC_STR_FUNC(foo_buf_decrypt, NULL, key),
 734  *                         SILC_STR_FUNC(foo_decode_id, &id, ctx),
 735  *                         SILC_STR_UINT16(&len),
 736  *                         SILC_STR_END);
 737  *
 738  ***/
 739 #define SILC_STR_FUNC(func, val, context) SILC_PARAM_FUNC, \
 740     func, (val), (context)
 741
 742 /****d* silcutil/SilcBufferFormatAPI/SilcBufferRegexFlags
 743  *
 744  * NAME
 745  *
 746  *    typedef enum { ... } SilcBufferRegexFlags;
 747  *
 748  * DESCRIPTION
 749  *
 750  *    Regular expression flags for SILC_STR_REGEX macro.  The flags can be
 751  *    used to manipulate the behavior of the SILC_STR_REGEX.  All flags
 752  *    may be combined unless otherwise stated.
 753  *
 754  * SOURCE
 755  */
 756 typedef enum {
 757   SILC_STR_REGEX_NONE                 = 0x00000000,
 758
 759   /* By default mismatch will be skipped.  Set this flag if mismatch should
 760      cause error and stopping of the formatting/unformatting. */
 761   SILC_STR_REGEX_MISMATCH             = 0x00000001,
 762
 763   /* By default only the first match is found.  Set this flag to find
 764      all matches. */
 765   SILC_STR_REGEX_ALL                  = 0x00000002,
 766
 767   /* By default the buffer position is advanced to the position of the
 768      first match.  Set this flag if the buffer should not be advanced to
 769      the match. */
 770   SILC_STR_REGEX_NO_ADVANCE           = 0x00000004,
 771
 772   /* By default SILC_STR_REGEX performs the match on the whole buffer.  Set
 773      this flag to make it behave like sed and match line by line.  Each line
 774      must end with '\n'.  If buffer doesn't have '\n' it is considered to be
 775      one line.  Note that, any formatting done immediately after SILC_STR_REGEX
 776      block with this flag will be formatted to the end of the buffer (after
 777      last line).  Use SILC_STR_OFFSET* macros to change the position if
 778      needed.  Also note that, any encoding macro inside the SILC_STR_REGEX
 779      block will see only the matched line (including '\n'), instead of whole
 780      buffer after the match. */
 781   SILC_STR_REGEX_NL                   = 0x00000008,
 782
 783   /* Set this flag to not match the regular expression, but to match everything
 784      else.  When combined with SILC_STR_REGEX_NL this flag matches all other
 785      lines except the ones with matching regular expression. */
 786   SILC_STR_REGEX_NOT                  = 0x00000010,
 787
 788   /* By default the buffer is advanced to the first match and the rest of the
 789      buffer remains as is.  Set this flag to pass the exact match to the
 790      SILC_STR_* macros in the SILC_STR_REGEX block; macros see the start of
 791      the match and the end of the match, but not rest of the buffer (ie. with
 792      match 'foo' the size of the buffer is 3 bytes). */
 793   SILC_STR_REGEX_INCLUSIVE            = 0x00000020,
 794 } SilcBufferRegexFlags;
 795 /***/
 796
 797 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_REGEX
 798  *
 799  * NAME
 800  *
 801  *    #define SILC_STR_REGEX() ...
 802  *
 803  * DESCRIPTION
 804  *
 805  *    Regular expression matching within the buffer.
 806  *
 807  *    Formatting:    SILC_STR_REGEX(char *regex, SilcBufferRegexFlags flags)
 808  *    Unformatting:  SILC_STR_REGEX(char *regex, SilcBufferRegexFlags flags)
 809  *
 810  *    SILC_STR_REGEX can be used to do regular expression matching within
 811  *    the SilcBuffer.  When the string in the buffer matches the regular
 812  *    expression the position of the buffer is advanced to the position of
 813  *    the first match (rest of the buffer remains intact).  If the regular
 814  *    expression does not match it is skipped, unless the flags specify
 815  *    otherwise.  If flags are not needed they can be set to 0.
 816  *
 817  *    In addition of matching regular expressions it can be used in a
 818  *    Stream Editor (sed) and Awk like fashion.  The regular expression can be
 819  *    matched and then edited by any of the SILC_STR_* macros.  The flags
 820  *    can be used to perform complex operations on the data.  Some sed
 821  *    features that cannot be directly done with the flags can be done with
 822  *    SILC_STR_FUNC and other macros (the SILC_STR_FUNC could do anything
 823  *    after the match).
 824  *
 825  *    The SILC_STR_REGEX itself is used as an opening of a block of encoding
 826  *    macros and must be closed with SILC_STR_END.  This means that for
 827  *    each SILC_STR_REGEX there must be one SILC_STR_END.  See examples for
 828  *    more information.
 829  *
 830  *    The SILC_STR_REGEX can be used in buffer unformatting also to do
 831  *    string matching and parsing, but not editing, except with SILC_STR_FUNC
 832  *    macro, which can do anything caller wants.
 833  *
 834  * EXAMPLE
 835  *
 836  *    // sed 's/foo/bar/', replace first foo with bar
 837  *    silc_buffer_format(buffer,
 838  *                       SILC_STR_REGEX("foo", 0),
 839  *                         SILC_STR_STRING("bar"),
 840  *                       SILC_STR_END, SILC_STR_END);
 841  *
 842  *    // sed 's/foo/bar/g', replace all foo's with bar
 843  *    silc_buffer_format(buffer,
 844  *                       SILC_STR_REGEX("foo", SILC_STR_REGEX_ALL),
 845  *                         SILC_STR_STRING("bar"),
 846  *                       SILC_STR_END, SILC_STR_END);
 847  *
 848  *    // sed '/baz/s/foo/bar/g, replace all foo's with bar on lines with baz
 849  *    silc_buffer_format(buffer,
 850  *                       SILC_STR_REGEX("baz", SILC_STR_REGEX_NL),
 851  *                         SILC_STR_REGEX("foo", SILC_STR_REGEX_ALL),
 852  *                           SILC_STR_STRING("bar"),
 853  *                         SILC_STR_END,
 854  *                       SILC_STR_END, SILC_STR_END);
 855  *
 856  *    // Print all lines that start with 'R'
 857  *    int print(SilcStack stack, SilcBuffer buf, void *value, void *context)
 858  *    {
 859  *      return fwrite(silc_buffer_data(buf), 1, silc_buffer_len(buf), stdout);
 860  *    }
 861  *
 862  *    silc_buffer_unformat(buffer,
 863  *                         SILC_STR_REGEX("^R", SILC_STR_REGEX_NL),
 864  *                           SILC_STR_FUNC(print, NULL, NULL),
 865  *                         SILC_STR_END, SILC_STR_END);
 866  *
 867  ***/
 868 #define SILC_STR_REGEX(regex, flags) SILC_PARAM_REGEX, (regex), (flags)
 869
 870 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_OFFSET
 871  *
 872  * NAME
 873  *
 874  *    #define SILC_STR_OFFSET() ...
 875  *
 876  * DESCRIPTION
 877  *
 878  *    Offset in buffer.  This can be used in formatting and unformatting to
 879  *    move the data pointer of the buffer either forwards (positive offset)
 880  *    or backwards (negative offset).  It can be used to for example skip
 881  *    some types during unformatting.
 882  *
 883  *    Example:
 884  *
 885  *    ..., SILC_STR_OFFSET(5), ...
 886  *    ..., SILC_STR_OFFSET(-3), ...
 887  *
 888  *    Moves the data pointer at the point of the offset either forward
 889  *    or backward and then moves to the next type.  Multiple SILC_STR_OFFSETs
 890  *    can be used in formatting and unformatting at the same time.
 891  *
 892  ***/
 893 #define SILC_STR_OFFSET(x) SILC_PARAM_OFFSET, (x)
 894
 895 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_OFFSET_START
 896  *
 897  * NAME
 898  *
 899  *    #define SILC_STR_OFFSET_START ...
 900  *
 901  * DESCRIPTION
 902  *
 903  *    Moves the buffer position to the start of the data area.
 904  *
 905  *    Example:
 906  *
 907  *    ..., SILC_STR_OFFSET_START, ...
 908  *
 909  ***/
 910 #define SILC_STR_OFFSET_START SILC_PARAM_OFFSET_START
 911
 912 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_OFFSET_END
 913  *
 914  * NAME
 915  *
 916  *    #define SILC_STR_OFFSET_END ...
 917  *
 918  * DESCRIPTION
 919  *
 920  *    Moves the buffer position to the end of the data area.
 921  *
 922  *    Example:
 923  *
 924  *    ..., SILC_STR_OFFSET_END, ...
 925  *
 926  ***/
 927 #define SILC_STR_OFFSET_END SILC_PARAM_OFFSET_END
 928
 929 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_ADVANCE
 930  *
 931  * NAME
 932  *
 933  *    #define SILC_STR_ADVANCE ...
 934  *
 935  * DESCRIPTION
 936  *
 937  *    Advance the buffer to the end of the data after the formatting is
 938  *    done.  In normal operation when the formatted data is written the
 939  *    buffer is positioned at the start of the data.  With SILC_STR_ADVANCE
 940  *    the buffer will be positioned at the end of the data.  This makes it
 941  *    easy to add new data immediately after the previously added data.
 942  *    The SILC_STR_ADVANCE may also be used in unformatting.
 943  *
 944  * EXAMPLE
 945  *
 946  *    do {
 947  *      len = read(fd, buf, sizeof(buf));
 948  *      if (len > 0)
 949  *        // Add read data to the buffer
 950  *        silc_buffer_format(buffer,
 951  *                           SILC_STR_ADVANCE,
 952  *                           SILC_STR_DATA(buf, len),
 953  *                           SILC_STR_END);
 954  *    } while (len > 0);
 955  *
 956  *    // Move to beginning of buffer
 957  *    silc_buffer_start(buffer);
 958  *
 959  ***/
 960 #define SILC_STR_ADVANCE SILC_PARAM_ADVANCE
 961
 962 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_END
 963  *
 964  * NAME
 965  *
 966  *    #define SILC_STR_END ...
 967  *
 968  * DESCRIPTION
 969  *
 970  *    Marks end of the argument list. This must be at the end of the
 971  *    argument list or error will occur.
 972  *
 973  ***/
 974 #define SILC_STR_END SILC_PARAM_END
 975
 976 /****d* silcutil/SilcBufferFormatAPI/SILC_STRFMT_END
 977  *
 978  * NAME
 979  *
 980  *    #define SILC_STRFMT_END ...
 981  *
 982  * DESCRIPTION
 983  *
 984  *    Marks end of the argument list in silc_buffer_strformat function.
 985  *    This must be at the end of the argument list or error will occur.
 986  *
 987  ***/
 988 #define SILC_STRFMT_END (void *)SILC_STR_END
 989
 990 #endif  /* !SILCBUFFMT_H */