+/****f* silcutil/SilcBufferFormatAPI/silc_buffer_sunformat
+ *
+ * SYNOPSIS
+ *
+ * int silc_buffer_sunformat(SilcStack stack, SilcBuffer src, ...);
+ *
+ * DESCRIPTION
+ *
+ * Same as silc_buffer_unformat but uses `stack' to allocate the memory.
+ * if `stack' is NULL reverts back to silc_buffer_format call.
+ *
+ ***/
+int silc_buffer_sunformat(SilcStack stack, SilcBuffer src, ...);
+
+/****f* silcutil/SilcBufferFormatAPI/silc_buffer_unformat_vp
+ *
+ * SYNOPSIS
+ *
+ * int silc_buffer_unformat_vp(SilcBuffer src, va_list vp);
+ *
+ * DESCRIPTION
+ *
+ * Unformats a buffer from a variable argument list indicated by the `ap'.
+ * Returns -1 on error and the length of the unformatted buffer otherwise.
+ *
+ ***/
+int silc_buffer_unformat_vp(SilcBuffer src, va_list ap);
+
+/****f* silcutil/SilcBufferFormatAPI/silc_buffer_sunformat_vp
+ *
+ * SYNOPSIS
+ *
+ * int silc_buffer_sunformat_vp(SilcBuffer src, va_list vp);
+ *
+ * DESCRIPTION
+ *
+ * Same as silc_buffer_unformat_vp but uses `stack' to allocate the
+ * memory. if `stack' is NULL reverts back to silc_buffer_format_vp call.
+ *
+ ***/
+int silc_buffer_sunformat_vp(SilcStack stack, SilcBuffer src, va_list ap);
+
+/****f* silcutil/SilcBufferFormatAPI/silc_buffer_strformat
+ *
+ * SYNOPSIS
+ *
+ * int silc_buffer_strformat(SilcBuffer dst, ...);
+ *
+ * DESCRIPTION
+ *
+ * Formats a buffer from variable argument list of strings. Each
+ * string must be NULL-terminated and the variable argument list must
+ * be end with SILC_STRFMT_END argument. This allows that a string in
+ * the list can be NULL, in which case it is skipped. This automatically
+ * allocates the space for the buffer data but `dst' must be already
+ * allocated by the caller.
+ *
+ * EXAMPLE
+ *
+ * ret = silc_buffer_strformat(buffer, "foo", "bar", SILC_STRFMT_END);
+ * if (ret < 0)
+ * error;
+ *
+ ***/
+int silc_buffer_strformat(SilcBuffer dst, ...);
+
+/****f* silcutil/SilcBufferFormatAPI/silc_buffer_sstrformat
+ *
+ * SYNOPSIS
+ *
+ * int silc_buffer_strformat(SilcStack stack, SilcBuffer dst, ...);
+ *
+ * DESCRIPTION
+ *
+ * Formats a buffer from variable argument list of strings. Each
+ * string must be NULL-terminated and the variable argument list must
+ * be end with SILC_STRFMT_END argument. This allows that a string in
+ * the list can be NULL, in which case it is skipped. This automatically
+ * allocates the space for the buffer data but `dst' must be already
+ * allocated by the caller. This function is equivalent to
+ * silc_buffer_strformat but allocates memory from `stack'.
+ *
+ ***/
+int silc_buffer_sstrformat(SilcStack stack, SilcBuffer dst, ...);
+
+/****d* silcutil/SilcBufferFormatAPI/SilcBufferParamType
+ *
+ * NAME
+ *
+ * typedef enum { ... } SilcBufferParamType;
+ *
+ * DESCRIPTION
+ *
+ * Buffer parameter types. These are not needed when formatting or
+ * unformatting buffers. Use the macros such as SILC_STR_UI_CHAR and
+ * others instead. These types may be used when describing what a
+ * buffer looks like, and how it may be formatted and unformatted.
+ *
+ * SOURCE
+ */
+typedef enum {
+ SILC_PARAM_SI8_CHAR, /* Signed 8-bit char */
+ SILC_PARAM_UI8_CHAR, /* Unsigned 8-bit char */
+ SILC_PARAM_SI16_SHORT, /* Signed 16-bit int */
+ SILC_PARAM_UI16_SHORT, /* Unsigned 16-bit int */
+ SILC_PARAM_SI32_INT, /* Signed 32-bit int */
+ SILC_PARAM_UI32_INT, /* Unsigned 32-bit int */
+ SILC_PARAM_SI64_INT, /* Signed 64-bit int */
+ SILC_PARAM_UI64_INT, /* Unsigned 64-bit int */
+ SILC_PARAM_UI8_STRING, /* String (max len 8-bits)*/
+ SILC_PARAM_UI16_STRING, /* String (max len 16-bits) */
+ SILC_PARAM_UI32_STRING, /* String (max len 32-bits) */
+ SILC_PARAM_BUFFER, /* SilcBuffer */
+
+ /* Internal types */
+ SILC_PARAM_DATA, /* Binary data */
+ SILC_PARAM_UI8_NSTRING, /* String (max len 8-bits) */
+ SILC_PARAM_UI16_NSTRING, /* String (max len 16-bits) */
+ SILC_PARAM_UI32_NSTRING, /* String (max len 32-bits) */
+ SILC_PARAM_UI8_STRING_ALLOC, /* Alloc + memcpy */
+ SILC_PARAM_UI16_STRING_ALLOC, /* Alloc + memcpy */
+ SILC_PARAM_UI32_STRING_ALLOC, /* Alloc + memcpy */
+ SILC_PARAM_UI8_NSTRING_ALLOC, /* Alloc + memcpy */
+ SILC_PARAM_UI16_NSTRING_ALLOC, /* Alloc + memcpy */
+ SILC_PARAM_UI32_NSTRING_ALLOC, /* Alloc + memcpy */
+ SILC_PARAM_DATA_ALLOC, /* Alloc + memcpy */
+ SILC_PARAM_BUFFER_ALLOC, /* Alloc + memcpy */
+
+ SILC_PARAM_OFFSET,
+ SILC_PARAM_ADVANCE,
+ SILC_PARAM_FUNC,
+
+ SILC_PARAM_UI_XNSTRING,
+ SILC_PARAM_UI_XNSTRING_ALLOC,
+
+ SILC_PARAM_END
+} SilcBufferParamType;
+/***/
+
+/****d* silcutil/SilcBufferFormatAPI/SILC_STR_*_CHAR
+ *
+ * NAME
+ *
+ * #define SILC_STR_UI_CHAR() ...
+ * #define SILC_STR_SI_CHAR() ...
+ *
+ * DESCRIPTION
+ *
+ * One signed/unsigned character.
+ *
+ * Formatting: SILC_STR_SI_CHAR(char)
+ * SILC_STR_UI_CHAR(unsigned char)
+ * Unformatting: SILC_STR_SI_CHAR(char *)
+ * SILC_STR_UI_CHAR(unsigned char *)
+ *
+ ***/
+#define SILC_STR_SI_CHAR(x) SILC_PARAM_SI8_CHAR, (x)
+#define SILC_STR_UI_CHAR(x) SILC_PARAM_UI8_CHAR, (x)
+
+/****d* silcutil/SilcBufferFormatAPI/SILC_STR_*_SHORT
+ *
+ * NAME
+ *
+ * #define SILC_STR_UI_SHORT() ...
+ * #define SILC_STR_SI_SHORT() ...
+ *
+ * DESCRIPTION
+ *
+ * SilcInt16/SilcUInt16.
+ *
+ * Formatting: SILC_STR_SI_SHORT(SilcInt16)
+ * SILC_STR_UI_SHORT(SilcUInt16)
+ * Unformatting: SILC_STR_SI_SHORT(SilcInt16 *)
+ * SILC_STR_UI_SHORT(SilcUInt16 *)
+ *
+ ***/
+#define SILC_STR_SI_SHORT(x) SILC_PARAM_SI16_SHORT, (x)
+#define SILC_STR_UI_SHORT(x) SILC_PARAM_UI16_SHORT, (x)
+
+/****d* silcutil/SilcBufferFormatAPI/SILC_STR_*_INT
+ *
+ * NAME
+ *
+ * #define SILC_STR_UI_INT() ...
+ * #define SILC_STR_SI_INT() ...
+ *
+ * DESCRIPTION
+ *
+ * SilcInt32/SilcUInt32.
+ *
+ * Formatting: SILC_STR_SI_INT(SilcInt32)
+ * SILC_STR_UI_INT(SilcUInt32)
+ * Unformatting: SILC_STR_SI_INT(SilcInt32 *)
+ * SILC_STR_UI_INT(SilcUInt32 *)
+ *
+ ***/
+#define SILC_STR_SI_INT(x) SILC_PARAM_SI32_INT, (x)
+#define SILC_STR_UI_INT(x) SILC_PARAM_UI32_INT, (x)
+
+/****d* silcutil/SilcBufferFormatAPI/SILC_STR_*_INT64
+ *
+ * NAME
+ *
+ * #define SILC_STR_UI_INT64() ...
+ * #define SILC_STR_SI_INT64() ...
+ *
+ * DESCRIPTION
+ *
+ * SilcInt64/SilcUInt64.
+ *
+ * Formatting: SILC_STR_SI_INT64(SilcInt64)
+ * SILC_STR_UI_INT64(SilcUInt64)
+ * Unformatting: SILC_STR_SI_INT64(SilcInt64 *)
+ * SILC_STR_UI_INT64(SilcUInt64 *)
+ *
+ ***/
+#define SILC_STR_SI_INT64(x) SILC_PARAM_SI64_INT, (x)
+#define SILC_STR_UI_INT64(x) SILC_PARAM_UI64_INT, (x)
+
+/****d* silcutil/SilcBufferFormatAPI/SILC_STR_*_STRING
+ *
+ * NAME
+ *
+ * #define SILC_STR_UI8_STRING() ...
+ * #define SILC_STR_UI8_STRING_ALLOC() ...
+ * #define SILC_STR_UI16_STRING() ...
+ * #define SILC_STR_UI16_STRING_ALLOC() ...
+ * #define SILC_STR_UI32_STRING() ...
+ * #define SILC_STR_UI32_STRING_ALLOC() ...
+ *
+ * DESCRIPTION
+ *
+ * Unsigned NULL terminated string. Note that the string must be
+ * NULL terminated because strlen() will be used to get the length of
+ * the string.
+ *
+ * Formatting: SILC_STR_UI32_STRING(unsigned char *)
+ * Unformatting: SILC_STR_UI32_STRING(unsigned char **)
+ *
+ * Unformatting procedure will check for length of the string from the
+ * buffer before trying to get the string out. Thus, one *must* format the
+ * length as UI_INT or UI_SHORT into the buffer *before* formatting the
+ * actual string to the buffer, and, in unformatting one must ignore the
+ * length of the string because unformatting procedure will take it
+ * automatically.
+ *
+ * Example:
+ *
+ * Formatting: ..., SILC_STR_UI_INT(strlen(string)),
+ * SILC_STR_UI32_STRING(string), ...
+ * Unformatting: ..., SILC_STR_UI32_STRING(&string), ...
+ *
+ * I.e., you can ignore the formatted length field in unformatting.
+ *
+ * UI8, UI16 and UI32 means that the length is considered to be
+ * either char (8 bits), short (16 bits) or int (32 bits) in
+ * unformatting.
+ *
+ * _ALLOC routines automatically allocates memory for the variable sent
+ * as argument in unformatting.
+ *
+ ***/
+#define SILC_STR_UI8_STRING(x) SILC_PARAM_UI8_STRING, (x)
+#define SILC_STR_UI8_STRING_ALLOC(x) SILC_PARAM_UI8_STRING_ALLOC, (x)
+#define SILC_STR_UI16_STRING(x) SILC_PARAM_UI16_STRING, (x)
+#define SILC_STR_UI16_STRING_ALLOC(x) SILC_PARAM_UI16_STRING_ALLOC, (x)
+#define SILC_STR_UI32_STRING(x) SILC_PARAM_UI32_STRING, (x)
+#define SILC_STR_UI32_STRING_ALLOC(x) SILC_PARAM_UI32_STRING_ALLOC, (x)
+
+/****d* silcutil/SilcBufferFormatAPI/SILC_STR_*_NSTRING
+ *
+ * NAME
+ *
+ * #define SILC_STR_UI8_NSTRING() ...
+ * #define SILC_STR_UI8_NSTRING_ALLOC() ...
+ * #define SILC_STR_UI16_NSTRING() ...
+ * #define SILC_STR_UI16_NSTRING_ALLOC() ...
+ * #define SILC_STR_UI32_NSTRING() ...
+ * #define SILC_STR_UI32_NSTRING_ALLOC() ...
+ *
+ * DESCRIPTION
+ *
+ * Unsigned string. Second argument is the length of the string.
+ *
+ * Formatting: SILC_STR_UI32_NSTRING(unsigned char *, SilcUInt32)
+ * Unformatting: SILC_STR_UI32_NSTRING(unsigned char **, SilcUInt32 *)
+ *
+ * Unformatting procedure will check for length of the string from the
+ * buffer before trying to get the string out. Thus, one *must* format the
+ * length as UI_INT or UI_SHORT into the buffer *before* formatting the
+ * actual string to the buffer, and, in unformatting one must ignore the
+ * length of the string because unformatting procedure will take it
+ * automatically.
+ *
+ * Example:
+ *
+ * Formatting: ..., SILC_STR_UI_INT(strlen(string)),
+ * SILC_STR_UI32_NSTRING(string, strlen(string)), ...
+ * Unformatting: ..., SILC_STR_UI32_NSTRING(&string, &len), ...
+ *
+ * I.e., you can ignore the formatted length field in unformatting. The
+ * length taken from the buffer is returned to the pointer sent as
+ * argument (&len in above example).
+ *
+ * UI8, UI16 and UI32 means that the length is considered to be
+ * either char (8 bits), short (16 bits) or int (32 bits) in
+ * unformatting.
+ *
+ * _ALLOC routines automatically allocates memory for the variable sent
+ * as argument in unformatting.
+ *
+ ***/
+#define SILC_STR_UI8_NSTRING(x, l) SILC_PARAM_UI8_NSTRING, (x), (l)
+#define SILC_STR_UI8_NSTRING_ALLOC(x, l) \
+ SILC_PARAM_UI8_NSTRING_ALLOC, (x), (l)
+#define SILC_STR_UI16_NSTRING(x, l) SILC_PARAM_UI16_NSTRING, (x), (l)