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