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_APPEND
 535  *
 536  * NAME
 537  *
 538  *    #define SILC_STR_STRING_APPEND() ...
 539  *
 540  * DESCRIPTION
 541  *
 542  *    Encode NULL terminated string and append it to the buffer without
 543  *    replacing any data if the end of the data area is reached before
 544  *    encoding the whole string.  If buffer has tail area, it will not be
 545  *    replaced if the string is longer than the current data area, but the
 546  *    buffer will be enlarged and the tail area will be copied to the new
 547  *    tail area in order not to replace any data while appending the string.
 548  *    This will then enlarge the current data area.
 549  *
 550  *    Use this only for formatting.
 551  *
 552  *    Formatting:  SILC_STR_STRING_APPEND(char *)
 553  *
 554  *    For unformatting use one of the SILC_STR_*_STRING macros, which
 555  *    automatically gets the length of the string from the buffer.  Note
 556  *    SILC_STR_STRING_APPEND does not save the length of the string into the
 557  *    buffer.  The caller must do that in order for the unformatting macros
 558  *    to work.
 559  *
 560  *    Example:
 561  *
 562  *    Formatting:    ..., SILC_STR_UINT32(strlen(string)),
 563  *                        SILC_STR_STRING_APPEND(string), ...
 564  *    Unformatting:  ..., SILC_STR_UI32_STRING(&string), ...
 565  *
 566  ***/
 567 #define SILC_STR_STRING_APPEND(x) SILC_PARAM_UI8_STRING | SILC_PARAM_APPEND, (x)
 568
 569 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_*_STRING
 570  *
 571  * NAME
 572  *
 573  *    #define SILC_STR_UI8_STRING() ...
 574  *    #define SILC_STR_UI8_STRING_ALLOC() ...
 575  *    #define SILC_STR_UI16_STRING() ...
 576  *    #define SILC_STR_UI16_STRING_ALLOC() ...
 577  *    #define SILC_STR_UI32_STRING() ...
 578  *    #define SILC_STR_UI32_STRING_ALLOC() ...
 579  *
 580  * DESCRIPTION
 581  *
 582  *    Unsigned NULL terminated string. Note that the string must be
 583  *    NULL terminated because strlen() will be used to get the length of
 584  *    the string.
 585  *
 586  *    Formatting:    SILC_STR_UI32_STRING(unsigned char *)
 587  *    Unformatting:  SILC_STR_UI32_STRING(unsigned char **)
 588  *
 589  *    Unformatting procedure will check for length of the string from the
 590  *    buffer before trying to get the string out. Thus, one *must* format the
 591  *    length as UINT32 or UINT16 or UINT8 into the buffer *before* formatting
 592  *    the actual string to the buffer, and, in unformatting one ignores the
 593  *    length of the string because unformatting procedure will take it
 594  *    automatically.
 595  *
 596  *    Example:
 597  *
 598  *    Formatting:    ..., SILC_STR_UINT32(strlen(string)),
 599  *                        SILC_STR_UI32_STRING(string), ...
 600  *    Unformatting:  ..., SILC_STR_UI32_STRING(&string), ...
 601  *
 602  *    I.e., you can ignore the formatted length field in unformatting.
 603  *
 604  *    UI8, UI16 and UI32 means that the length is considered to be
 605  *    either UINT8, UINT16 or UINT32 in unformatting.
 606  *
 607  *    _ALLOC routines automatically allocates memory for the variable sent
 608  *    as argument in unformatting.
 609  *
 610  ***/
 611 #define SILC_STR_UI8_STRING(x) SILC_PARAM_UI8_STRING, (x)
 612 #define SILC_STR_UI8_STRING_ALLOC(x) SILC_PARAM_UI8_STRING | SILC_PARAM_ALLOC, (x)
 613 #define SILC_STR_UI16_STRING(x) SILC_PARAM_UI16_STRING, (x)
 614 #define SILC_STR_UI16_STRING_ALLOC(x) SILC_PARAM_UI16_STRING | SILC_PARAM_ALLOC, (x)
 615 #define SILC_STR_UI32_STRING(x) SILC_PARAM_UI32_STRING, (x)
 616 #define SILC_STR_UI32_STRING_ALLOC(x) SILC_PARAM_UI32_STRING | SILC_PARAM_ALLOC, (x)
 617
 618 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_*_NSTRING
 619  *
 620  * NAME
 621  *
 622  *    #define SILC_STR_UI8_NSTRING() ...
 623  *    #define SILC_STR_UI8_NSTRING_ALLOC() ...
 624  *    #define SILC_STR_UI16_NSTRING() ...
 625  *    #define SILC_STR_UI16_NSTRING_ALLOC() ...
 626  *    #define SILC_STR_UI32_NSTRING() ...
 627  *    #define SILC_STR_UI32_NSTRING_ALLOC() ...
 628  *
 629  * DESCRIPTION
 630  *
 631  *    Unsigned string. Second argument is the length of the string.
 632  *
 633  *    Formatting:    SILC_STR_UI32_NSTRING(unsigned char *, SilcUInt32)
 634  *    Unformatting:  SILC_STR_UI32_NSTRING(unsigned char **, SilcUInt32 *)
 635  *
 636  *    Unformatting procedure will check for length of the string from the
 637  *    buffer before trying to get the string out. Thus, one *must* format the
 638  *    length as UINT32 or UINT16 or UINT8 into the buffer *before* formatting
 639  *    the actual string to the buffer, and, in unformatting one ignores the
 640  *    length of the string because unformatting procedure will take it
 641  *    automatically.
 642  *
 643  *     Example:
 644  *
 645  *     Formatting:    ..., SILC_STR_UINT32(strlen(string)),
 646  *                         SILC_STR_UI32_NSTRING(string, strlen(string)), ...
 647  *     Unformatting:  ..., SILC_STR_UI32_NSTRING(&string, &len), ...
 648  *
 649  *    I.e., you can ignore the formatted length field in unformatting. The
 650  *    length taken from the buffer is returned to the pointer sent as
 651  *    argument (&len in above example).
 652  *
 653  *    UI8, UI16 and UI32 means that the length is considered to be
 654  *    either UINT8, UINT16 or UINT32 in unformatting.
 655  *
 656  *    _ALLOC routines automatically allocates memory for the variable sent
 657  *    as argument in unformatting.
 658  *
 659  ***/
 660 #define SILC_STR_UI8_NSTRING(x, l) SILC_PARAM_UI8_NSTRING, (x), (l)
 661 #define SILC_STR_UI8_NSTRING_ALLOC(x, l) \
 662   SILC_PARAM_UI8_NSTRING | SILC_PARAM_ALLOC, (x), (l)
 663 #define SILC_STR_UI16_NSTRING(x, l) SILC_PARAM_UI16_NSTRING, (x), (l)
 664 #define SILC_STR_UI16_NSTRING_ALLOC(x, l) \
 665   SILC_PARAM_UI16_NSTRING | SILC_PARAM_ALLOC, (x), (l)
 666 #define SILC_STR_UI32_NSTRING(x, l) SILC_PARAM_UI32_NSTRING, (x), (l)
 667 #define SILC_STR_UI32_NSTRING_ALLOC(x, l) \
 668   SILC_PARAM_UI32_NSTRING | SILC_PARAM_ALLOC, (x), (l)
 669
 670 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_DATA
 671  *
 672  * NAME
 673  *
 674  *    #define SILC_STR_DATA() ...
 675  *    #define SILC_STR_DATA_ALLOC() ...
 676  *
 677  * DESCRIPTION
 678  *
 679  *    Binary data formatting.  Second argument is the length of the data.
 680  *
 681  *    Formatting:    SILC_STR_DATA(unsigned char *, SilcUInt32)
 682  *    Unformatting:  SILC_STR_DATA(unsigned char **, SilcUInt32)
 683  *
 684  *    This type can be used to take arbitrary size data block from the buffer
 685  *    by sending the requested amount of bytes as argument.
 686  *
 687  *    _ALLOC routines automatically allocates memory for the variable sent
 688  *    as argument in unformatting.
 689  *
 690  ***/
 691 #define SILC_STR_DATA(x, l) SILC_PARAM_UICHAR, (x), (l)
 692 #define SILC_STR_DATA_ALLOC(x, l) SILC_PARAM_UICHAR | SILC_PARAM_ALLOC, (x), (l)
 693
 694 /* Deprecated */
 695 #define SILC_STR_UI_XNSTRING(x, l) SILC_PARAM_UICHAR, (x), (l)
 696 #define SILC_STR_UI_XNSTRING_ALLOC(x, l) SILC_PARAM_UICHAR | SILC_PARAM_ALLOC, (x), (l)
 697
 698 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_BUFFER
 699  *
 700  * NAME
 701  *
 702  *    #define SILC_STR_BUFFER() ...
 703  *    #define SILC_STR_BUFFER_ALLOC() ...
 704  *
 705  * DESCRIPTION
 706  *
 707  *    SilcBuffer formatting.
 708  *
 709  *    Formatting:    SILC_STR_BUFFER(SilcBuffer)
 710  *    Unformatting:  SILC_STR_BUFFER(SilcBuffer)
 711  *
 712  *    This type can be used to format and unformat SilcBuffer.  Note that, the
 713  *    length of the buffer will be automatically encoded into the buffer as
 714  *    a 32-bit integer.  In unformatting the SilcBuffer context must be
 715  *    pre-allocated.
 716  *
 717  *    _ALLOC routines automatically allocates memory inside SilcBuffer in
 718  *    unformatting.
 719  *
 720  ***/
 721 #define SILC_STR_BUFFER(x) SILC_PARAM_BUFFER, (x)
 722 #define SILC_STR_BUFFER_ALLOC(x) SILC_PARAM_BUFFER | SILC_PARAM_ALLOC, (x)
 723
 724 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_FUNC
 725  *
 726  * NAME
 727  *
 728  *    #define SILC_STR_FUNC() ...
 729  *
 730  * DESCRIPTION
 731  *
 732  *    Formatting and unformatting of arbitrary data.
 733  *
 734  *    Formatting:    SILC_STR_FUNC(function, void *value, void *context)
 735  *    Unformatting:  SILC_STR_FUNC(function, void **value, void *context)
 736  *
 737  *    This type can be used to call the `function' of the type
 738  *    SilcBufferFormatFunc or SilcBufferUnformatFunc to encode or decode
 739  *    the `value'.  In encoding the `value' will be passed to the `function'
 740  *    and can be encoded into the buffer.  The buffer will be passed as
 741  *    well to the `function' at the location where SILC_STR_FUNC is placed
 742  *    in formatting.  The `context' delivers caller specific context to
 743  *    the `function'
 744  *
 745  *    In unformatting the `function' will decode the encoded type and
 746  *    return it to `value' pointer.  The decoding function should decide
 747  *    itself whether to allocate or not the decoded value.
 748  *
 749  *    The `function' does not have to encode anything and passing `value'
 750  *    as NULL is allowed.  The `function' could for example modify the
 751  *    existing buffer.
 752  *
 753  * EXAMPLE
 754  *
 755  *    // Encode payload, encrypt and compute MAC.
 756  *    silc_buffer_format(buf,
 757  *                       SILC_STR_FUNC(foo_encode_id, id, ctx),
 758  *                       SILC_STR_UINT16(len),
 759  *                       SILC_STR_DATA(data, len),
 760  *                       SILC_STR_FUNC(foo_buf_encrypt, NULL, key),
 761  *                       SILC_STR_FUNC(foo_buf_hmac, NULL, hmac),
 762  *                       SILC_STR_DATA(iv, iv_len);
 763  *                       SILC_STR_END);
 764  *
 765  *    // Check MAC, decrypt and decode payload
 766  *    silc_buffer_unformat(buf,
 767  *                         SILC_STR_FUNC(foo_buf_hmac, NULL, hmac),
 768  *                         SILC_STR_FUNC(foo_buf_decrypt, NULL, key),
 769  *                         SILC_STR_FUNC(foo_decode_id, &id, ctx),
 770  *                         SILC_STR_UINT16(&len),
 771  *                         SILC_STR_END);
 772  *
 773  ***/
 774 #define SILC_STR_FUNC(func, val, context) SILC_PARAM_FUNC, \
 775     func, (val), (context)
 776
 777 /****d* silcutil/SilcBufferFormatAPI/SilcBufferRegexFlags
 778  *
 779  * NAME
 780  *
 781  *    typedef enum { ... } SilcBufferRegexFlags;
 782  *
 783  * DESCRIPTION
 784  *
 785  *    Regular expression flags for SILC_STR_REGEX macro.  The flags can be
 786  *    used to manipulate the behavior of the SILC_STR_REGEX.  All flags
 787  *    may be combined unless otherwise stated.
 788  *
 789  * SOURCE
 790  */
 791 typedef enum {
 792   SILC_STR_REGEX_NONE                 = 0x00000000,
 793
 794   /* By default mismatch will be skipped.  Set this flag if mismatch should
 795      cause error and stopping of the formatting/unformatting. */
 796   SILC_STR_REGEX_MISMATCH             = 0x00000001,
 797
 798   /* By default only the first match is found.  Set this flag to find
 799      all matches. */
 800   SILC_STR_REGEX_ALL                  = 0x00000002,
 801
 802   /* By default the buffer position is advanced to the position of the
 803      first match.  Set this flag if the buffer should not be advanced to
 804      the match. */
 805   SILC_STR_REGEX_NO_ADVANCE           = 0x00000004,
 806
 807   /* By default SILC_STR_REGEX performs the match on the whole buffer.  Set
 808      this flag to make it behave like sed and match line by line.  Each line
 809      must end with '\n'.  If buffer doesn't have '\n' it is considered to be
 810      one line.  Note that, any formatting done immediately after SILC_STR_REGEX
 811      block with this flag will be formatted to the end of the buffer (after
 812      last line).  Use SILC_STR_OFFSET* macros to change the position if
 813      needed.  Also note that, any encoding macro inside the SILC_STR_REGEX
 814      block will see only the matched line (including '\n'), instead of whole
 815      buffer after the match. */
 816   SILC_STR_REGEX_NL                   = 0x00000008,
 817
 818   /* Set this flag to not match the regular expression, but to match everything
 819      else.  When combined with SILC_STR_REGEX_NL this flag matches all other
 820      lines except the ones with matching regular expression. */
 821   SILC_STR_REGEX_NOT                  = 0x00000010,
 822
 823   /* By default the buffer is advanced to the first match and the rest of the
 824      buffer remains as is.  Set this flag to pass the exact match to the
 825      SILC_STR_* macros in the SILC_STR_REGEX block; macros see the start of
 826      the match and the end of the match, but not rest of the buffer (ie. with
 827      match 'foo' the size of the buffer is 3 bytes). */
 828   SILC_STR_REGEX_INCLUSIVE            = 0x00000020,
 829 } SilcBufferRegexFlags;
 830 /***/
 831
 832 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_REGEX
 833  *
 834  * NAME
 835  *
 836  *    #define SILC_STR_REGEX() ...
 837  *
 838  * DESCRIPTION
 839  *
 840  *    Regular expression matching within the buffer.
 841  *
 842  *    Formatting:    SILC_STR_REGEX(char *regex, SilcBufferRegexFlags flags)
 843  *    Unformatting:  SILC_STR_REGEX(char *regex, SilcBufferRegexFlags flags)
 844  *
 845  *    SILC_STR_REGEX can be used to do regular expression matching within
 846  *    the SilcBuffer.  When the string in the buffer matches the regular
 847  *    expression the position of the buffer is advanced to the position of
 848  *    the first match (rest of the buffer remains intact).  If the regular
 849  *    expression does not match it is skipped, unless the flags specify
 850  *    otherwise.  If flags are not needed they can be set to 0.
 851  *
 852  *    In addition of matching regular expressions it can be used in a
 853  *    Stream Editor (sed) and Awk like fashion.  The regular expression can be
 854  *    matched and then edited by any of the SILC_STR_* macros.  The flags
 855  *    can be used to perform complex operations on the data.  Some sed
 856  *    features that cannot be directly done with the flags can be done with
 857  *    SILC_STR_FUNC and other macros (the SILC_STR_FUNC could do anything
 858  *    after the match).
 859  *
 860  *    The SILC_STR_REGEX itself is used as an opening of a block of encoding
 861  *    macros and must be closed with SILC_STR_END.  This means that for
 862  *    each SILC_STR_REGEX there must be one SILC_STR_END.  See examples for
 863  *    more information.
 864  *
 865  *    The SILC_STR_REGEX can be used in buffer unformatting also to do
 866  *    string matching and parsing, but not editing, except with SILC_STR_FUNC
 867  *    macro, which can do anything caller wants.
 868  *
 869  * EXAMPLE
 870  *
 871  *    // sed 's/foo/bar/', replace first foo with bar
 872  *    silc_buffer_format(buffer,
 873  *                       SILC_STR_REGEX("foo", 0),
 874  *                         SILC_STR_STRING("bar"),
 875  *                       SILC_STR_END, SILC_STR_END);
 876  *
 877  *    // sed 's/foo/barbar/g', replace all foo's with barbar, without
 878  *    // overwriting any data in the buffer, but appending it.  The match
 879  *    // must be SILC_STR_REGEX_INCLUSIVE to make appending work.
 880  *    silc_buffer_format(buffer,
 881  *                       SILC_STR_REGEX("foo", SILC_STR_REGEX_ALL |
 882  *                                             SILC_STR_REGEX_INCLUSIVE),
 883  *                         SILC_STR_STRING_APPEND("barbar"),
 884  *                       SILC_STR_END, SILC_STR_END);
 885  *
 886  *    // sed '/baz/s/foo/bar/g, replace all foo's with bar on lines with baz
 887  *    silc_buffer_format(buffer,
 888  *                       SILC_STR_REGEX("baz", SILC_STR_REGEX_NL),
 889  *                         SILC_STR_REGEX("foo", SILC_STR_REGEX_ALL),
 890  *                           SILC_STR_STRING("bar"),
 891  *                         SILC_STR_END,
 892  *                       SILC_STR_END, SILC_STR_END);
 893  *
 894  *    // Print all lines that start with 'R'
 895  *    int print(SilcStack stack, SilcBuffer buf, void *value, void *context)
 896  *    {
 897  *      return fwrite(silc_buffer_data(buf), 1, silc_buffer_len(buf), stdout);
 898  *    }
 899  *
 900  *    silc_buffer_unformat(buffer,
 901  *                         SILC_STR_REGEX("^R", SILC_STR_REGEX_NL),
 902  *                           SILC_STR_FUNC(print, NULL, NULL),
 903  *                         SILC_STR_END, SILC_STR_END);
 904  *
 905  ***/
 906 #define SILC_STR_REGEX(regex, flags) SILC_PARAM_REGEX, (regex), (flags)
 907
 908 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_OFFSET
 909  *
 910  * NAME
 911  *
 912  *    #define SILC_STR_OFFSET() ...
 913  *
 914  * DESCRIPTION
 915  *
 916  *    Offset in buffer.  This can be used in formatting and unformatting to
 917  *    move the data pointer of the buffer either forwards (positive offset)
 918  *    or backwards (negative offset).  It can be used to for example skip
 919  *    some types during unformatting.
 920  *
 921  *    Example:
 922  *
 923  *    ..., SILC_STR_OFFSET(5), ...
 924  *    ..., SILC_STR_OFFSET(-3), ...
 925  *
 926  *    Moves the data pointer at the point of the offset either forward
 927  *    or backward and then moves to the next type.  Multiple SILC_STR_OFFSETs
 928  *    can be used in formatting and unformatting at the same time.
 929  *
 930  ***/
 931 #define SILC_STR_OFFSET(x) SILC_PARAM_OFFSET, (x)
 932
 933 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_OFFSET_START
 934  *
 935  * NAME
 936  *
 937  *    #define SILC_STR_OFFSET_START ...
 938  *
 939  * DESCRIPTION
 940  *
 941  *    Moves the buffer position to the start of the data area.
 942  *
 943  *    Example:
 944  *
 945  *    ..., SILC_STR_OFFSET_START, ...
 946  *
 947  ***/
 948 #define SILC_STR_OFFSET_START SILC_PARAM_OFFSET_START
 949
 950 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_OFFSET_END
 951  *
 952  * NAME
 953  *
 954  *    #define SILC_STR_OFFSET_END ...
 955  *
 956  * DESCRIPTION
 957  *
 958  *    Moves the buffer position to the end of the data area.
 959  *
 960  *    Example:
 961  *
 962  *    ..., SILC_STR_OFFSET_END, ...
 963  *
 964  ***/
 965 #define SILC_STR_OFFSET_END SILC_PARAM_OFFSET_END
 966
 967 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_ADVANCE
 968  *
 969  * NAME
 970  *
 971  *    #define SILC_STR_ADVANCE ...
 972  *
 973  * DESCRIPTION
 974  *
 975  *    Advance the buffer to the end of the data after the formatting is
 976  *    done.  In normal operation when the formatted data is written the
 977  *    buffer is positioned at the start of the data.  With SILC_STR_ADVANCE
 978  *    the buffer will be positioned at the end of the data.  This makes it
 979  *    easy to add new data immediately after the previously added data.
 980  *    The SILC_STR_ADVANCE may also be used in unformatting.
 981  *
 982  * EXAMPLE
 983  *
 984  *    do {
 985  *      len = read(fd, buf, sizeof(buf));
 986  *      if (len > 0)
 987  *        // Add read data to the buffer
 988  *        silc_buffer_format(buffer,
 989  *                           SILC_STR_ADVANCE,
 990  *                           SILC_STR_DATA(buf, len),
 991  *                           SILC_STR_END);
 992  *    } while (len > 0);
 993  *
 994  *    // Move to beginning of buffer
 995  *    silc_buffer_start(buffer);
 996  *
 997  ***/
 998 #define SILC_STR_ADVANCE SILC_PARAM_ADVANCE
 999
1000 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_END
1001  *
1002  * NAME
1003  *
1004  *    #define SILC_STR_END ...
1005  *
1006  * DESCRIPTION
1007  *
1008  *    Marks end of the argument list. This must be at the end of the
1009  *    argument list or error will occur.
1010  *
1011  ***/
1012 #define SILC_STR_END SILC_PARAM_END
1013
1014 /****d* silcutil/SilcBufferFormatAPI/SILC_STRFMT_END
1015  *
1016  * NAME
1017  *
1018  *    #define SILC_STRFMT_END ...
1019  *
1020  * DESCRIPTION
1021  *
1022  *    Marks end of the argument list in silc_buffer_strformat function.
1023  *    This must be at the end of the argument list or error will occur.
1024  *
1025  ***/
1026 #define SILC_STRFMT_END (void *)SILC_STR_END
1027
1028 #endif  /* !SILCBUFFMT_H */