+#define SILC_STR_DATA(x, l) SILC_PARAM_UICHAR, (x), (l)
+#define SILC_STR_DATA_ALLOC(x, l) SILC_PARAM_UICHAR | SILC_PARAM_ALLOC, (x), (l)
+
+/* Deprecated */
+#define SILC_STR_UI_XNSTRING(x, l) SILC_PARAM_UICHAR, (x), (l)
+#define SILC_STR_UI_XNSTRING_ALLOC(x, l) SILC_PARAM_UICHAR | SILC_PARAM_ALLOC, (x), (l)
+
+/****d* silcutil/SilcBufferFormatAPI/SILC_STR_BUFFER
+ *
+ * NAME
+ *
+ * #define SILC_STR_BUFFER() ...
+ * #define SILC_STR_BUFFER_ALLOC() ...
+ *
+ * DESCRIPTION
+ *
+ * SilcBuffer formatting.
+ *
+ * Formatting: SILC_STR_BUFFER(SilcBuffer)
+ * Unformatting: SILC_STR_BUFFER(SilcBuffer)
+ *
+ * This type can be used to format and unformat SilcBuffer. Note that, the
+ * length of the buffer will be automatically encoded into the buffer as
+ * a 32-bit integer. In unformatting the SilcBuffer context must be
+ * pre-allocated.
+ *
+ * _ALLOC routines automatically allocates memory inside SilcBuffer in
+ * unformatting.
+ *
+ ***/
+#define SILC_STR_BUFFER(x) SILC_PARAM_BUFFER, (x)
+#define SILC_STR_BUFFER_ALLOC(x) SILC_PARAM_BUFFER | SILC_PARAM_ALLOC, (x)
+
+/****d* silcutil/SilcBufferFormatAPI/SILC_STR_FUNC
+ *
+ * NAME
+ *
+ * #define SILC_STR_FUNC() ...
+ *
+ * DESCRIPTION
+ *
+ * Formatting and unformatting of arbitrary data.
+ *
+ * Formatting: SILC_STR_FUNC(function, void *value, void *context)
+ * Unformatting: SILC_STR_FUNC(function, void **value, void *context)
+ *
+ * This type can be used to call the `function' of the type
+ * SilcBufferFormatFunc or SilcBufferUnformatFunc to encode or decode
+ * the `value'. In encoding the `value' will be passed to the `function'
+ * and can be encoded into the buffer. The buffer will be passed as
+ * well to the `function' at the location where SILC_STR_FUNC is placed
+ * in formatting. The `context' delivers caller specific context to
+ * the `function'
+ *
+ * In unformatting the `function' will decode the encoded type and
+ * return it to `value' pointer. The decoding function should decide
+ * itself whether to allocate or not the decoded value.
+ *
+ * The `function' does not have to encode anything and passing `value'
+ * as NULL is allowed. The `function' could for example modify the
+ * existing buffer.
+ *
+ * EXAMPLE
+ *
+ * // Encode payload, encrypt and compute MAC.
+ * silc_buffer_format(buf,
+ * SILC_STR_FUNC(foo_encode_id, id, ctx),
+ * SILC_STR_UINT16(len),
+ * SILC_STR_DATA(data, len),
+ * SILC_STR_FUNC(foo_buf_encrypt, NULL, key),
+ * SILC_STR_FUNC(foo_buf_hmac, NULL, hmac),
+ * SILC_STR_DATA(iv, iv_len);
+ * SILC_STR_END);
+ *
+ * // Check MAC, decrypt and decode payload
+ * silc_buffer_unformat(buf,
+ * SILC_STR_FUNC(foo_buf_hmac, NULL, hmac),
+ * SILC_STR_FUNC(foo_buf_decrypt, NULL, key),
+ * SILC_STR_FUNC(foo_decode_id, &id, ctx),
+ * SILC_STR_UINT16(&len),
+ * SILC_STR_END);
+ *
+ ***/
+#define SILC_STR_FUNC(func, val, context) SILC_PARAM_FUNC, \
+ func, (val), (context)
+
+/****d* silcutil/SilcBufferFormatAPI/SilcBufferRegexFlags
+ *
+ * NAME
+ *
+ * typedef enum { ... } SilcBufferRegexFlags;
+ *
+ * DESCRIPTION
+ *
+ * Regular expression flags for SILC_STR_REGEX macro. The flags can be
+ * used to manipulate the behavior of the SILC_STR_REGEX. All flags
+ * may be combined unless otherwise stated.
+ *
+ * SOURCE
+ */
+typedef enum {
+ SILC_STR_REGEX_NONE = 0x00000000,
+
+ /* By default mismatch will be skipped. Set this flag if mismatch should
+ cause error and stopping of the formatting/unformatting. */
+ SILC_STR_REGEX_MISMATCH = 0x00000001,
+
+ /* By default only the first match is found. Set this flag to find
+ all matches. */
+ SILC_STR_REGEX_ALL = 0x00000002,
+
+ /* By default the buffer position is advanced to the position of the
+ first match. Set this flag if the buffer should not be advanced to
+ the match. */
+ SILC_STR_REGEX_NO_ADVANCE = 0x00000004,
+
+ /* By default SILC_STR_REGEX performs the match on the whole buffer. Set
+ this flag to make it behave like sed and match line by line. Each line
+ must end with '\n'. If buffer doesn't have '\n' it is considered to be
+ one line. Note that, any formatting done immediately after SILC_STR_REGEX
+ block with this flag will be formatted to the end of the buffer (after
+ last line). Use SILC_STR_OFFSET* macros to change the position if
+ needed. Also note that, any encoding macro inside the SILC_STR_REGEX
+ block will see only the matched line (including '\n'), instead of whole
+ buffer after the match. */
+ SILC_STR_REGEX_NL = 0x00000008,
+
+ /* Set this flag to not match the regular expression, but to match everything
+ else. When combined with SILC_STR_REGEX_NL this flag matches all other
+ lines except the ones with matching regular expression. */
+ SILC_STR_REGEX_NOT = 0x00000010,
+
+ /* By default the buffer is advanced to the first match and the rest of the
+ buffer remains as is. Set this flag to pass the exact match to the
+ SILC_STR_* macros in the SILC_STR_REGEX block; macros see the start of
+ the match and the end of the match, but not rest of the buffer (ie. with
+ match 'foo' the size of the buffer is 3 bytes). */
+ SILC_STR_REGEX_INCLUSIVE = 0x00000020,
+} SilcBufferRegexFlags;
+/***/
+
+/****d* silcutil/SilcBufferFormatAPI/SILC_STR_REGEX
+ *
+ * NAME
+ *
+ * #define SILC_STR_REGEX() ...
+ *
+ * DESCRIPTION
+ *
+ * Regular expression matching within the buffer.
+ *
+ * Formatting: SILC_STR_REGEX(char *regex, SilcBufferRegexFlags flags)
+ * Unformatting: SILC_STR_REGEX(char *regex, SilcBufferRegexFlags flags)
+ *
+ * SILC_STR_REGEX can be used to do regular expression matching within
+ * the SilcBuffer. When the string in the buffer matches the regular
+ * expression the position of the buffer is advanced to the position of
+ * the first match (rest of the buffer remains intact). If the regular
+ * expression does not match it is skipped, unless the flags specify
+ * otherwise. If flags are not needed they can be set to 0.
+ *
+ * In addition of matching regular expressions it can be used in a
+ * Stream Editor (sed) and Awk like fashion. The regular expression can be
+ * matched and then edited by any of the SILC_STR_* macros. The flags
+ * can be used to perform complex operations on the data. Some sed
+ * features that cannot be directly done with the flags can be done with
+ * SILC_STR_FUNC and other macros (the SILC_STR_FUNC could do anything
+ * after the match).
+ *
+ * The SILC_STR_REGEX itself is used as an opening of a block of encoding
+ * macros and must be closed with SILC_STR_END. This means that for
+ * each SILC_STR_REGEX there must be one SILC_STR_END. See examples for
+ * more information.
+ *
+ * The SILC_STR_REGEX can be used in buffer unformatting also to do
+ * string matching and parsing, but not editing, except with SILC_STR_FUNC
+ * macro, which can do anything caller wants.
+ *
+ * EXAMPLE
+ *
+ * // sed 's/foo/bar/', replace first foo with bar
+ * silc_buffer_format(buffer,
+ * SILC_STR_REGEX("foo", 0),
+ * SILC_STR_STRING("bar"),
+ * SILC_STR_END, SILC_STR_END);
+ *
+ * // sed 's/foo/barbar/g', replace all foo's with barbar, without
+ * // overwriting any data in the buffer, but appending it. The match
+ * // must be SILC_STR_REGEX_INCLUSIVE to make appending work.
+ * silc_buffer_format(buffer,
+ * SILC_STR_REGEX("foo", SILC_STR_REGEX_ALL |
+ * SILC_STR_REGEX_INCLUSIVE),
+ * SILC_STR_STRING_APPEND("barbar"),
+ * SILC_STR_END, SILC_STR_END);
+ *
+ * // sed '/baz/s/foo/bar/g, replace all foo's with bar on lines with baz
+ * silc_buffer_format(buffer,
+ * SILC_STR_REGEX("baz", SILC_STR_REGEX_NL),
+ * SILC_STR_REGEX("foo", SILC_STR_REGEX_ALL),
+ * SILC_STR_STRING("bar"),
+ * SILC_STR_END,
+ * SILC_STR_END, SILC_STR_END);
+ *
+ * // Print all lines that start with 'R'
+ * int print(SilcStack stack, SilcBuffer buf, void *value, void *context)
+ * {
+ * return fwrite(silc_buffer_data(buf), 1, silc_buffer_len(buf), stdout);
+ * }
+ *
+ * silc_buffer_unformat(buffer,
+ * SILC_STR_REGEX("^R", SILC_STR_REGEX_NL),
+ * SILC_STR_FUNC(print, NULL, NULL),
+ * SILC_STR_END, SILC_STR_END);
+ *
+ ***/
+#define SILC_STR_REGEX(regex, flags) SILC_PARAM_REGEX, (regex), (flags)
+
+/****d* silcutil/SilcBufferFormatAPI/SILC_STR_OFFSET
+ *
+ * NAME
+ *
+ * #define SILC_STR_OFFSET() ...
+ *
+ * DESCRIPTION
+ *
+ * Offset in buffer. This can be used in formatting and unformatting to
+ * move the data pointer of the buffer either forwards (positive offset)
+ * or backwards (negative offset). It can be used to for example skip
+ * some types during unformatting.
+ *
+ * Example:
+ *
+ * ..., SILC_STR_OFFSET(5), ...
+ * ..., SILC_STR_OFFSET(-3), ...
+ *
+ * Moves the data pointer at the point of the offset either forward
+ * or backward and then moves to the next type. Multiple SILC_STR_OFFSETs
+ * can be used in formatting and unformatting at the same time.
+ *
+ ***/
+#define SILC_STR_OFFSET(x) SILC_PARAM_OFFSET, (x)
+
+/****d* silcutil/SilcBufferFormatAPI/SILC_STR_OFFSET_START
+ *
+ * NAME
+ *
+ * #define SILC_STR_OFFSET_START ...
+ *
+ * DESCRIPTION
+ *
+ * Moves the buffer position to the start of the data area.
+ *
+ * Example:
+ *
+ * ..., SILC_STR_OFFSET_START, ...
+ *
+ ***/
+#define SILC_STR_OFFSET_START SILC_PARAM_OFFSET_START
+
+/****d* silcutil/SilcBufferFormatAPI/SILC_STR_OFFSET_END
+ *
+ * NAME
+ *
+ * #define SILC_STR_OFFSET_END ...
+ *
+ * DESCRIPTION
+ *
+ * Moves the buffer position to the end of the data area.
+ *
+ * Example:
+ *
+ * ..., SILC_STR_OFFSET_END, ...
+ *
+ ***/
+#define SILC_STR_OFFSET_END SILC_PARAM_OFFSET_END
+
+/****d* silcutil/SilcBufferFormatAPI/SILC_STR_ADVANCE
+ *
+ * NAME
+ *
+ * #define SILC_STR_ADVANCE ...
+ *
+ * DESCRIPTION
+ *
+ * Advance the buffer to the end of the data after the formatting is
+ * done. In normal operation when the formatted data is written the
+ * buffer is positioned at the start of the data. With SILC_STR_ADVANCE
+ * the buffer will be positioned at the end of the data. This makes it
+ * easy to add new data immediately after the previously added data.
+ * The SILC_STR_ADVANCE may also be used in unformatting.
+ *
+ * EXAMPLE
+ *
+ * do {
+ * len = read(fd, buf, sizeof(buf));
+ * if (len > 0)
+ * // Add read data to the buffer
+ * silc_buffer_format(buffer,
+ * SILC_STR_ADVANCE,
+ * SILC_STR_DATA(buf, len),
+ * SILC_STR_END);
+ * } while (len > 0);
+ *
+ * // Move to beginning of buffer
+ * silc_buffer_start(buffer);
+ *
+ ***/
+#define SILC_STR_ADVANCE SILC_PARAM_ADVANCE