lib/silcutil/silcbuffmt.h

   1 /*
   2
   3   silcbuffmt.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 1997 - 2007 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 format packets,
  27  * protocol payloads and such.
  28  *
  29  * As the SilcBuffer API is not thread-safe these routines may not be used
  30  * in multithreaded environment with a same SilcBuffer context without
  31  * concurrency control.
  32  *
  33  ***/
  34
  35 #ifndef SILCBUFFMT_H
  36 #define SILCBUFFMT_H
  37
  38 /****f* silcutil/SilcBufferFormatAPI/SilcBufferFormatFunc
  39  *
  40  * SYNOPSIS
  41  *
  42  *    typedef int (*SilcBuffeSFormatFunc)(SilcStack stack,
  43  *                                        SilcBuffer buffer,
  44  *                                        void *value,
  45  *                                        void *context);
  46  *
  47  * DESCRIPTION
  48  *
  49  *    Formatting function callback given with SILC_STR_FUNC type.  The
  50  *    `buffer' is the buffer being formatted at the location where the
  51  *    SILC_STR_FUNC was placed in formatting.  The function should call
  52  *    silc_buffer_senlarge before it adds the data to the buffer to make
  53  *    sure that it has enough space.  The buffer->head points to the
  54  *    start of the buffer and silc_buffer_headlen() gives the length
  55  *    of the currently formatted data area.  It is also possible to use
  56  *    silc_buffer_sformat with `buffer' which will enlarge the buffer if
  57  *    needed.
  58  *
  59  *    The `value' is the value given to SILC_STR_FUNC that is to be formatted
  60  *    into the buffer.  It may be NULL if the function is not formatting
  61  *    new data into the buffer.  The `context' is caller specific context.
  62  *    Returns -1 on error and length of the formatted value otherwise, and
  63  *    0 if nothing was formatted.
  64  *
  65  ***/
  66 typedef int (*SilcBufferFormatFunc)(SilcStack stack, SilcBuffer buffer,
  67                                     void *value, void *context);
  68
  69 /****f* silcutil/SilcBufferFormatAPI/SilcBufferUnformatFunc
  70  *
  71  * SYNOPSIS
  72  *
  73  *    typedef int (*SilcBufferUnformatFunc)(SilcBuffer buffer,
  74  *                                          void **value,
  75  *                                          void *context);
  76  *
  77  * DESCRIPTION
  78  *
  79  *    Unformatting function callback given with SILC_STR_FUNC type.  The
  80  *    `buffer' is the buffer being unformatted and is at the location where
  81  *    the SILC_STR_FUNC was placed in unformatting.  The function should
  82  *    check there is enough data in the `buffer' before trying to decode
  83  *    from it.
  84  *
  85  *    If this function unformats anything from the buffer its value is to
  86  *    be returned to the `value' pointer.  The implementation should itself
  87  *    decide whether the unformatted value is allocated or not.  If this
  88  *    function does not unformat anything, nothing is returned to `value'
  89  *
  90  *    The `context' is caller specific context.  Returns -1 on error, and
  91  *    length of the unformatted value otherwise, and 0 if nothing was
  92  *    unformatted.
  93  *
  94  ***/
  95 typedef int (*SilcBufferUnformatFunc)(SilcStack stack, SilcBuffer buffer,
  96                                       void **value, void *context);
  97
  98 /* Prototypes */
  99
 100 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_format
 101  *
 102  * SYNOPSIS
 103  *
 104  *    int silc_buffer_format(SilcBuffer dst, ...);
 105  *
 106  * DESCRIPTION
 107  *
 108  *    Formats a buffer from a variable argument list.  Returns -1 on error
 109  *    and the length of the formatted buffer otherwise.  The buffer is
 110  *    enlarged automatically during formatting, if it doesn't already have
 111  *    enough space.
 112  *
 113  * EXAMPLE
 114  *
 115  *    Three basic ways of using silc_buffer_format:
 116  *
 117  *    // Statically allocated zero size buffer
 118  *    SilcBufferStruct buffer;
 119  *
 120  *    memset(&buffer, 0, sizeof(buffer));
 121  *    ret = silc_buffer_format(&buffer,
 122  *                             SILC_STR_UI_INT(intval),
 123  *                             SILC_STR_CHAR(charval),
 124  *                             SILC_STR_UI_INT(intval),
 125  *                             SILC_STR_SHORT(str_len),
 126  *                             SILC_STR_DATA(str, str_len),
 127  *                             SILC_STR_END);
 128  *    if (ret < 0)
 129  *      error;
 130  *
 131  *    // Free the allocated data
 132  *    silc_buffer_purge(&buffer);
 133  *
 134  *    // Dynamically allocated zero size buffer
 135  *    SilcBuffer buf;
 136  *    buf = silc_buffer_alloc(0);
 137  *    ret = silc_buffer_format(buf,
 138  *                             SILC_STR_UI_INT(intval),
 139  *                             SILC_STR_CHAR(charval),
 140  *                             SILC_STR_END);
 141  *    if (ret < 0)
 142  *      error;
 143  *
 144  *    // Free the allocated buffer
 145  *    silc_buffer_free(buf);
 146  *
 147  *    // Dynamically allocated buffer with enough space
 148  *    SilcBuffer buf;
 149  *    buf = silc_buffer_alloc(2 + str_len);
 150  *    ret = silc_buffer_format(buf,
 151  *                             SILC_STR_UI_SHORT(str_len),
 152  *                             SILC_STR_DATA(str, str_len),
 153  *                             SILC_STR_END);
 154  *    if (ret < 0)
 155  *      error;
 156  *
 157  ***/
 158 int silc_buffer_format(SilcBuffer dst, ...);
 159
 160 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_sformat
 161  *
 162  * SYNOPSIS
 163  *
 164  *    int silc_buffer_sformat(SilcStack stack, SilcBuffer dst, ...);
 165  *
 166  * DESCRIPTION
 167  *
 168  *    Same as silc_buffer_format but uses `stack' to allocate the memory.
 169  *    if `stack' is NULL reverts back to silc_buffer_format call.
 170  *
 171  *    Note that this call consumes the `stack'.  The caller should push the
 172  *    stack before calling the function and pop it later.
 173  *
 174  ***/
 175 int silc_buffer_sformat(SilcStack stack, SilcBuffer dst, ...);
 176
 177 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_format_vp
 178  *
 179  * SYNOPSIS
 180  *
 181  *    int silc_buffer_format_vp(SilcBuffer dst, va_list vp);
 182  *
 183  * DESCRIPTION
 184  *
 185  *    Formats a buffer from a variable argument list indicated by the `ap'.
 186  *    Returns -1 on error and the length of the formatted buffer otherwise.
 187  *
 188  ***/
 189 int silc_buffer_format_vp(SilcBuffer dst, va_list ap);
 190
 191 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_sformat_vp
 192  *
 193  * SYNOPSIS
 194  *
 195  *    int silc_buffer_sformat_vp(SilcStack stack, SilcBuffer dst, va_list vp);
 196  *
 197  * DESCRIPTION
 198  *
 199  *    Same as silc_buffer_format_vp but uses `stack' to allocate the memory.
 200  *    if `stack' is NULL reverts back to silc_buffer_format_vp call.
 201  *
 202  *    Note that this call consumes the `stack'.  The caller should push the
 203  *    stack before calling the function and pop it later.
 204  *
 205  ***/
 206 int silc_buffer_sformat_vp(SilcStack stack, SilcBuffer dst, va_list ap);
 207
 208 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_unformat
 209  *
 210  * SYNOPSIS
 211  *
 212  *    int silc_buffer_unformat(SilcBuffer src, ...);
 213  *
 214  * DESCRIPTION
 215  *
 216  *    Unformats a buffer from a variable argument list.  Returns -1 on error
 217  *    and the length of the unformatted buffer otherwise.
 218  *
 219  * EXAMPLE
 220  *
 221  *    ret = silc_buffer_unformat(buffer,
 222  *                               SILC_STR_UI_INT(&intval),
 223  *                               SILC_STR_CHAR(&charval),
 224  *                               SILC_STR_OFFSET(4),
 225  *                               SILC_STR_UI16_NSTRING_ALLOC(&str, &str_len),
 226  *                               SILC_STR_END);
 227  *    if (ret < 0)
 228  *      error;
 229  *
 230  ***/
 231 int silc_buffer_unformat(SilcBuffer src, ...);
 232
 233 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_sunformat
 234  *
 235  * SYNOPSIS
 236  *
 237  *    int silc_buffer_sunformat(SilcStack stack, SilcBuffer src, ...);
 238  *
 239  * DESCRIPTION
 240  *
 241  *    Same as silc_buffer_unformat but uses `stack' to allocate the memory.
 242  *    if `stack' is NULL reverts back to silc_buffer_format call.
 243  *
 244  *    Note that this call consumes the `stack'.  The caller should push the
 245  *    stack before calling the function and pop it later.
 246  *
 247  ***/
 248 int silc_buffer_sunformat(SilcStack stack, SilcBuffer src, ...);
 249
 250 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_unformat_vp
 251  *
 252  * SYNOPSIS
 253  *
 254  *    int silc_buffer_unformat_vp(SilcBuffer src, va_list vp);
 255  *
 256  * DESCRIPTION
 257  *
 258  *    Unformats a buffer from a variable argument list indicated by the `ap'.
 259  *    Returns -1 on error and the length of the unformatted buffer otherwise.
 260  *
 261  ***/
 262 int silc_buffer_unformat_vp(SilcBuffer src, va_list ap);
 263
 264 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_sunformat_vp
 265  *
 266  * SYNOPSIS
 267  *
 268  *    int silc_buffer_sunformat_vp(SilcBuffer src, va_list vp);
 269  *
 270  * DESCRIPTION
 271  *
 272  *    Same as silc_buffer_unformat_vp but uses `stack' to allocate the
 273  *    memory.  if `stack' is NULL reverts back to silc_buffer_format_vp call.
 274  *
 275  *    Note that this call consumes the `stack'.  The caller should push the
 276  *    stack before calling the function and pop it later.
 277  *
 278  ***/
 279 int silc_buffer_sunformat_vp(SilcStack stack, SilcBuffer src, va_list ap);
 280
 281 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_strformat
 282  *
 283  * SYNOPSIS
 284  *
 285  *    int silc_buffer_strformat(SilcBuffer dst, ...);
 286  *
 287  * DESCRIPTION
 288  *
 289  *    Formats a buffer from variable argument list of strings.  Each
 290  *    string must be NULL-terminated and the variable argument list must
 291  *    be end with SILC_STRFMT_END argument.  This allows that a string in
 292  *    the list can be NULL, in which case it is skipped.  This automatically
 293  *    allocates the space for the buffer data but `dst' must be already
 294  *    allocated by the caller.
 295  *
 296  * EXAMPLE
 297  *
 298  *    ret = silc_buffer_strformat(buffer, "foo", "bar", SILC_STRFMT_END);
 299  *    if (ret < 0)
 300  *      error;
 301  *
 302  ***/
 303 int silc_buffer_strformat(SilcBuffer dst, ...);
 304
 305 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_sstrformat
 306  *
 307  * SYNOPSIS
 308  *
 309  *    int silc_buffer_strformat(SilcStack stack, SilcBuffer dst, ...);
 310  *
 311  * DESCRIPTION
 312  *
 313  *    Formats a buffer from variable argument list of strings.  Each
 314  *    string must be NULL-terminated and the variable argument list must
 315  *    be end with SILC_STRFMT_END argument.  This allows that a string in
 316  *    the list can be NULL, in which case it is skipped.  This automatically
 317  *    allocates the space for the buffer data but `dst' must be already
 318  *    allocated by the caller.  This function is equivalent to
 319  *    silc_buffer_strformat but allocates memory from `stack'.
 320  *
 321  *    Note that this call consumes the `stack'.  The caller should push the
 322  *    stack before calling the function and pop it later.
 323  *
 324  ***/
 325 int silc_buffer_sstrformat(SilcStack stack, SilcBuffer dst, ...);
 326
 327 /****d* silcutil/SilcBufferFormatAPI/SilcBufferParamType
 328  *
 329  * NAME
 330  *
 331  *    typedef enum { ... } SilcBufferParamType;
 332  *
 333  * DESCRIPTION
 334  *
 335  *    Buffer parameter types.  These are not needed when formatting or
 336  *    unformatting buffers.  Use the macros such as SILC_STR_UI_CHAR and
 337  *    others instead.  These types may be used when describing what a
 338  *    buffer looks like, and how it may be formatted and unformatted.
 339  *
 340  * SOURCE
 341  */
 342 typedef enum {
 343   SILC_PARAM_SI8_CHAR,             /* Signed 8-bit char */
 344   SILC_PARAM_UI8_CHAR,             /* Unsigned 8-bit char */
 345   SILC_PARAM_SI16_SHORT,           /* Signed 16-bit int */
 346   SILC_PARAM_UI16_SHORT,           /* Unsigned 16-bit int */
 347   SILC_PARAM_SI32_INT,             /* Signed 32-bit int */
 348   SILC_PARAM_UI32_INT,             /* Unsigned 32-bit int */
 349   SILC_PARAM_SI64_INT,             /* Signed 64-bit int */
 350   SILC_PARAM_UI64_INT,             /* Unsigned 64-bit int */
 351   SILC_PARAM_UI8_STRING,           /* String (max len 8-bits)*/
 352   SILC_PARAM_UI16_STRING,          /* String (max len 16-bits) */
 353   SILC_PARAM_UI32_STRING,          /* String (max len 32-bits) */
 354   SILC_PARAM_BUFFER,               /* SilcBuffer */
 355
 356   /* Internal types */
 357   SILC_PARAM_DATA,                 /* Binary data */
 358   SILC_PARAM_UI8_NSTRING,          /* String (max len 8-bits) */
 359   SILC_PARAM_UI16_NSTRING,         /* String (max len 16-bits) */
 360   SILC_PARAM_UI32_NSTRING,         /* String (max len 32-bits) */
 361   SILC_PARAM_UI8_STRING_ALLOC,     /* Alloc + memcpy */
 362   SILC_PARAM_UI16_STRING_ALLOC,    /* Alloc + memcpy */
 363   SILC_PARAM_UI32_STRING_ALLOC,    /* Alloc + memcpy */
 364   SILC_PARAM_UI8_NSTRING_ALLOC,    /* Alloc + memcpy */
 365   SILC_PARAM_UI16_NSTRING_ALLOC,   /* Alloc + memcpy */
 366   SILC_PARAM_UI32_NSTRING_ALLOC,   /* Alloc + memcpy */
 367   SILC_PARAM_DATA_ALLOC,           /* Alloc + memcpy */
 368   SILC_PARAM_BUFFER_ALLOC,         /* Alloc + memcpy */
 369
 370   SILC_PARAM_OFFSET,
 371   SILC_PARAM_ADVANCE,
 372   SILC_PARAM_FUNC,
 373
 374   SILC_PARAM_UI_XNSTRING,
 375   SILC_PARAM_UI_XNSTRING_ALLOC,
 376
 377   SILC_PARAM_END
 378 } SilcBufferParamType;
 379 /***/
 380
 381 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_*_CHAR
 382  *
 383  * NAME
 384  *
 385  *    #define SILC_STR_UI_CHAR() ...
 386  *    #define SILC_STR_SI_CHAR() ...
 387  *
 388  * DESCRIPTION
 389  *
 390  *    One signed/unsigned character.
 391  *
 392  *    Formatting:    SILC_STR_SI_CHAR(char)
 393  *                   SILC_STR_UI_CHAR(unsigned char)
 394  *    Unformatting:  SILC_STR_SI_CHAR(char *)
 395  *                   SILC_STR_UI_CHAR(unsigned char *)
 396  *
 397  ***/
 398 #define SILC_STR_SI_CHAR(x) SILC_PARAM_SI8_CHAR, (x)
 399 #define SILC_STR_UI_CHAR(x) SILC_PARAM_UI8_CHAR, (x)
 400
 401 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_*_SHORT
 402  *
 403  * NAME
 404  *
 405  *    #define SILC_STR_UI_SHORT() ...
 406  *    #define SILC_STR_SI_SHORT() ...
 407  *
 408  * DESCRIPTION
 409  *
 410  *    SilcInt16/SilcUInt16.
 411  *
 412  *    Formatting:    SILC_STR_SI_SHORT(SilcInt16)
 413  *                   SILC_STR_UI_SHORT(SilcUInt16)
 414  *    Unformatting:  SILC_STR_SI_SHORT(SilcInt16 *)
 415  *                   SILC_STR_UI_SHORT(SilcUInt16 *)
 416  *
 417  ***/
 418 #define SILC_STR_SI_SHORT(x) SILC_PARAM_SI16_SHORT, (x)
 419 #define SILC_STR_UI_SHORT(x) SILC_PARAM_UI16_SHORT, (x)
 420
 421 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_*_INT
 422  *
 423  * NAME
 424  *
 425  *    #define SILC_STR_UI_INT() ...
 426  *    #define SILC_STR_SI_INT() ...
 427  *
 428  * DESCRIPTION
 429  *
 430  *    SilcInt32/SilcUInt32.
 431  *
 432  *    Formatting:    SILC_STR_SI_INT(SilcInt32)
 433  *                   SILC_STR_UI_INT(SilcUInt32)
 434  *    Unformatting:  SILC_STR_SI_INT(SilcInt32 *)
 435  *                   SILC_STR_UI_INT(SilcUInt32 *)
 436  *
 437  ***/
 438 #define SILC_STR_SI_INT(x) SILC_PARAM_SI32_INT, (x)
 439 #define SILC_STR_UI_INT(x) SILC_PARAM_UI32_INT, (x)
 440
 441 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_*_INT64
 442  *
 443  * NAME
 444  *
 445  *    #define SILC_STR_UI_INT64() ...
 446  *    #define SILC_STR_SI_INT64() ...
 447  *
 448  * DESCRIPTION
 449  *
 450  *    SilcInt64/SilcUInt64.
 451  *
 452  *     Formatting:    SILC_STR_SI_INT64(SilcInt64)
 453  *                    SILC_STR_UI_INT64(SilcUInt64)
 454  *     Unformatting:  SILC_STR_SI_INT64(SilcInt64 *)
 455  *                    SILC_STR_UI_INT64(SilcUInt64 *)
 456  *
 457  ***/
 458 #define SILC_STR_SI_INT64(x) SILC_PARAM_SI64_INT, (x)
 459 #define SILC_STR_UI_INT64(x) SILC_PARAM_UI64_INT, (x)
 460
 461 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_*_STRING
 462  *
 463  * NAME
 464  *
 465  *    #define SILC_STR_UI8_STRING() ...
 466  *    #define SILC_STR_UI8_STRING_ALLOC() ...
 467  *    #define SILC_STR_UI16_STRING() ...
 468  *    #define SILC_STR_UI16_STRING_ALLOC() ...
 469  *    #define SILC_STR_UI32_STRING() ...
 470  *    #define SILC_STR_UI32_STRING_ALLOC() ...
 471  *
 472  * DESCRIPTION
 473  *
 474  *    Unsigned NULL terminated string. Note that the string must be
 475  *    NULL terminated because strlen() will be used to get the length of
 476  *    the string.
 477  *
 478  *    Formatting:    SILC_STR_UI32_STRING(unsigned char *)
 479  *    Unformatting:  SILC_STR_UI32_STRING(unsigned char **)
 480  *
 481  *    Unformatting procedure will check for length of the string from the
 482  *    buffer before trying to get the string out. Thus, one *must* format the
 483  *    length as UI_INT or UI_SHORT into the buffer *before* formatting the
 484  *    actual string to the buffer, and, in unformatting one must ignore the
 485  *    length of the string because unformatting procedure will take it
 486  *    automatically.
 487  *
 488  *    Example:
 489  *
 490  *    Formatting:    ..., SILC_STR_UI_INT(strlen(string)),
 491  *                        SILC_STR_UI32_STRING(string), ...
 492  *    Unformatting:  ..., SILC_STR_UI32_STRING(&string), ...
 493  *
 494  *    I.e., you can ignore the formatted length field in unformatting.
 495  *
 496  *    UI8, UI16 and UI32 means that the length is considered to be
 497  *    either char (8 bits), short (16 bits) or int (32 bits) in
 498  *    unformatting.
 499  *
 500  *    _ALLOC routines automatically allocates memory for the variable sent
 501  *    as argument in unformatting.
 502  *
 503  ***/
 504 #define SILC_STR_UI8_STRING(x) SILC_PARAM_UI8_STRING, (x)
 505 #define SILC_STR_UI8_STRING_ALLOC(x) SILC_PARAM_UI8_STRING_ALLOC, (x)
 506 #define SILC_STR_UI16_STRING(x) SILC_PARAM_UI16_STRING, (x)
 507 #define SILC_STR_UI16_STRING_ALLOC(x) SILC_PARAM_UI16_STRING_ALLOC, (x)
 508 #define SILC_STR_UI32_STRING(x) SILC_PARAM_UI32_STRING, (x)
 509 #define SILC_STR_UI32_STRING_ALLOC(x) SILC_PARAM_UI32_STRING_ALLOC, (x)
 510
 511 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_*_NSTRING
 512  *
 513  * NAME
 514  *
 515  *    #define SILC_STR_UI8_NSTRING() ...
 516  *    #define SILC_STR_UI8_NSTRING_ALLOC() ...
 517  *    #define SILC_STR_UI16_NSTRING() ...
 518  *    #define SILC_STR_UI16_NSTRING_ALLOC() ...
 519  *    #define SILC_STR_UI32_NSTRING() ...
 520  *    #define SILC_STR_UI32_NSTRING_ALLOC() ...
 521  *
 522  * DESCRIPTION
 523  *
 524  *    Unsigned string. Second argument is the length of the string.
 525  *
 526  *    Formatting:    SILC_STR_UI32_NSTRING(unsigned char *, SilcUInt32)
 527  *    Unformatting:  SILC_STR_UI32_NSTRING(unsigned char **, SilcUInt32 *)
 528  *
 529  *    Unformatting procedure will check for length of the string from the
 530  *    buffer before trying to get the string out. Thus, one *must* format the
 531  *    length as UI_INT or UI_SHORT into the buffer *before* formatting the
 532  *    actual string to the buffer, and, in unformatting one must ignore the
 533  *    length of the string because unformatting procedure will take it
 534  *    automatically.
 535  *
 536  *     Example:
 537  *
 538  *     Formatting:    ..., SILC_STR_UI_INT(strlen(string)),
 539  *                         SILC_STR_UI32_NSTRING(string, strlen(string)), ...
 540  *     Unformatting:  ..., SILC_STR_UI32_NSTRING(&string, &len), ...
 541  *
 542  *    I.e., you can ignore the formatted length field in unformatting. The
 543  *    length taken from the buffer is returned to the pointer sent as
 544  *    argument (&len in above example).
 545  *
 546  *    UI8, UI16 and UI32 means that the length is considered to be
 547  *    either char (8 bits), short (16 bits) or int (32 bits) in
 548  *    unformatting.
 549  *
 550  *    _ALLOC routines automatically allocates memory for the variable sent
 551  *    as argument in unformatting.
 552  *
 553  ***/
 554 #define SILC_STR_UI8_NSTRING(x, l) SILC_PARAM_UI8_NSTRING, (x), (l)
 555 #define SILC_STR_UI8_NSTRING_ALLOC(x, l) \
 556   SILC_PARAM_UI8_NSTRING_ALLOC, (x), (l)
 557 #define SILC_STR_UI16_NSTRING(x, l) SILC_PARAM_UI16_NSTRING, (x), (l)
 558 #define SILC_STR_UI16_NSTRING_ALLOC(x, l) \
 559   SILC_PARAM_UI16_NSTRING_ALLOC, (x), (l)
 560 #define SILC_STR_UI32_NSTRING(x, l) SILC_PARAM_UI32_NSTRING, (x), (l)
 561 #define SILC_STR_UI32_NSTRING_ALLOC(x, l) \
 562   SILC_PARAM_UI32_NSTRING_ALLOC, (x), (l)
 563
 564 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_DATA
 565  *
 566  * NAME
 567  *
 568  *    #define SILC_STR_DATA() ...
 569  *    #define SILC_STR_DATA_ALLOC() ...
 570  *
 571  * DESCRIPTION
 572  *
 573  *    Binary data formatting.  Second argument is the length of the data.
 574  *
 575  *    Formatting:    SILC_STR_DATA(unsigned char *, SilcUInt32)
 576  *    Unformatting:  SILC_STR_DATA(unsigned char **, SilcUInt32)
 577  *
 578  *    This type can be used to take arbitrary size data block from the buffer
 579  *    by sending the requested amount of bytes as argument.
 580  *
 581  *    _ALLOC routines automatically allocates memory for the variable sent
 582  *    as argument in unformatting.
 583  *
 584  ***/
 585 #define SILC_STR_DATA(x, l) SILC_PARAM_DATA, (x), (l)
 586 #define SILC_STR_DATA_ALLOC(x, l) SILC_PARAM_DATA_ALLOC, (x), (l)
 587
 588 /* Deprecated */
 589 #define SILC_STR_UI_XNSTRING(x, l) SILC_PARAM_UI_XNSTRING, (x), (l)
 590 #define SILC_STR_UI_XNSTRING_ALLOC(x, l) SILC_PARAM_UI_XNSTRING_ALLOC, (x), (l)
 591
 592 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_BUFFER
 593  *
 594  * NAME
 595  *
 596  *    #define SILC_STR_BUFFER() ...
 597  *    #define SILC_STR_BUFFER_ALLOC() ...
 598  *
 599  * DESCRIPTION
 600  *
 601  *    SilcBuffer formatting.
 602  *
 603  *    Formatting:    SILC_STR_BUFFER(SilcBuffer)
 604  *    Unformatting:  SILC_STR_BUFFER(SilcBuffer)
 605  *
 606  *    This type can be used to format and unformat SilcBuffer.  Note that, the
 607  *    length of the buffer will be automatically encoded into the buffer as
 608  *    a 32-bit integer.  In unformatting the SilcBuffer context must be
 609  *    pre-allocated.
 610  *
 611  *    _ALLOC routines automatically allocates memory inside SilcBuffer in
 612  *    unformatting.
 613  *
 614  ***/
 615 #define SILC_STR_BUFFER(x) SILC_PARAM_BUFFER, (x)
 616 #define SILC_STR_BUFFER_ALLOC(x) SILC_PARAM_BUFFER_ALLOC, (x)
 617
 618 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_FUNC
 619  *
 620  * NAME
 621  *
 622  *    #define SILC_STR_FUNC() ...
 623  *
 624  * DESCRIPTION
 625  *
 626  *    SilcBuffer formatting.
 627  *
 628  *    Formatting:    SILC_STR_FUNC(function, void *value, void *context)
 629  *    Unformatting:  SILC_STR_FUNC(function, void **value, void *context)
 630  *
 631  *    This type can be used to call the `function' of the type
 632  *    SilcBufferFormatFunc or SilcBufferUnformatFunc to encode or decode
 633  *    the `value'.  In encoding the `value' will be passed to the `function'
 634  *    and can be encoded into the buffer.  The buffer will be passed as
 635  *    well to the `function' at the location where SILC_STR_FUNC is placed
 636  *    in formatting.  The `context' delivers caller specific context to
 637  *    the `function'
 638  *
 639  *    In unformatting the `function' will decode the encoded type and
 640  *    return it to `value' pointer.  The decoding function should decide
 641  *    itself whether to allocate or not the decoded value.
 642  *
 643  *    The `function' does not have to encode anything and passing `value'
 644  *    as NULL is allowed.  The `function' could for example modify the
 645  *    existing buffer.
 646  *
 647  * EXAMPLE
 648  *
 649  *    // Encode payload, encrypt and compute MAC.
 650  *    silc_buffer_format(buf,
 651  *                       SILC_STR_FUNC(foo_encode_id, id, ctx),
 652  *                       SILC_STR_UI_SHORT(len),
 653  *                       SILC_STR_DATA(data, len),
 654  *                       SILC_STR_FUNC(foo_buf_encrypt, NULL, key),
 655  *                       SILC_STR_FUNC(foo_buf_hmac, NULL, hmac),
 656  *                       SILC_STR_DATA(iv, iv_len);
 657  *                       SILC_STR_END);
 658  *
 659  *    // Check MAC, decrypt and decode payload
 660  *    silc_buffer_unformat(buf,
 661  *                         SILC_STR_FUNC(foo_buf_hmac, NULL, hmac),
 662  *                         SILC_STR_FUNC(foo_buf_decrypt, NULL, key),
 663  *                         SILC_STR_FUNC(foo_decode_id, &id, ctx),
 664  *                         SILC_STR_UI_SHORT(&len),
 665  *                         SILC_STR_END);
 666  *
 667  ***/
 668 #define SILC_STR_FUNC(func, val, context) SILC_PARAM_FUNC, \
 669     func, (val), (context)
 670
 671 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_OFFSET
 672  *
 673  * NAME
 674  *
 675  *    #define SILC_STR_OFFSET() ...
 676  *
 677  * DESCRIPTION
 678  *
 679  *    Offset in buffer.  This can be used in formatting and unformatting to
 680  *    move the data pointer of the buffer either forwards (positive offset)
 681  *    or backwards (negative offset).  It can be used to for example skip
 682  *    some types during unformatting.
 683  *
 684  *    Example:
 685  *
 686  *    ..., SILC_STR_OFFSET(5), ...
 687  *    ..., SILC_STR_OFFSET(-3), ...
 688  *
 689  *    Moves the data pointer at the point of the offset either forward
 690  *    or backward and then moves to the next type.  Multiple SILC_STR_OFFSETs
 691  *    can be used in formatting and unformatting at the same time.
 692  *
 693  ***/
 694 #define SILC_STR_OFFSET(x) SILC_PARAM_OFFSET, (x)
 695
 696 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_ADVANCE
 697  *
 698  * NAME
 699  *
 700  *    #define SILC_STR_ADVANCE ...
 701  *
 702  * DESCRIPTION
 703  *
 704  *    Advance the buffer to the end of the data after the formatting is
 705  *    done.  In normal operation when the formatted data is written the
 706  *    buffer is located at the start of the data.  With SILC_STR_ADVANCE
 707  *    the buffer will be located at the end of the data.  This makes it
 708  *    easy to add new data immediately after the previously added data.
 709  *    The SILC_STR_ADVANCE may also be used in unformatting.
 710  *
 711  * EXAMPLE
 712  *
 713  *    do {
 714  *      len = read(fd, buf, sizeof(buf));
 715  *      if (len > 0)
 716  *        // Add read data to the buffer
 717  *        silc_buffer_format(buffer,
 718  *                           SILC_STR_ADVANCE,
 719  *                           SILC_STR_DATA(buf, len),
 720  *                           SILC_STR_END);
 721  *    } while (len > 0);
 722  *
 723  *    // Move to beginning of buffer
 724  *    silc_buffer_start(buffer);
 725  *
 726  ***/
 727 #define SILC_STR_ADVANCE SILC_PARAM_ADVANCE
 728
 729 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_END
 730  *
 731  * NAME
 732  *
 733  *    #define SILC_STR_END ...
 734  *
 735  * DESCRIPTION
 736  *
 737  *    Marks end of the argument list. This must be at the end of the
 738  *    argument list or error will occur.
 739  *
 740  ***/
 741 #define SILC_STR_END SILC_PARAM_END
 742
 743 /****d* silcutil/SilcBufferFormatAPI/SILC_STRFMT_END
 744  *
 745  * NAME
 746  *
 747  *    #define SILC_STRFMT_END ...
 748  *
 749  * DESCRIPTION
 750  *
 751  *    Marks end of the argument list in silc_buffer_strformat function.
 752  *    This must be at the end of the argument list or error will occur.
 753  *
 754  ***/
 755 #define SILC_STRFMT_END (void *)SILC_STR_END
 756
 757 #endif  /* !SILCBUFFMT_H */