5 Author: Pekka Riikonen <priikone@poseidon.pspt.fi>
7 Copyright (C) 1997 - 2000 Pekka Riikonen
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.
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.
21 /****h* silcutil/SilcBufferFormatAPI
25 * SILC Buffer Format API provides a few functions for formatting
26 * various different data types into a buffer, and retrieving
27 * various data from buffer into specific data types. It is usefull
28 * to format for example packets and later unformat them.
35 /* Buffer parameter types.
40 Any XXX_STRING_ALLOC types will allocate space for the data and
41 memcpy the data to the pointer sent as argument (in unformatting).
43 Any XXX_STRING will not allocate or copy any data. Instead it
44 will set the pointer to the data. Note that the data pointer
45 returned (in unformatting) must not be freed.
49 SILC_BUFFER_PARAM_SI8_CHAR,
50 SILC_BUFFER_PARAM_UI8_CHAR,
52 SILC_BUFFER_PARAM_SI16_SHORT,
53 SILC_BUFFER_PARAM_UI16_SHORT,
55 SILC_BUFFER_PARAM_SI32_INT,
56 SILC_BUFFER_PARAM_UI32_INT,
58 SILC_BUFFER_PARAM_SI64_INT,
59 SILC_BUFFER_PARAM_UI64_INT,
61 SILC_BUFFER_PARAM_UI8_STRING, /* No copy */
62 SILC_BUFFER_PARAM_UI8_STRING_ALLOC, /* Alloc + memcpy */
63 SILC_BUFFER_PARAM_UI16_STRING, /* No copy */
64 SILC_BUFFER_PARAM_UI16_STRING_ALLOC, /* Alloc + memcpy */
65 SILC_BUFFER_PARAM_UI32_STRING, /* No copy */
66 SILC_BUFFER_PARAM_UI32_STRING_ALLOC, /* Alloc + memcpy */
67 SILC_BUFFER_PARAM_UI8_NSTRING, /* No copy */
68 SILC_BUFFER_PARAM_UI8_NSTRING_ALLOC, /* Alloc + memcpy */
69 SILC_BUFFER_PARAM_UI16_NSTRING, /* No copy */
70 SILC_BUFFER_PARAM_UI16_NSTRING_ALLOC, /* Alloc + memcpy */
71 SILC_BUFFER_PARAM_UI32_NSTRING, /* No copy */
72 SILC_BUFFER_PARAM_UI32_NSTRING_ALLOC, /* Alloc + memcpy */
73 SILC_BUFFER_PARAM_UI_XNSTRING, /* No copy */
74 SILC_BUFFER_PARAM_UI_XNSTRING_ALLOC, /* Alloc + memcpy */
77 } SilcBufferParamType;
79 /* Macros for expanding parameters into variable function argument list.
80 These are passed to silc_buffer_format and silc_buffer_unformat
83 /* One signed/unsigned character.
85 Formatting: SILC_STR_SI_CHAR(char)
86 SILC_STR_UI_CHAR(unsigned char)
87 Unformatting: SILC_STR_SI_CHAR(char *)
88 SILC_STR_UI_CHAR(unsigned char *)
91 #define SILC_STR_SI_CHAR(x) SILC_BUFFER_PARAM_SI8_CHAR, (x)
92 #define SILC_STR_UI_CHAR(x) SILC_BUFFER_PARAM_UI8_CHAR, (x)
96 Formatting: SILC_STR_SI_SHORT(short)
97 SILC_STR_UI_SHORT(uint16)
98 Unformatting: SILC_STR_SI_SHORT(short *)
99 SILC_STR_UI_SHORT(uint16 *)
102 #define SILC_STR_SI_SHORT(x) SILC_BUFFER_PARAM_SI16_SHORT, (x)
103 #define SILC_STR_UI_SHORT(x) SILC_BUFFER_PARAM_UI16_SHORT, (x)
107 Formatting: SILC_STR_SI_INT(int)
108 SILC_STR_UI_INT(uint32)
109 Unformatting: SILC_STR_SI_INT(int *)
110 SILC_STR_UI_INT(uint32 *)
113 #define SILC_STR_SI_INT(x) SILC_BUFFER_PARAM_SI32_INT, (x)
114 #define SILC_STR_UI_INT(x) SILC_BUFFER_PARAM_UI32_INT, (x)
118 Formatting: SILC_STR_SI_INT64(int)
119 SILC_STR_UI_INT64(uint32)
120 Unformatting: SILC_STR_SI_INT64(int *)
121 SILC_STR_UI_INT64(uint32 *)
124 #define SILC_STR_SI_INT64(x) SILC_BUFFER_PARAM_SI64_INT, (x)
125 #define SILC_STR_UI_INT64(x) SILC_BUFFER_PARAM_UI64_INT, (x)
127 /* Unsigned NULL terminated string. Note that the string must be
128 NULL terminated because strlen() will be used to get the length of
131 Formatting: SILC_STR_UI32_STRING(unsigned char *)
132 Unformatting: SILC_STR_UI32_STRING(unsigned char **)
134 Unformatting procedure will check for length of the string from the
135 buffer before trying to get the string out. Thus, one *must* format the
136 length as UI_INT or UI_SHORT into the buffer *before* formatting the
137 actual string to the buffer, and, in unformatting one must ignore the
138 length of the string because unformatting procedure will take it
143 Formatting: ..., SILC_STR_UI_INT(strlen(string)),
144 SILC_STR_UI32_STRING(string), ...
145 Unformatting: ..., SILC_STR_UI32_STRING(&string), ...
147 I.e., you ignore the formatted length field in unformatting. If you don't
148 the unformatting procedure might fail and it definitely does not unformat
151 _ALLOC routines automatically allocates memory for the variable sent
152 as argument in unformatting.
155 #define SILC_STR_UI8_STRING(x) SILC_BUFFER_PARAM_UI8_STRING, (x)
156 #define SILC_STR_UI8_STRING_ALLOC(x) SILC_BUFFER_PARAM_UI8_STRING_ALLOC, (x)
157 #define SILC_STR_UI16_STRING(x) SILC_BUFFER_PARAM_UI16_STRING, (x)
158 #define SILC_STR_UI16_STRING_ALLOC(x) SILC_BUFFER_PARAM_UI16_STRING_ALLOC, (x)
159 #define SILC_STR_UI32_STRING(x) SILC_BUFFER_PARAM_UI32_STRING, (x)
160 #define SILC_STR_UI32_STRING_ALLOC(x) SILC_BUFFER_PARAM_UI32_STRING_ALLOC, (x)
162 /* Unsigned string. Second argument is the length of the string.
164 Formatting: SILC_STR_UI32_NSTRING(unsigned char *, uint32)
165 Unformatting: SILC_STR_UI32_NSTRING(unsigned char **, uint32 *)
167 Unformatting procedure will check for length of the string from the
168 buffer before trying to get the string out. Thus, one *must* format the
169 length as UI_INT or UI_SHORT into the buffer *before* formatting the
170 actual string to the buffer, and, in unformatting one must ignore the
171 length of the string because unformatting procedure will take it
176 Formatting: ..., SILC_STR_UI_INT(strlen(string)),
177 SILC_STR_UI32_NSTRING(string, strlen(string)), ...
178 Unformatting: ..., SILC_STR_UI32_NSTRING(&string, &len), ...
180 I.e., you ignore the formatted length field in unformatting. If you don't
181 the unformatting procedure might fail and it definitely does not unformat
182 the data reliably. The length taken from the buffer is returned to the
183 pointer sent as argument (&len in above example).
185 UI/SI16 and UI/SI32 means that the length is considered to be either
186 short (16 bits) or int (32 bits) in unformatting.
188 _ALLOC routines automatically allocates memory for the variable sent
189 as argument in unformatting.
192 #define SILC_STR_UI8_NSTRING(x, l) SILC_BUFFER_PARAM_UI8_NSTRING, (x), (l)
193 #define SILC_STR_UI8_NSTRING_ALLOC(x, l) \
194 SILC_BUFFER_PARAM_UI8_NSTRING_ALLOC, (x), (l)
195 #define SILC_STR_UI16_NSTRING(x, l) SILC_BUFFER_PARAM_UI16_NSTRING, (x), (l)
196 #define SILC_STR_UI16_NSTRING_ALLOC(x, l) \
197 SILC_BUFFER_PARAM_UI16_NSTRING_ALLOC, (x), (l)
198 #define SILC_STR_UI32_NSTRING(x, l) SILC_BUFFER_PARAM_UI32_NSTRING, (x), (l)
199 #define SILC_STR_UI32_NSTRING_ALLOC(x, l) \
200 SILC_BUFFER_PARAM_UI32_NSTRING_ALLOC, (x), (l)
202 /* Extended Unsigned string formatting. Second argument is the length of
205 Formatting: This is equal to using *_NSTRING
206 Unformatting: SILC_STR_UI_XNSTRING(unsigned char **, uint32)
208 This type can be used to take arbitrary length string from the buffer
209 by sending the requested amount of bytes as argument. This differs
210 from *_STRING and *_NSTRING so that this doesn't try to find the
211 length of the data from the buffer but the length of the data is
212 sent as argument. This a handy way to unformat fixed length strings
213 from the buffer without having the length of the string formatted
216 _ALLOC routines automatically allocates memory for the variable sent
217 as argument in unformatting.
220 #define SILC_STR_UI_XNSTRING(x, l) SILC_BUFFER_PARAM_UI_XNSTRING, (x), (l)
221 #define SILC_STR_UI_XNSTRING_ALLOC(x, l) \
222 SILC_BUFFER_PARAM_UI_XNSTRING_ALLOC, (x), (l)
224 /* Marks end of the argument list. This must be at the end of the
225 argument list or error will occur. */
226 #define SILC_STR_END SILC_BUFFER_PARAM_END
230 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_format
234 * int silc_buffer_format(SilcBuffer dst, ...);
238 * Formats a buffer from a variable argument list. Returns -1 on error
239 * and the length of the formatted buffer otherwise.
242 int silc_buffer_format(SilcBuffer dst, ...);
244 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_unformat
248 * int silc_buffer_unformat(SilcBuffer src, ...);
252 * Formats a buffer from a variable argument list. Returns -1 on error
253 * and the length of the formatted buffer otherwise.
256 int silc_buffer_unformat(SilcBuffer src, ...);
258 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_format_vp
262 * int silc_buffer_format_vp(SilcBuffer dst, va_list vp);
266 * Formats a buffer from a variable argument list indicated by the `ap'.
267 * Returns -1 on error and the length of the formatted buffer otherwise.
270 int silc_buffer_format_vp(SilcBuffer dst, va_list ap);
272 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_unformat_vp
276 * int silc_buffer_unformat_vp(SilcBuffer src, va_list vp);
280 * Formats a buffer from a variable argument list indicated by the `ap'.
281 * Returns -1 on error and the length of the formatted buffer otherwise.
284 int silc_buffer_unformat_vp(SilcBuffer src, va_list ap);