lib/silcutil/silcbuffmt.h

   1 /*
   2
   3   silcbuffmt.h
   4
   5   Author: Pekka Riikonen <priikone@poseidon.pspt.fi>
   6
   7   Copyright (C) 1997 - 2000 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; either version 2 of the License, or
  12   (at your option) any later version.
  13
  14   This program is distributed in the hope that it will be useful,
  15   but WITHOUT ANY WARRANTY; without even the implied warranty of
  16   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17   GNU General Public License for more details.
  18
  19 */
  20
  21 #ifndef SILCBUFFMT_H
  22 #define SILCBUFFMT_H
  23
  24 /* Buffer parameter types.
  25
  26    _SI_ = signed
  27    _UI_ = unsigned
  28
  29   Any XXX_STRING_ALLOC types will allocate space for the data and
  30   memcpy the data to the pointer sent as argument (in unformatting).
  31
  32   Any XXX_STRING will not allocate or copy any data.  Instead it
  33   will set the pointer to the data.  Note that the data pointer
  34   returned (in unformatting) must not be freed.
  35
  36 */
  37 typedef enum {
  38   SILC_BUFFER_PARAM_SI8_CHAR,
  39   SILC_BUFFER_PARAM_UI8_CHAR,
  40
  41   SILC_BUFFER_PARAM_SI16_SHORT,
  42   SILC_BUFFER_PARAM_UI16_SHORT,
  43
  44   SILC_BUFFER_PARAM_SI32_INT,
  45   SILC_BUFFER_PARAM_UI32_INT,
  46
  47   SILC_BUFFER_PARAM_SI64_INT,
  48   SILC_BUFFER_PARAM_UI64_INT,
  49
  50   SILC_BUFFER_PARAM_UI8_STRING,         /* No copy */
  51   SILC_BUFFER_PARAM_UI8_STRING_ALLOC,   /* Alloc + memcpy */
  52   SILC_BUFFER_PARAM_UI16_STRING,        /* No copy */
  53   SILC_BUFFER_PARAM_UI16_STRING_ALLOC,  /* Alloc + memcpy */
  54   SILC_BUFFER_PARAM_UI32_STRING,        /* No copy */
  55   SILC_BUFFER_PARAM_UI32_STRING_ALLOC,  /* Alloc + memcpy */
  56   SILC_BUFFER_PARAM_UI8_NSTRING,        /* No copy */
  57   SILC_BUFFER_PARAM_UI8_NSTRING_ALLOC,  /* Alloc + memcpy */
  58   SILC_BUFFER_PARAM_UI16_NSTRING,       /* No copy */
  59   SILC_BUFFER_PARAM_UI16_NSTRING_ALLOC, /* Alloc + memcpy */
  60   SILC_BUFFER_PARAM_UI32_NSTRING,       /* No copy */
  61   SILC_BUFFER_PARAM_UI32_NSTRING_ALLOC, /* Alloc + memcpy */
  62   SILC_BUFFER_PARAM_UI_XNSTRING,        /* No copy */
  63   SILC_BUFFER_PARAM_UI_XNSTRING_ALLOC,  /* Alloc + memcpy */
  64
  65   SILC_BUFFER_PARAM_END
  66 } SilcBufferParamType;
  67
  68 /* Macros for expanding parameters into variable function argument list.
  69    These are passed to silc_buffer_format and silc_buffer_unformat
  70    functions. */
  71
  72 /* One signed/unsigned character.
  73
  74    Formatting:    SILC_STR_SI_CHAR(char)
  75                   SILC_STR_UI_CHAR(unsigned char)
  76    Unformatting:  SILC_STR_SI_CHAR(char *)
  77                   SILC_STR_UI_CHAR(unsigned char *)
  78
  79 */
  80 #define SILC_STR_SI_CHAR(x) SILC_BUFFER_PARAM_SI8_CHAR, (x)
  81 #define SILC_STR_UI_CHAR(x) SILC_BUFFER_PARAM_UI8_CHAR, (x)
  82
  83 /* Signed/uint16.
  84
  85    Formatting:    SILC_STR_SI_SHORT(short)
  86                   SILC_STR_UI_SHORT(uint16)
  87    Unformatting:  SILC_STR_SI_SHORT(short *)
  88                   SILC_STR_UI_SHORT(uint16 *)
  89
  90 */
  91 #define SILC_STR_SI_SHORT(x) SILC_BUFFER_PARAM_SI16_SHORT, (x)
  92 #define SILC_STR_UI_SHORT(x) SILC_BUFFER_PARAM_UI16_SHORT, (x)
  93
  94 /* Signed/uint32.
  95
  96    Formatting:    SILC_STR_SI_INT(int)
  97                   SILC_STR_UI_INT(uint32)
  98    Unformatting:  SILC_STR_SI_INT(int *)
  99                   SILC_STR_UI_INT(uint32 *)
 100
 101 */
 102 #define SILC_STR_SI_INT(x) SILC_BUFFER_PARAM_SI32_INT, (x)
 103 #define SILC_STR_UI_INT(x) SILC_BUFFER_PARAM_UI32_INT, (x)
 104
 105 /* Signed/uint64.
 106
 107    Formatting:    SILC_STR_SI_INT64(int)
 108                   SILC_STR_UI_INT64(uint32)
 109    Unformatting:  SILC_STR_SI_INT64(int *)
 110                   SILC_STR_UI_INT64(uint32 *)
 111
 112 */
 113 #define SILC_STR_SI_INT64(x) SILC_BUFFER_PARAM_SI64_INT, (x)
 114 #define SILC_STR_UI_INT64(x) SILC_BUFFER_PARAM_UI64_INT, (x)
 115
 116 /* Unsigned NULL terminated string. Note that the string must be
 117    NULL terminated because strlen() will be used to get the length of
 118    the string.
 119
 120    Formatting:    SILC_STR_UI32_STRING(unsigned char *)
 121    Unformatting:  SILC_STR_UI32_STRING(unsigned char **)
 122
 123    Unformatting procedure will check for length of the string from the
 124    buffer before trying to get the string out. Thus, one *must* format the
 125    length as UI_INT or UI_SHORT into the buffer *before* formatting the
 126    actual string to the buffer, and, in unformatting one must ignore the
 127    length of the string because unformatting procedure will take it
 128    automatically.
 129
 130    Example:
 131
 132    Formatting:    ..., SILC_STR_UI_INT(strlen(string)),
 133                        SILC_STR_UI32_STRING(string), ...
 134    Unformatting:  ..., SILC_STR_UI32_STRING(&string), ...
 135
 136    I.e., you ignore the formatted length field in unformatting. If you don't
 137    the unformatting procedure might fail and it definitely does not unformat
 138    the data reliably.
 139
 140    _ALLOC routines automatically allocates memory for the variable sent
 141    as argument in unformatting.
 142
 143 */
 144 #define SILC_STR_UI8_STRING(x) SILC_BUFFER_PARAM_UI8_STRING, (x)
 145 #define SILC_STR_UI8_STRING_ALLOC(x) SILC_BUFFER_PARAM_UI8_STRING_ALLOC, (x)
 146 #define SILC_STR_UI16_STRING(x) SILC_BUFFER_PARAM_UI16_STRING, (x)
 147 #define SILC_STR_UI16_STRING_ALLOC(x) SILC_BUFFER_PARAM_UI16_STRING_ALLOC, (x)
 148 #define SILC_STR_UI32_STRING(x) SILC_BUFFER_PARAM_UI32_STRING, (x)
 149 #define SILC_STR_UI32_STRING_ALLOC(x) SILC_BUFFER_PARAM_UI32_STRING_ALLOC, (x)
 150
 151 /* Unsigned string. Second argument is the length of the string.
 152
 153    Formatting:    SILC_STR_UI32_NSTRING(unsigned char *, uint32)
 154    Unformatting:  SILC_STR_UI32_NSTRING(unsigned char **, uint32 *)
 155
 156    Unformatting procedure will check for length of the string from the
 157    buffer before trying to get the string out. Thus, one *must* format the
 158    length as UI_INT or UI_SHORT into the buffer *before* formatting the
 159    actual string to the buffer, and, in unformatting one must ignore the
 160    length of the string because unformatting procedure will take it
 161    automatically.
 162
 163    Example:
 164
 165    Formatting:    ..., SILC_STR_UI_INT(strlen(string)),
 166                        SILC_STR_UI32_NSTRING(string, strlen(string)), ...
 167    Unformatting:  ..., SILC_STR_UI32_NSTRING(&string, &len), ...
 168
 169    I.e., you ignore the formatted length field in unformatting. If you don't
 170    the unformatting procedure might fail and it definitely does not unformat
 171    the data reliably. The length taken from the buffer is returned to the
 172    pointer sent as argument (&len in above example).
 173
 174    UI/SI16 and UI/SI32 means that the length is considered to be either
 175    short (16 bits) or int (32 bits) in unformatting.
 176
 177    _ALLOC routines automatically allocates memory for the variable sent
 178    as argument in unformatting.
 179
 180 */
 181 #define SILC_STR_UI8_NSTRING(x, l) SILC_BUFFER_PARAM_UI8_NSTRING, (x), (l)
 182 #define SILC_STR_UI8_NSTRING_ALLOC(x, l) \
 183   SILC_BUFFER_PARAM_UI8_NSTRING_ALLOC, (x), (l)
 184 #define SILC_STR_UI16_NSTRING(x, l) SILC_BUFFER_PARAM_UI16_NSTRING, (x), (l)
 185 #define SILC_STR_UI16_NSTRING_ALLOC(x, l) \
 186   SILC_BUFFER_PARAM_UI16_NSTRING_ALLOC, (x), (l)
 187 #define SILC_STR_UI32_NSTRING(x, l) SILC_BUFFER_PARAM_UI32_NSTRING, (x), (l)
 188 #define SILC_STR_UI32_NSTRING_ALLOC(x, l) \
 189   SILC_BUFFER_PARAM_UI32_NSTRING_ALLOC, (x), (l)
 190
 191 /* Extended Unsigned string formatting. Second argument is the length of
 192    the string.
 193
 194    Formatting:    This is equal to using *_NSTRING
 195    Unformatting:  SILC_STR_UI_XNSTRING(unsigned char **, uint32)
 196
 197    This type can be used to take arbitrary length string from the buffer
 198    by sending the requested amount of bytes as argument. This differs
 199    from *_STRING and *_NSTRING so that this doesn't try to find the
 200    length of the data from the buffer but the length of the data is
 201    sent as argument. This a handy way to unformat fixed length strings
 202    from the buffer without having the length of the string formatted
 203    in the buffer.
 204
 205    _ALLOC routines automatically allocates memory for the variable sent
 206    as argument in unformatting.
 207
 208 */
 209 #define SILC_STR_UI_XNSTRING(x, l) SILC_BUFFER_PARAM_UI_XNSTRING, (x), (l)
 210 #define SILC_STR_UI_XNSTRING_ALLOC(x, l) \
 211   SILC_BUFFER_PARAM_UI_XNSTRING_ALLOC, (x), (l)
 212
 213 /* Marks end of the argument list. This must be at the end of the
 214    argument list or error will occur. */
 215 #define SILC_STR_END SILC_BUFFER_PARAM_END
 216
 217 /* Prototypes */
 218
 219 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_format
 220  *
 221  * SYNOPSIS
 222  *
 223  *    int silc_buffer_format(SilcBuffer dst, ...);
 224  *
 225  * DESCRIPTION
 226  *
 227  *    Formats a buffer from a variable argument list.  Returns -1 on error
 228  *    and the length of the formatted buffer otherwise.
 229  *
 230  ***/
 231 int silc_buffer_format(SilcBuffer dst, ...);
 232
 233 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_unformat
 234  *
 235  * SYNOPSIS
 236  *
 237  *    int silc_buffer_unformat(SilcBuffer src, ...);
 238  *
 239  * DESCRIPTION
 240  *
 241  *    Formats a buffer from a variable argument list.  Returns -1 on error
 242  *    and the length of the formatted buffer otherwise.
 243  *
 244  ***/
 245 int silc_buffer_unformat(SilcBuffer src, ...);
 246
 247 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_format
 248  *
 249  * SYNOPSIS
 250  *
 251  *    int silc_buffer_format_vp(SilcBuffer dst, va_list vp);
 252  *
 253  * DESCRIPTION
 254  *
 255  *    Formats a buffer from a variable argument list indicated by the `ap'.
 256  *    Returns -1 on error and the length of the formatted buffer otherwise.
 257  *
 258  ***/
 259 int silc_buffer_format_vp(SilcBuffer dst, va_list ap);
 260
 261 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_unformat
 262  *
 263  * SYNOPSIS
 264  *
 265  *    int silc_buffer_unformat_vp(SilcBuffer src, va_list vp);
 266  *
 267  * DESCRIPTION
 268  *
 269  *    Formats a buffer from a variable argument list indicated by the `ap'.
 270  *    Returns -1 on error and the length of the formatted buffer otherwise.
 271  *
 272  ***/
 273 int silc_buffer_unformat_vp(SilcBuffer src, va_list ap);
 274
 275 #endif