5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 1997 - 2007 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; version 2 of the License.
13 This program is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
20 /****h* silcutil/SILC Buffer Format Interface
24 * SILC Buffer Format API provides functions for formatting different data
25 * types into a buffer and retrieving different data types from a buffer
26 * into specified data types. It is especially useful to format packets,
27 * protocol payloads and such.
29 * As the SilcBuffer API is not thread-safe these routines may not be used
30 * in multithreaded environment with a same SilcBuffer context without
31 * concurrency control.
38 /****f* silcutil/SilcBufferFormatAPI/SilcBufferFormatFunc
42 * typedef int (*SilcBufferFormatFunc)(SilcBuffer buffer,
48 * Formatting function callback given with SILC_STR_FUNC type. The
49 * `buffer' is the buffer being formatted at the location where the
50 * SILC_STR_FUNC was placed in formatting. The function should call
51 * silc_buffer_enlarge before it adds the data to the buffer to make
52 * sure that it has enough space. The buffer->head points to the
53 * start of the buffer and silc_buffer_headlen() gives the length
54 * of the currently formatted data area. It is also possible to use
55 * silc_buffer_format with `buffer' which will enlarge the buffer if
58 * The `value' is the value given to SILC_STR_FUNC that is to be formatted
59 * into the buffer. It may be NULL if the function is not formatting
60 * new data into the buffer. The `context' is caller specific context.
61 * Returns -1 on error and length of the formatted value otherwise, and
62 * 0 if nothing was formatted.
65 typedef int (*SilcBufferFormatFunc)(SilcBuffer buffer, void *value,
68 /****f* silcutil/SilcBufferFormatAPI/SilcBufferSFormatFunc
72 * typedef int (*SilcBufferSFormatFunc)(SilcStack stack,
79 * Formatting function callback given with SILC_STR_FUNC type. The
80 * `buffer' is the buffer being formatted at the location where the
81 * SILC_STR_FUNC was placed in formatting. The function should call
82 * silc_buffer_senlarge before it adds the data to the buffer to make
83 * sure that it has enough space. The buffer->head points to the
84 * start of the buffer and silc_buffer_headlen() gives the length
85 * of the currently formatted data area. It is also possible to use
86 * silc_buffer_sformat with `buffer' which will enlarge the buffer if
89 * The `value' is the value given to SILC_STR_FUNC that is to be formatted
90 * into the buffer. It may be NULL if the function is not formatting
91 * new data into the buffer. The `context' is caller specific context.
92 * Returns -1 on error and length of the formatted value otherwise, and
93 * 0 if nothing was formatted.
95 * This is same as SilcBufferFormatFunc except the SilcStack will be
96 * delivered. This callback must be used when SilcStack is used with
100 typedef int (*SilcBufferSFormatFunc)(SilcStack stack, SilcBuffer buffer,
101 void *value, void *context);
103 /****f* silcutil/SilcBufferFormatAPI/SilcBufferUnformatFunc
107 * typedef int (*SilcBufferUnformatFunc)(SilcBuffer buffer,
113 * Unformatting function callback given with SILC_STR_FUNC type. The
114 * `buffer' is the buffer being unformatted and is at the location where
115 * the SILC_STR_FUNC was placed in unformatting. The function should
116 * check there is enough data in the `buffer' before trying to decode
119 * If this function unformats anything from the buffer its value is to
120 * be returned to the `value' pointer. The implementation should itself
121 * decide whether the unformatted value is allocated or not. If this
122 * function does not unformat anything, nothing is returned to `value'
124 * The `context' is caller specific context. Returns -1 on error, and
125 * length of the unformatted value otherwise, and 0 if nothing was
129 typedef int (*SilcBufferUnformatFunc)(SilcBuffer buffer, void **value,
132 /****f* silcutil/SilcBufferFormatAPI/SilcBufferSUnformatFunc
136 * typedef int (*SilcBufferSUnformatFunc)(SilcStack stack,
143 * Unformatting function callback given with SILC_STR_FUNC type. The
144 * `buffer' is the buffer being unformatted and is at the location where
145 * the SILC_STR_FUNC was placed in unformatting. The function should
146 * check there is enough data in the `buffer' before trying to decode
149 * If this function unformats anything from the buffer its value is to
150 * be returned to the `value' pointer. The implementation should itself
151 * decide whether the unformatted value is allocated or not. If this
152 * function does not unformat anything, nothing is returned to `value'
154 * The `context' is caller specific context. Returns -1 on error, and
155 * length of the unformatted value otherwise, and 0 if nothing was
158 * This is same as SilcBufferUnformatFunc except the SilcStack will be
159 * delivered. This callback must be used when SilcStack is used with
163 typedef int (*SilcBufferSUnformatFunc)(SilcStack stack, SilcBuffer buffer,
164 void **value, void *context);
168 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_format
172 * int silc_buffer_format(SilcBuffer dst, ...);
176 * Formats a buffer from a variable argument list. Returns -1 on error
177 * and the length of the formatted buffer otherwise. The buffer is
178 * enlarged automatically during formatting, if it doesn't already have
183 * Three basic ways of using silc_buffer_format:
185 * // Statically allocated zero size buffer
186 * SilcBufferStruct buffer;
188 * memset(&buffer, 0, sizeof(buffer));
189 * ret = silc_buffer_format(&buffer,
190 * SILC_STR_UI_INT(intval),
191 * SILC_STR_CHAR(charval),
192 * SILC_STR_UI_INT(intval),
193 * SILC_STR_SHORT(str_len),
194 * SILC_STR_DATA(str, str_len),
199 * // Free the allocated data
200 * silc_buffer_purge(&buffer);
202 * // Dynamically allocated zero size buffer
204 * buf = silc_buffer_alloc(0);
205 * ret = silc_buffer_format(buf,
206 * SILC_STR_UI_INT(intval),
207 * SILC_STR_CHAR(charval),
212 * // Free the allocated buffer
213 * silc_buffer_free(buf);
215 * // Dynamically allocated buffer with enough space
217 * buf = silc_buffer_alloc(2 + str_len);
218 * ret = silc_buffer_format(buf,
219 * SILC_STR_UI_SHORT(str_len),
220 * SILC_STR_DATA(str, str_len),
226 int silc_buffer_format(SilcBuffer dst, ...);
228 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_sformat
232 * int silc_buffer_sformat(SilcStack stack, SilcBuffer dst, ...);
236 * Same as silc_buffer_format but uses `stack' to allocate the memory.
237 * if `stack' is NULL reverts back to silc_buffer_format call.
240 int silc_buffer_sformat(SilcStack stack, SilcBuffer dst, ...);
242 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_format_vp
246 * int silc_buffer_format_vp(SilcBuffer dst, va_list vp);
250 * Formats a buffer from a variable argument list indicated by the `ap'.
251 * Returns -1 on error and the length of the formatted buffer otherwise.
254 int silc_buffer_format_vp(SilcBuffer dst, va_list ap);
256 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_sformat_vp
260 * int silc_buffer_sformat_vp(SilcStack stack, SilcBuffer dst, va_list vp);
264 * Same as silc_buffer_format_vp but uses `stack' to allocate the memory.
265 * if `stack' is NULL reverts back to silc_buffer_format_vp call.
268 int silc_buffer_sformat_vp(SilcStack stack, SilcBuffer dst, va_list ap);
270 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_unformat
274 * int silc_buffer_unformat(SilcBuffer src, ...);
278 * Unformats a buffer from a variable argument list. Returns -1 on error
279 * and the length of the unformatted buffer otherwise.
283 * ret = silc_buffer_unformat(buffer,
284 * SILC_STR_UI_INT(&intval),
285 * SILC_STR_CHAR(&charval),
286 * SILC_STR_OFFSET(4),
287 * SILC_STR_UI16_NSTRING_ALLOC(&str, &str_len),
293 int silc_buffer_unformat(SilcBuffer src, ...);
295 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_sunformat
299 * int silc_buffer_sunformat(SilcStack stack, SilcBuffer src, ...);
303 * Same as silc_buffer_unformat but uses `stack' to allocate the memory.
304 * if `stack' is NULL reverts back to silc_buffer_format call.
307 int silc_buffer_sunformat(SilcStack stack, SilcBuffer src, ...);
309 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_unformat_vp
313 * int silc_buffer_unformat_vp(SilcBuffer src, va_list vp);
317 * Unformats a buffer from a variable argument list indicated by the `ap'.
318 * Returns -1 on error and the length of the unformatted buffer otherwise.
321 int silc_buffer_unformat_vp(SilcBuffer src, va_list ap);
323 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_sunformat_vp
327 * int silc_buffer_sunformat_vp(SilcBuffer src, va_list vp);
331 * Same as silc_buffer_unformat_vp but uses `stack' to allocate the
332 * memory. if `stack' is NULL reverts back to silc_buffer_format_vp call.
335 int silc_buffer_sunformat_vp(SilcStack stack, SilcBuffer src, va_list ap);
337 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_strformat
341 * int silc_buffer_strformat(SilcBuffer dst, ...);
345 * Formats a buffer from variable argument list of strings. Each
346 * string must be NULL-terminated and the variable argument list must
347 * be end with SILC_STRFMT_END argument. This allows that a string in
348 * the list can be NULL, in which case it is skipped. This automatically
349 * allocates the space for the buffer data but `dst' must be already
350 * allocated by the caller.
354 * ret = silc_buffer_strformat(buffer, "foo", "bar", SILC_STRFMT_END);
359 int silc_buffer_strformat(SilcBuffer dst, ...);
361 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_sstrformat
365 * int silc_buffer_strformat(SilcStack stack, SilcBuffer dst, ...);
369 * Formats a buffer from variable argument list of strings. Each
370 * string must be NULL-terminated and the variable argument list must
371 * be end with SILC_STRFMT_END argument. This allows that a string in
372 * the list can be NULL, in which case it is skipped. This automatically
373 * allocates the space for the buffer data but `dst' must be already
374 * allocated by the caller. This function is equivalent to
375 * silc_buffer_strformat but allocates memory from `stack'.
378 int silc_buffer_sstrformat(SilcStack stack, SilcBuffer dst, ...);
380 /****d* silcutil/SilcBufferFormatAPI/SilcBufferParamType
384 * typedef enum { ... } SilcBufferParamType;
388 * Buffer parameter types. These are not needed when formatting or
389 * unformatting buffers. Use the macros such as SILC_STR_UI_CHAR and
390 * others instead. These types may be used when describing what a
391 * buffer looks like, and how it may be formatted and unformatted.
396 SILC_PARAM_SI8_CHAR, /* Signed 8-bit char */
397 SILC_PARAM_UI8_CHAR, /* Unsigned 8-bit char */
398 SILC_PARAM_SI16_SHORT, /* Signed 16-bit int */
399 SILC_PARAM_UI16_SHORT, /* Unsigned 16-bit int */
400 SILC_PARAM_SI32_INT, /* Signed 32-bit int */
401 SILC_PARAM_UI32_INT, /* Unsigned 32-bit int */
402 SILC_PARAM_SI64_INT, /* Signed 64-bit int */
403 SILC_PARAM_UI64_INT, /* Unsigned 64-bit int */
404 SILC_PARAM_UI8_STRING, /* String (max len 8-bits)*/
405 SILC_PARAM_UI16_STRING, /* String (max len 16-bits) */
406 SILC_PARAM_UI32_STRING, /* String (max len 32-bits) */
407 SILC_PARAM_BUFFER, /* SilcBuffer */
410 SILC_PARAM_DATA, /* Binary data */
411 SILC_PARAM_UI8_NSTRING, /* String (max len 8-bits) */
412 SILC_PARAM_UI16_NSTRING, /* String (max len 16-bits) */
413 SILC_PARAM_UI32_NSTRING, /* String (max len 32-bits) */
414 SILC_PARAM_UI8_STRING_ALLOC, /* Alloc + memcpy */
415 SILC_PARAM_UI16_STRING_ALLOC, /* Alloc + memcpy */
416 SILC_PARAM_UI32_STRING_ALLOC, /* Alloc + memcpy */
417 SILC_PARAM_UI8_NSTRING_ALLOC, /* Alloc + memcpy */
418 SILC_PARAM_UI16_NSTRING_ALLOC, /* Alloc + memcpy */
419 SILC_PARAM_UI32_NSTRING_ALLOC, /* Alloc + memcpy */
420 SILC_PARAM_DATA_ALLOC, /* Alloc + memcpy */
421 SILC_PARAM_BUFFER_ALLOC, /* Alloc + memcpy */
427 SILC_PARAM_UI_XNSTRING,
428 SILC_PARAM_UI_XNSTRING_ALLOC,
431 } SilcBufferParamType;
434 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_*_CHAR
438 * #define SILC_STR_UI_CHAR() ...
439 * #define SILC_STR_SI_CHAR() ...
443 * One signed/unsigned character.
445 * Formatting: SILC_STR_SI_CHAR(char)
446 * SILC_STR_UI_CHAR(unsigned char)
447 * Unformatting: SILC_STR_SI_CHAR(char *)
448 * SILC_STR_UI_CHAR(unsigned char *)
451 #define SILC_STR_SI_CHAR(x) SILC_PARAM_SI8_CHAR, (x)
452 #define SILC_STR_UI_CHAR(x) SILC_PARAM_UI8_CHAR, (x)
454 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_*_SHORT
458 * #define SILC_STR_UI_SHORT() ...
459 * #define SILC_STR_SI_SHORT() ...
463 * SilcInt16/SilcUInt16.
465 * Formatting: SILC_STR_SI_SHORT(SilcInt16)
466 * SILC_STR_UI_SHORT(SilcUInt16)
467 * Unformatting: SILC_STR_SI_SHORT(SilcInt16 *)
468 * SILC_STR_UI_SHORT(SilcUInt16 *)
471 #define SILC_STR_SI_SHORT(x) SILC_PARAM_SI16_SHORT, (x)
472 #define SILC_STR_UI_SHORT(x) SILC_PARAM_UI16_SHORT, (x)
474 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_*_INT
478 * #define SILC_STR_UI_INT() ...
479 * #define SILC_STR_SI_INT() ...
483 * SilcInt32/SilcUInt32.
485 * Formatting: SILC_STR_SI_INT(SilcInt32)
486 * SILC_STR_UI_INT(SilcUInt32)
487 * Unformatting: SILC_STR_SI_INT(SilcInt32 *)
488 * SILC_STR_UI_INT(SilcUInt32 *)
491 #define SILC_STR_SI_INT(x) SILC_PARAM_SI32_INT, (x)
492 #define SILC_STR_UI_INT(x) SILC_PARAM_UI32_INT, (x)
494 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_*_INT64
498 * #define SILC_STR_UI_INT64() ...
499 * #define SILC_STR_SI_INT64() ...
503 * SilcInt64/SilcUInt64.
505 * Formatting: SILC_STR_SI_INT64(SilcInt64)
506 * SILC_STR_UI_INT64(SilcUInt64)
507 * Unformatting: SILC_STR_SI_INT64(SilcInt64 *)
508 * SILC_STR_UI_INT64(SilcUInt64 *)
511 #define SILC_STR_SI_INT64(x) SILC_PARAM_SI64_INT, (x)
512 #define SILC_STR_UI_INT64(x) SILC_PARAM_UI64_INT, (x)
514 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_*_STRING
518 * #define SILC_STR_UI8_STRING() ...
519 * #define SILC_STR_UI8_STRING_ALLOC() ...
520 * #define SILC_STR_UI16_STRING() ...
521 * #define SILC_STR_UI16_STRING_ALLOC() ...
522 * #define SILC_STR_UI32_STRING() ...
523 * #define SILC_STR_UI32_STRING_ALLOC() ...
527 * Unsigned NULL terminated string. Note that the string must be
528 * NULL terminated because strlen() will be used to get the length of
531 * Formatting: SILC_STR_UI32_STRING(unsigned char *)
532 * Unformatting: SILC_STR_UI32_STRING(unsigned char **)
534 * Unformatting procedure will check for length of the string from the
535 * buffer before trying to get the string out. Thus, one *must* format the
536 * length as UI_INT or UI_SHORT into the buffer *before* formatting the
537 * actual string to the buffer, and, in unformatting one must ignore the
538 * length of the string because unformatting procedure will take it
543 * Formatting: ..., SILC_STR_UI_INT(strlen(string)),
544 * SILC_STR_UI32_STRING(string), ...
545 * Unformatting: ..., SILC_STR_UI32_STRING(&string), ...
547 * I.e., you can ignore the formatted length field in unformatting.
549 * UI8, UI16 and UI32 means that the length is considered to be
550 * either char (8 bits), short (16 bits) or int (32 bits) in
553 * _ALLOC routines automatically allocates memory for the variable sent
554 * as argument in unformatting.
557 #define SILC_STR_UI8_STRING(x) SILC_PARAM_UI8_STRING, (x)
558 #define SILC_STR_UI8_STRING_ALLOC(x) SILC_PARAM_UI8_STRING_ALLOC, (x)
559 #define SILC_STR_UI16_STRING(x) SILC_PARAM_UI16_STRING, (x)
560 #define SILC_STR_UI16_STRING_ALLOC(x) SILC_PARAM_UI16_STRING_ALLOC, (x)
561 #define SILC_STR_UI32_STRING(x) SILC_PARAM_UI32_STRING, (x)
562 #define SILC_STR_UI32_STRING_ALLOC(x) SILC_PARAM_UI32_STRING_ALLOC, (x)
564 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_*_NSTRING
568 * #define SILC_STR_UI8_NSTRING() ...
569 * #define SILC_STR_UI8_NSTRING_ALLOC() ...
570 * #define SILC_STR_UI16_NSTRING() ...
571 * #define SILC_STR_UI16_NSTRING_ALLOC() ...
572 * #define SILC_STR_UI32_NSTRING() ...
573 * #define SILC_STR_UI32_NSTRING_ALLOC() ...
577 * Unsigned string. Second argument is the length of the string.
579 * Formatting: SILC_STR_UI32_NSTRING(unsigned char *, SilcUInt32)
580 * Unformatting: SILC_STR_UI32_NSTRING(unsigned char **, SilcUInt32 *)
582 * Unformatting procedure will check for length of the string from the
583 * buffer before trying to get the string out. Thus, one *must* format the
584 * length as UI_INT or UI_SHORT into the buffer *before* formatting the
585 * actual string to the buffer, and, in unformatting one must ignore the
586 * length of the string because unformatting procedure will take it
591 * Formatting: ..., SILC_STR_UI_INT(strlen(string)),
592 * SILC_STR_UI32_NSTRING(string, strlen(string)), ...
593 * Unformatting: ..., SILC_STR_UI32_NSTRING(&string, &len), ...
595 * I.e., you can ignore the formatted length field in unformatting. The
596 * length taken from the buffer is returned to the pointer sent as
597 * argument (&len in above example).
599 * UI8, UI16 and UI32 means that the length is considered to be
600 * either char (8 bits), short (16 bits) or int (32 bits) in
603 * _ALLOC routines automatically allocates memory for the variable sent
604 * as argument in unformatting.
607 #define SILC_STR_UI8_NSTRING(x, l) SILC_PARAM_UI8_NSTRING, (x), (l)
608 #define SILC_STR_UI8_NSTRING_ALLOC(x, l) \
609 SILC_PARAM_UI8_NSTRING_ALLOC, (x), (l)
610 #define SILC_STR_UI16_NSTRING(x, l) SILC_PARAM_UI16_NSTRING, (x), (l)
611 #define SILC_STR_UI16_NSTRING_ALLOC(x, l) \
612 SILC_PARAM_UI16_NSTRING_ALLOC, (x), (l)
613 #define SILC_STR_UI32_NSTRING(x, l) SILC_PARAM_UI32_NSTRING, (x), (l)
614 #define SILC_STR_UI32_NSTRING_ALLOC(x, l) \
615 SILC_PARAM_UI32_NSTRING_ALLOC, (x), (l)
617 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_DATA
621 * #define SILC_STR_DATA() ...
622 * #define SILC_STR_DATA_ALLOC() ...
626 * Binary data formatting. Second argument is the length of the data.
628 * Formatting: SILC_STR_DATA(unsigned char *, SilcUInt32)
629 * Unformatting: SILC_STR_DATA(unsigned char **, SilcUInt32)
631 * This type can be used to take arbitrary size data block from the buffer
632 * by sending the requested amount of bytes as argument.
634 * _ALLOC routines automatically allocates memory for the variable sent
635 * as argument in unformatting.
638 #define SILC_STR_DATA(x, l) SILC_PARAM_DATA, (x), (l)
639 #define SILC_STR_DATA_ALLOC(x, l) SILC_PARAM_DATA_ALLOC, (x), (l)
642 #define SILC_STR_UI_XNSTRING(x, l) SILC_PARAM_UI_XNSTRING, (x), (l)
643 #define SILC_STR_UI_XNSTRING_ALLOC(x, l) SILC_PARAM_UI_XNSTRING_ALLOC, (x), (l)
645 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_BUFFER
649 * #define SILC_STR_BUFFER() ...
650 * #define SILC_STR_BUFFER_ALLOC() ...
654 * SilcBuffer formatting.
656 * Formatting: SILC_STR_BUFFER(SilcBuffer)
657 * Unformatting: SILC_STR_BUFFER(SilcBuffer)
659 * This type can be used to format and unformat SilcBuffer. Note that, the
660 * length of the buffer will be automatically encoded into the buffer as
661 * a 32-bit integer. In unformatting the SilcBuffer context must be
664 * _ALLOC routines automatically allocates memory inside SilcBuffer in
668 #define SILC_STR_BUFFER(x) SILC_PARAM_BUFFER, (x)
669 #define SILC_STR_BUFFER_ALLOC(x) SILC_PARAM_BUFFER_ALLOC, (x)
671 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_FUNC
675 * #define SILC_STR_FUNC() ...
679 * SilcBuffer formatting.
681 * Formatting: SILC_STR_FUNC(function, void *value, void *context)
682 * Unformatting: SILC_STR_FUNC(function, void **value, void *context)
684 * This type can be used to call the `function' of the type
685 * SilcBufferFormatFunc or SilcBufferUnformatFunc to encode or decode
686 * the `value'. In encoding the `value' will be passed to the `function'
687 * and can be encoded into the buffer. The buffer will be passed as
688 * well to the `function' at the location where SILC_STR_FUNC is placed
689 * in formatting. The `context' delivers caller specific context to
692 * In unformatting the `function' will decode the encoded type and
693 * return it to `value' pointer. The decoding function should decide
694 * itself whether to allocate or not the decoded value.
696 * The `function' does not have to encode anything and passing `value'
697 * as NULL is allowed. The `function' could for example modify the
702 * // Encode payload, encrypt and compute MAC.
703 * silc_buffer_format(buf,
704 * SILC_STR_FUNC(foo_encode_id, id, ctx),
705 * SILC_STR_UI_SHORT(len),
706 * SILC_STR_DATA(data, len),
707 * SILC_STR_FUNC(foo_buf_encrypt, NULL, key),
708 * SILC_STR_FUNC(foo_buf_hmac, NULL, hmac),
709 * SILC_STR_DATA(iv, iv_len);
712 * // Check MAC, decrypt and decode payload
713 * silc_buffer_unformat(buf,
714 * SILC_STR_FUNC(foo_buf_hmac, NULL, hmac),
715 * SILC_STR_FUNC(foo_buf_decrypt, NULL, key),
716 * SILC_STR_FUNC(foo_decode_id, &id, ctx),
717 * SILC_STR_UI_SHORT(&len),
721 #define SILC_STR_FUNC(func, val, context) SILC_PARAM_FUNC, \
722 func, (val), (context)
724 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_OFFSET
728 * #define SILC_STR_OFFSET() ...
732 * Offset in buffer. This can be used in formatting and unformatting to
733 * move the data pointer of the buffer either forwards (positive offset)
734 * or backwards (negative offset). It can be used to for example skip
735 * some types during unformatting.
739 * ..., SILC_STR_OFFSET(5), ...
740 * ..., SILC_STR_OFFSET(-3), ...
742 * Moves the data pointer at the point of the offset either forward
743 * or backward and then moves to the next type. Multiple SILC_STR_OFFSETs
744 * can be used in formatting and unformatting at the same time.
747 #define SILC_STR_OFFSET(x) SILC_PARAM_OFFSET, (x)
749 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_ADVANCE
753 * #define SILC_STR_ADVANCE ...
757 * Advance the buffer to the end of the data after the formatting is
758 * done. In normal operation when the formatted data is written the
759 * buffer is located at the start of the data. With SILC_STR_ADVANCE
760 * the buffer will be located at the end of the data. This makes it
761 * easy to add new data immediately after the previously added data.
762 * The SILC_STR_ADVANCE may also be used in unformatting.
767 * len = read(fd, buf, sizeof(buf));
769 * // Add read data to the buffer
770 * silc_buffer_format(buffer,
772 * SILC_STR_DATA(buf, len),
776 * // Move to beginning of buffer
777 * silc_buffer_start(buffer);
780 #define SILC_STR_ADVANCE SILC_PARAM_ADVANCE
782 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_END
786 * #define SILC_STR_END ...
790 * Marks end of the argument list. This must be at the end of the
791 * argument list or error will occur.
794 #define SILC_STR_END SILC_PARAM_END
796 /****d* silcutil/SilcBufferFormatAPI/SILC_STRFMT_END
800 * #define SILC_STRFMT_END ...
804 * Marks end of the argument list in silc_buffer_strformat function.
805 * This must be at the end of the argument list or error will occur.
808 #define SILC_STRFMT_END (void *)SILC_STR_END
810 #endif /* !SILCBUFFMT_H */