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