lib/silccore/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 */
  30 typedef enum {
  31   SILC_BUFFER_PARAM_SI8_CHAR,
  32   SILC_BUFFER_PARAM_UI8_CHAR,
  33
  34   SILC_BUFFER_PARAM_SI16_SHORT,
  35   SILC_BUFFER_PARAM_UI16_SHORT,
  36
  37   SILC_BUFFER_PARAM_SI32_INT,
  38   SILC_BUFFER_PARAM_UI32_INT,
  39
  40   SILC_BUFFER_PARAM_UI16_STRING,
  41   SILC_BUFFER_PARAM_UI16_STRING_ALLOC,
  42   SILC_BUFFER_PARAM_UI32_STRING,
  43   SILC_BUFFER_PARAM_UI32_STRING_ALLOC,
  44   SILC_BUFFER_PARAM_UI16_NSTRING,
  45   SILC_BUFFER_PARAM_UI16_NSTRING_ALLOC,
  46   SILC_BUFFER_PARAM_UI32_NSTRING,
  47   SILC_BUFFER_PARAM_UI32_NSTRING_ALLOC,
  48   SILC_BUFFER_PARAM_UI_XNSTRING,
  49   SILC_BUFFER_PARAM_UI_XNSTRING_ALLOC,
  50
  51   SILC_BUFFER_PARAM_END
  52 } SilcBufferParamType;
  53
  54 /* Macros for expanding parameters into variable function argument list.
  55    These are passed to silc_buffer_format and silc_buffer_unformat
  56    functions. */
  57
  58 /* One signed/unsigned character.
  59
  60    Formatting:    SILC_STR_SI_CHAR(char)
  61                   SILC_STR_UI_CHAR(unsigned char)
  62    Unformatting:  SILC_STR_SI_CHAR(char *)
  63                   SILC_STR_UI_CHAR(unsigned char *)
  64
  65 */
  66 #define SILC_STR_SI_CHAR(x) SILC_BUFFER_PARAM_SI8_CHAR, (x)
  67 #define SILC_STR_UI_CHAR(x) SILC_BUFFER_PARAM_UI8_CHAR, (x)
  68
  69 /* Signed/unsigned short.
  70
  71    Formatting:    SILC_STR_SI_SHORT(short)
  72                   SILC_STR_UI_SHORT(unsigned short)
  73    Unformatting:  SILC_STR_SI_SHORT(short *)
  74                   SILC_STR_UI_SHORT(unsigned short *)
  75
  76 */
  77 #define SILC_STR_SI_SHORT(x) SILC_BUFFER_PARAM_SI16_SHORT, (x)
  78 #define SILC_STR_UI_SHORT(x) SILC_BUFFER_PARAM_UI16_SHORT, (x)
  79
  80 /* Signed/unsigned int.
  81
  82    Formatting:    SILC_STR_SI_INT(int)
  83                   SILC_STR_UI_INT(unsigned int)
  84    Unformatting:  SILC_STR_SI_INT(int *)
  85                   SILC_STR_UI_INT(unsigned int *)
  86
  87 */
  88 #define SILC_STR_SI_INT(x) SILC_BUFFER_PARAM_SI32_INT, (x)
  89 #define SILC_STR_UI_INT(x) SILC_BUFFER_PARAM_UI32_INT, (x)
  90
  91 /* Unsigned NULL terminated string. Note that the string must be
  92    NULL terminated because strlen() will be used to get the length of
  93    the string.
  94
  95    Formatting:    SILC_STR_UI32_STRING(unsigned char *)
  96    Unformatting:  SILC_STR_UI32_STRING(unsigned char **)
  97
  98    Unformatting procedure will check for length of the string from the
  99    buffer before trying to get the string out. Thus, one *must* format the
 100    length as UI_INT or UI_SHORT into the buffer *before* formatting the
 101    actual string to the buffer, and, in unformatting one must ignore the
 102    length of the string because unformatting procedure will take it
 103    automatically.
 104
 105    Example:
 106
 107    Formatting:    ..., SILC_STR_UI_INT(strlen(string)),
 108                        SILC_STR_UI32_STRING(string), ...
 109    Unformatting:  ..., SILC_STR_UI32_STRING(&string), ...
 110
 111    I.e., you ignore the formatted length field in unformatting. If you don't
 112    the unformatting procedure might fail and it definitely does not unformat
 113    the data reliably.
 114
 115    _ALLOC routines automatically allocates memory for the variable sent
 116    as argument in unformatting.
 117
 118 */
 119 #define SILC_STR_UI16_STRING(x) SILC_BUFFER_PARAM_UI16_STRING, (x)
 120 #define SILC_STR_UI16_STRING_ALLOC(x) SILC_BUFFER_PARAM_UI16_STRING_ALLOC, (x)
 121 #define SILC_STR_UI32_STRING(x) SILC_BUFFER_PARAM_UI32_STRING, (x)
 122 #define SILC_STR_UI32_STRING_ALLOC(x) SILC_BUFFER_PARAM_UI32_STRING_ALLOC, (x)
 123
 124 /* Unsigned string. Second argument is the length of the string.
 125
 126    Formatting:    SILC_STR_UI32_NSTRING(unsigned char *, unsigned int)
 127    Unformatting:  SILC_STR_UI32_NSTRING(unsigned char **, unsigned int *)
 128
 129    Unformatting procedure will check for length of the string from the
 130    buffer before trying to get the string out. Thus, one *must* format the
 131    length as UI_INT or UI_SHORT into the buffer *before* formatting the
 132    actual string to the buffer, and, in unformatting one must ignore the
 133    length of the string because unformatting procedure will take it
 134    automatically.
 135
 136    Example:
 137
 138    Formatting:    ..., SILC_STR_UI_INT(strlen(string)),
 139                        SILC_STR_UI32_NSTRING(string, strlen(string)), ...
 140    Unformatting:  ..., SILC_STR_UI32_NSTRING(&string, &len), ...
 141
 142    I.e., you ignore the formatted length field in unformatting. If you don't
 143    the unformatting procedure might fail and it definitely does not unformat
 144    the data reliably. The length taken from the buffer is returned to the
 145    pointer sent as argument (&len in above example).
 146
 147    UI/SI16 and UI/SI32 means that the length is considered to be either
 148    short (16 bits) or int (32 bits) in unformatting.
 149
 150    _ALLOC routines automatically allocates memory for the variable sent
 151    as argument in unformatting.
 152
 153 */
 154 #define SILC_STR_UI16_NSTRING(x, l) SILC_BUFFER_PARAM_UI16_NSTRING, (x), (l)
 155 #define SILC_STR_UI16_NSTRING_ALLOC(x, l) \
 156   SILC_BUFFER_PARAM_UI16_NSTRING_ALLOC, (x), (l)
 157 #define SILC_STR_UI32_NSTRING(x, l) SILC_BUFFER_PARAM_UI32_NSTRING, (x), (l)
 158 #define SILC_STR_UI32_NSTRING_ALLOC(x, l) \
 159   SILC_BUFFER_PARAM_UI32_NSTRING_ALLOC, (x), (l)
 160
 161 /* Extended Unsigned string formatting. Second argument is the length of
 162    the string.
 163
 164    Formatting:    This is equal to using *_NSTRING
 165    Unformatting:  SILC_STR_UI_XNSTRING(unsigned char **, unsigned int)
 166
 167    This type can be used to take arbitrary length string from the buffer
 168    by sending the requested amount of bytes as argument. This differs
 169    from *_STRING and *_NSTRING so that this doesn't try to find the
 170    length of the data from the buffer but the length of the data is
 171    sent as argument. This a handy way to unformat fixed length strings
 172    from the buffer without having the length of the string formatted
 173    in the buffer.
 174
 175    _ALLOC routines automatically allocates memory for the variable sent
 176    as argument in unformatting.
 177
 178 */
 179 #define SILC_STR_UI_XNSTRING(x, l) SILC_BUFFER_PARAM_UI_XNSTRING, (x), (l)
 180 #define SILC_STR_UI_XNSTRING_ALLOC(x, l) \
 181   SILC_BUFFER_PARAM_UI_XNSTRING_ALLOC, (x), (l)
 182
 183 /* Marks end of the argument list. This must the at the end of the
 184    argument list or error will occur. */
 185 #define SILC_STR_END SILC_BUFFER_PARAM_END
 186
 187 /* Prototypes */
 188 int silc_buffer_format(SilcBuffer dst, ...);
 189 int silc_buffer_unformat(SilcBuffer src, ...);
 190
 191 #endif