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_UI16_STRING,        /* No copy */
  51   SILC_BUFFER_PARAM_UI16_STRING_ALLOC,  /* Alloc + memcpy */
  52   SILC_BUFFER_PARAM_UI32_STRING,        /* No copy */
  53   SILC_BUFFER_PARAM_UI32_STRING_ALLOC,  /* Alloc + memcpy */
  54   SILC_BUFFER_PARAM_UI16_NSTRING,       /* No copy */
  55   SILC_BUFFER_PARAM_UI16_NSTRING_ALLOC, /* Alloc + memcpy */
  56   SILC_BUFFER_PARAM_UI32_NSTRING,       /* No copy */
  57   SILC_BUFFER_PARAM_UI32_NSTRING_ALLOC, /* Alloc + memcpy */
  58   SILC_BUFFER_PARAM_UI_XNSTRING,        /* No copy */
  59   SILC_BUFFER_PARAM_UI_XNSTRING_ALLOC,  /* Alloc + memcpy */
  60
  61   SILC_BUFFER_PARAM_END
  62 } SilcBufferParamType;
  63
  64 /* Macros for expanding parameters into variable function argument list.
  65    These are passed to silc_buffer_format and silc_buffer_unformat
  66    functions. */
  67
  68 /* One signed/unsigned character.
  69
  70    Formatting:    SILC_STR_SI_CHAR(char)
  71                   SILC_STR_UI_CHAR(unsigned char)
  72    Unformatting:  SILC_STR_SI_CHAR(char *)
  73                   SILC_STR_UI_CHAR(unsigned char *)
  74
  75 */
  76 #define SILC_STR_SI_CHAR(x) SILC_BUFFER_PARAM_SI8_CHAR, (x)
  77 #define SILC_STR_UI_CHAR(x) SILC_BUFFER_PARAM_UI8_CHAR, (x)
  78
  79 /* Signed/uint16.
  80
  81    Formatting:    SILC_STR_SI_SHORT(short)
  82                   SILC_STR_UI_SHORT(uint16)
  83    Unformatting:  SILC_STR_SI_SHORT(short *)
  84                   SILC_STR_UI_SHORT(uint16 *)
  85
  86 */
  87 #define SILC_STR_SI_SHORT(x) SILC_BUFFER_PARAM_SI16_SHORT, (x)
  88 #define SILC_STR_UI_SHORT(x) SILC_BUFFER_PARAM_UI16_SHORT, (x)
  89
  90 /* Signed/uint32.
  91
  92    Formatting:    SILC_STR_SI_INT(int)
  93                   SILC_STR_UI_INT(uint32)
  94    Unformatting:  SILC_STR_SI_INT(int *)
  95                   SILC_STR_UI_INT(uint32 *)
  96
  97 */
  98 #define SILC_STR_SI_INT(x) SILC_BUFFER_PARAM_SI32_INT, (x)
  99 #define SILC_STR_UI_INT(x) SILC_BUFFER_PARAM_UI32_INT, (x)
 100
 101 /* Signed/uint64.
 102
 103    Formatting:    SILC_STR_SI_INT64(int)
 104                   SILC_STR_UI_INT64(uint32)
 105    Unformatting:  SILC_STR_SI_INT64(int *)
 106                   SILC_STR_UI_INT64(uint32 *)
 107
 108 */
 109 #define SILC_STR_SI_INT64(x) SILC_BUFFER_PARAM_SI64_INT, (x)
 110 #define SILC_STR_UI_INT64(x) SILC_BUFFER_PARAM_UI64_INT, (x)
 111
 112 /* Unsigned NULL terminated string. Note that the string must be
 113    NULL terminated because strlen() will be used to get the length of
 114    the string.
 115
 116    Formatting:    SILC_STR_UI32_STRING(unsigned char *)
 117    Unformatting:  SILC_STR_UI32_STRING(unsigned char **)
 118
 119    Unformatting procedure will check for length of the string from the
 120    buffer before trying to get the string out. Thus, one *must* format the
 121    length as UI_INT or UI_SHORT into the buffer *before* formatting the
 122    actual string to the buffer, and, in unformatting one must ignore the
 123    length of the string because unformatting procedure will take it
 124    automatically.
 125
 126    Example:
 127
 128    Formatting:    ..., SILC_STR_UI_INT(strlen(string)),
 129                        SILC_STR_UI32_STRING(string), ...
 130    Unformatting:  ..., SILC_STR_UI32_STRING(&string), ...
 131
 132    I.e., you ignore the formatted length field in unformatting. If you don't
 133    the unformatting procedure might fail and it definitely does not unformat
 134    the data reliably.
 135
 136    _ALLOC routines automatically allocates memory for the variable sent
 137    as argument in unformatting.
 138
 139 */
 140 #define SILC_STR_UI16_STRING(x) SILC_BUFFER_PARAM_UI16_STRING, (x)
 141 #define SILC_STR_UI16_STRING_ALLOC(x) SILC_BUFFER_PARAM_UI16_STRING_ALLOC, (x)
 142 #define SILC_STR_UI32_STRING(x) SILC_BUFFER_PARAM_UI32_STRING, (x)
 143 #define SILC_STR_UI32_STRING_ALLOC(x) SILC_BUFFER_PARAM_UI32_STRING_ALLOC, (x)
 144
 145 /* Unsigned string. Second argument is the length of the string.
 146
 147    Formatting:    SILC_STR_UI32_NSTRING(unsigned char *, uint32)
 148    Unformatting:  SILC_STR_UI32_NSTRING(unsigned char **, uint32 *)
 149
 150    Unformatting procedure will check for length of the string from the
 151    buffer before trying to get the string out. Thus, one *must* format the
 152    length as UI_INT or UI_SHORT into the buffer *before* formatting the
 153    actual string to the buffer, and, in unformatting one must ignore the
 154    length of the string because unformatting procedure will take it
 155    automatically.
 156
 157    Example:
 158
 159    Formatting:    ..., SILC_STR_UI_INT(strlen(string)),
 160                        SILC_STR_UI32_NSTRING(string, strlen(string)), ...
 161    Unformatting:  ..., SILC_STR_UI32_NSTRING(&string, &len), ...
 162
 163    I.e., you ignore the formatted length field in unformatting. If you don't
 164    the unformatting procedure might fail and it definitely does not unformat
 165    the data reliably. The length taken from the buffer is returned to the
 166    pointer sent as argument (&len in above example).
 167
 168    UI/SI16 and UI/SI32 means that the length is considered to be either
 169    short (16 bits) or int (32 bits) in unformatting.
 170
 171    _ALLOC routines automatically allocates memory for the variable sent
 172    as argument in unformatting.
 173
 174 */
 175 #define SILC_STR_UI16_NSTRING(x, l) SILC_BUFFER_PARAM_UI16_NSTRING, (x), (l)
 176 #define SILC_STR_UI16_NSTRING_ALLOC(x, l) \
 177   SILC_BUFFER_PARAM_UI16_NSTRING_ALLOC, (x), (l)
 178 #define SILC_STR_UI32_NSTRING(x, l) SILC_BUFFER_PARAM_UI32_NSTRING, (x), (l)
 179 #define SILC_STR_UI32_NSTRING_ALLOC(x, l) \
 180   SILC_BUFFER_PARAM_UI32_NSTRING_ALLOC, (x), (l)
 181
 182 /* Extended Unsigned string formatting. Second argument is the length of
 183    the string.
 184
 185    Formatting:    This is equal to using *_NSTRING
 186    Unformatting:  SILC_STR_UI_XNSTRING(unsigned char **, uint32)
 187
 188    This type can be used to take arbitrary length string from the buffer
 189    by sending the requested amount of bytes as argument. This differs
 190    from *_STRING and *_NSTRING so that this doesn't try to find the
 191    length of the data from the buffer but the length of the data is
 192    sent as argument. This a handy way to unformat fixed length strings
 193    from the buffer without having the length of the string formatted
 194    in the buffer.
 195
 196    _ALLOC routines automatically allocates memory for the variable sent
 197    as argument in unformatting.
 198
 199 */
 200 #define SILC_STR_UI_XNSTRING(x, l) SILC_BUFFER_PARAM_UI_XNSTRING, (x), (l)
 201 #define SILC_STR_UI_XNSTRING_ALLOC(x, l) \
 202   SILC_BUFFER_PARAM_UI_XNSTRING_ALLOC, (x), (l)
 203
 204 /* Marks end of the argument list. This must be at the end of the
 205    argument list or error will occur. */
 206 #define SILC_STR_END SILC_BUFFER_PARAM_END
 207
 208 /* Prototypes */
 209
 210 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_format
 211  *
 212  * SYNOPSIS
 213  *
 214  *    int silc_buffer_format(SilcBuffer dst, ...);
 215  *
 216  * DESCRIPTION
 217  *
 218  *    Formats a buffer from a variable argument list.  Returns -1 on error
 219  *    and the length of the formatted buffer otherwise.
 220  *
 221  ***/
 222 int silc_buffer_format(SilcBuffer dst, ...);
 223
 224 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_unformat
 225  *
 226  * SYNOPSIS
 227  *
 228  *    int silc_buffer_unformat(SilcBuffer src, ...);
 229  *
 230  * DESCRIPTION
 231  *
 232  *    Formats a buffer from a variable argument list.  Returns -1 on error
 233  *    and the length of the formatted buffer otherwise.
 234  *
 235  ***/
 236 int silc_buffer_unformat(SilcBuffer src, ...);
 237
 238 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_format
 239  *
 240  * SYNOPSIS
 241  *
 242  *    int silc_buffer_format_vp(SilcBuffer dst, va_list vp);
 243  *
 244  * DESCRIPTION
 245  *
 246  *    Formats a buffer from a variable argument list indicated by the `ap'.
 247  *    Returns -1 on error and the length of the formatted buffer otherwise.
 248  *
 249  ***/
 250 int silc_buffer_format_vp(SilcBuffer dst, va_list ap);
 251
 252 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_unformat
 253  *
 254  * SYNOPSIS
 255  *
 256  *    int silc_buffer_unformat_vp(SilcBuffer src, va_list vp);
 257  *
 258  * DESCRIPTION
 259  *
 260  *    Formats a buffer from a variable argument list indicated by the `ap'.
 261  *    Returns -1 on error and the length of the formatted buffer otherwise.
 262  *
 263  ***/
 264 int silc_buffer_unformat_vp(SilcBuffer src, va_list ap);
 265
 266 #endif