5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 1997 - 2008 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 encode packets,
27 * protocol payloads and such.
29 * It also provides many advanced features like calling user specified
30 * encoder and decoder functions that are free to do anything to the buffer.
31 * The API also provides powerful regular expression matching capabilities
32 * within the buffer, enabling caller to not only match regular expressions
33 * but to make the API behave like Stream Editor (Sed) and Awk. The buffer
34 * can be matched against regular expression and then edited. Caller can
35 * do anything they want to the buffer after a match. The SILC_STR_REGEX
36 * macro provides many different flags that can change the behavior of the
37 * matching, with capabilities to also mimic Sed behavior.
39 * As the SilcBuffer API is not thread-safe these routines may not be used
40 * in multithreaded environment with a same SilcBuffer context without
41 * concurrency control.
45 * SilcBufferStruct buffer;
47 * memset(&buffer, 0, sizeof(buffer));
48 * ret = silc_buffer_format(&buffer,
49 * SILC_STR_UINT32(intval),
50 * SILC_STR_UINT8(charval),
51 * SILC_STR_UINT64(longintval),
52 * SILC_STR_UINT16(str_len),
53 * SILC_STR_DATA(str, str_len),
58 * // sed 's/foo/bar/', replace first foo with bar
59 * silc_buffer_format(buffer,
60 * SILC_STR_REGEX("foo", 0),
61 * SILC_STR_STRING("bar"),
62 * SILC_STR_END, SILC_STR_END);
69 /****f* silcutil/SilcBufferFormatAPI/SilcBufferFormatFunc
73 * typedef int (*SilcBuffeSFormatFunc)(SilcStack stack,
80 * Formatting function callback given with SILC_STR_FUNC type. The
81 * `buffer' is the buffer being formatted at the location where the
82 * SILC_STR_FUNC was placed in formatting. The function should call
83 * silc_buffer_senlarge before it adds the data to the buffer to make
84 * sure that it has enough space. The buffer->head points to the
85 * start of the buffer and silc_buffer_headlen() gives the length
86 * of the currently formatted data area. It is also possible to use
87 * silc_buffer_sformat with `buffer' which will enlarge the buffer if
90 * The `value' is the value given to SILC_STR_FUNC that is to be formatted
91 * into the buffer. It may be NULL if the function is not formatting
92 * new data into the buffer. The `context' is caller specific context.
93 * Returns -1 on error and length of the formatted value otherwise, and
94 * 0 if nothing was formatted.
97 typedef int (*SilcBufferFormatFunc)(SilcStack stack, SilcBuffer buffer,
98 void *value, void *context);
100 /****f* silcutil/SilcBufferFormatAPI/SilcBufferUnformatFunc
104 * typedef int (*SilcBufferUnformatFunc)(SilcBuffer buffer,
110 * Unformatting function callback given with SILC_STR_FUNC type. The
111 * `buffer' is the buffer being unformatted and is at the location where
112 * the SILC_STR_FUNC was placed in unformatting. The function should
113 * check there is enough data in the `buffer' before trying to decode
116 * If this function unformats anything from the buffer its value is to
117 * be returned to the `value' pointer. The implementation should itself
118 * decide whether the unformatted value is allocated or not. If this
119 * function does not unformat anything, nothing is returned to `value'
121 * The `context' is caller specific context. Returns -1 on error, and
122 * length of the unformatted value otherwise, and 0 if nothing was
126 typedef int (*SilcBufferUnformatFunc)(SilcStack stack, SilcBuffer buffer,
127 void **value, void *context);
131 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_format
135 * int silc_buffer_format(SilcBuffer dst, ...);
139 * Formats a buffer from a variable argument list. Returns -1 if the
140 * system is out of memory and the length of the formatted buffer otherwise.
141 * The buffer is enlarged automatically during formatting, if it doesn't
142 * already have enough space. Sets silc_errno in case of error.
146 * Three basic ways of using silc_buffer_format:
148 * // Statically allocated zero size buffer
149 * SilcBufferStruct buffer;
151 * memset(&buffer, 0, sizeof(buffer));
152 * ret = silc_buffer_format(&buffer,
153 * SILC_STR_UINT32(intval),
154 * SILC_STR_UINT8(charval),
155 * SILC_STR_UINT32(intval),
156 * SILC_STR_UINT16(str_len),
157 * SILC_STR_DATA(str, str_len),
162 * // Free the allocated data
163 * silc_buffer_purge(&buffer);
165 * // Dynamically allocated zero size buffer
167 * buf = silc_buffer_alloc(0);
168 * ret = silc_buffer_format(buf,
169 * SILC_STR_UINT32(intval),
170 * SILC_STR_UINT8(charval),
175 * // Free the allocated buffer
176 * silc_buffer_free(buf);
178 * // Dynamically allocated buffer with enough space
180 * buf = silc_buffer_alloc(2 + str_len);
181 * ret = silc_buffer_format(buf,
182 * SILC_STR_UINT16(str_len),
183 * SILC_STR_DATA(str, str_len),
189 int silc_buffer_format(SilcBuffer dst, ...);
191 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_sformat
195 * int silc_buffer_sformat(SilcStack stack, SilcBuffer dst, ...);
199 * Same as silc_buffer_format but uses `stack' to allocate the memory.
200 * if `stack' is NULL reverts back to silc_buffer_format call. Returns
201 * -1 if system is out of memory. Sets silc_errno in case of error.
203 * Note that this call consumes the `stack'. The caller should push the
204 * stack before calling the function and pop it later.
207 int silc_buffer_sformat(SilcStack stack, SilcBuffer dst, ...);
209 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_format_vp
213 * int silc_buffer_format_vp(SilcBuffer dst, va_list vp);
217 * Formats a buffer from a variable argument list indicated by the `ap'.
218 * Returns -1 if system is out of memory and the length of the formatted
222 int silc_buffer_format_vp(SilcBuffer dst, va_list ap);
224 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_sformat_vp
228 * int silc_buffer_sformat_vp(SilcStack stack, SilcBuffer dst, va_list vp);
232 * Same as silc_buffer_format_vp but uses `stack' to allocate the memory.
233 * if `stack' is NULL reverts back to silc_buffer_format_vp call. Returns
234 * -1 if system is out of memory. Sets silc_errno in case of error.
236 * Note that this call consumes the `stack'. The caller should push the
237 * stack before calling the function and pop it later.
240 int silc_buffer_sformat_vp(SilcStack stack, SilcBuffer dst, va_list ap);
242 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_unformat
246 * int silc_buffer_unformat(SilcBuffer src, ...);
250 * Unformats a buffer from a variable argument list. Returns -1 on error
251 * and the length of the unformatted buffer otherwise. Sets silc_errno
256 * ret = silc_buffer_unformat(buffer,
257 * SILC_STR_UINT32(&intval),
258 * SILC_STR_UINT8(&charval),
259 * SILC_STR_OFFSET(4),
260 * SILC_STR_UI16_NSTRING_ALLOC(&str, &str_len),
266 int silc_buffer_unformat(SilcBuffer src, ...);
268 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_sunformat
272 * int silc_buffer_sunformat(SilcStack stack, SilcBuffer src, ...);
276 * Same as silc_buffer_unformat but uses `stack' to allocate the memory.
277 * if `stack' is NULL reverts back to silc_buffer_format call.
279 * Note that this call consumes the `stack'. The caller should push the
280 * stack before calling the function and pop it later.
283 int silc_buffer_sunformat(SilcStack stack, SilcBuffer src, ...);
285 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_unformat_vp
289 * int silc_buffer_unformat_vp(SilcBuffer src, va_list vp);
293 * Unformats a buffer from a variable argument list indicated by the `ap'.
294 * Returns -1 on error and the length of the unformatted buffer otherwise.
297 int silc_buffer_unformat_vp(SilcBuffer src, va_list ap);
299 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_sunformat_vp
303 * int silc_buffer_sunformat_vp(SilcBuffer src, va_list vp);
307 * Same as silc_buffer_unformat_vp but uses `stack' to allocate the
308 * memory. if `stack' is NULL reverts back to silc_buffer_format_vp call.
310 * Note that this call consumes the `stack'. The caller should push the
311 * stack before calling the function and pop it later.
314 int silc_buffer_sunformat_vp(SilcStack stack, SilcBuffer src, va_list ap);
316 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_strformat
320 * int silc_buffer_strformat(SilcBuffer dst, ...);
324 * Formats a buffer from variable argument list of strings. Each
325 * string must be NULL-terminated and the variable argument list must
326 * be end with SILC_STRFMT_END argument. This allows that a string in
327 * the list can be NULL, in which case it is skipped. This automatically
328 * allocates the space for the buffer data but `dst' must be already
329 * allocated by the caller. Returns -1 if system is out of memory and
334 * ret = silc_buffer_strformat(buffer, "foo", "bar", SILC_STRFMT_END);
339 int silc_buffer_strformat(SilcBuffer dst, ...);
341 /****f* silcutil/SilcBufferFormatAPI/silc_buffer_sstrformat
345 * int silc_buffer_strformat(SilcStack stack, SilcBuffer dst, ...);
349 * Formats a buffer from variable argument list of strings. Each
350 * string must be NULL-terminated and the variable argument list must
351 * be end with SILC_STRFMT_END argument. This allows that a string in
352 * the list can be NULL, in which case it is skipped. This automatically
353 * allocates the space for the buffer data but `dst' must be already
354 * allocated by the caller. This function is equivalent to
355 * silc_buffer_strformat but allocates memory from `stack'. Returns -1
356 * if system is out of memory and sets silc_errno.
358 * Note that this call consumes the `stack'. The caller should push the
359 * stack before calling the function and pop it later.
362 int silc_buffer_sstrformat(SilcStack stack, SilcBuffer dst, ...);
364 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_SINT8
368 * #define SILC_STR_SINT8() ...
372 * One 8-bit signed integer.
374 * Formatting: SILC_STR_SINT8(SilcInt8)
375 * Unformatting: SILC_STR_SINT8(SilcInt8 *)
378 #define SILC_STR_SINT8(x) SILC_PARAM_SINT8, (x)
380 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_UINT8
384 * #define SILC_STR_UINT8() ...
388 * One 8-bit unsigned integer.
390 * Formatting: SILC_STR_UINT8(SilcUInt8)
391 * Unformatting: SILC_STR_UINT8(SilcUInt8 *)
394 #define SILC_STR_UINT8(x) SILC_PARAM_UINT8, (x)
397 #define SILC_STR_SI_CHAR(x) SILC_PARAM_SINT8, (x)
398 #define SILC_STR_UI_CHAR(x) SILC_PARAM_UINT8, (x)
400 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_SINT16
404 * #define SILC_STR_SINT16() ...
410 * Formatting: SILC_STR_SINT16(SilcInt16)
411 * Unformatting: SILC_STR_SINT16(SilcInt16 *)
414 #define SILC_STR_SINT16(x) SILC_PARAM_SINT16, (x)
416 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_UINT16
420 * #define SILC_STR_UINT16() ...
426 * Formatting: SILC_STR_UINT16(SilcUInt16)
427 * Unformatting: SILC_STR_UINT16(SilcUInt16 *)
430 #define SILC_STR_UINT16(x) SILC_PARAM_UINT16, (x)
433 #define SILC_STR_SI_SHORT(x) SILC_PARAM_SINT16, (x)
434 #define SILC_STR_UI_SHORT(x) SILC_PARAM_UINT16, (x)
436 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_SINT32
440 * #define SILC_STR_SINT32() ...
446 * Formatting: SILC_STR_SINT32(SilcInt32)
447 * Unformatting: SILC_STR_SINT32(SilcInt32 *)
450 #define SILC_STR_SINT32(x) SILC_PARAM_SINT32, (x)
452 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_UINT32
456 * #define SILC_STR_UINT32() ...
462 * Formatting: SILC_STR_UINT32(SilcUInt32)
463 * Unformatting: SILC_STR_UINT32(SilcUInt32 *)
466 #define SILC_STR_UINT32(x) SILC_PARAM_UINT32, (x)
469 #define SILC_STR_SI_INT(x) SILC_PARAM_SINT32, (x)
470 #define SILC_STR_UI_INT(x) SILC_PARAM_UINT32, (x)
472 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_SINT64
476 * #define SILC_STR_SINT64() ...
482 * Formatting: SILC_STR_SINT64(SilcInt64)
483 * Unformatting: SILC_STR_SINT64(SilcInt64 *)
486 #define SILC_STR_SI_INT64(x) SILC_PARAM_SINT64, (x)
488 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_UINT64
492 * #define SILC_STR_UINT64() ...
498 * Formatting: SILC_STR_UINT64(SilcUInt64)
499 * Unformatting: SILC_STR_UINT64(SilcUInt64 *)
502 #define SILC_STR_UI_INT64(x) SILC_PARAM_UINT64, (x)
505 #define SILC_STR_SI_INT64(x) SILC_PARAM_SINT64, (x)
506 #define SILC_STR_UI_INT64(x) SILC_PARAM_UINT64, (x)
508 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_STRING
512 * #define SILC_STR_STRING() ...
516 * Encode NULL terminated string. Use this only for formatting.
518 * Formatting: SILC_STR_STRING(char *)
520 * For unformatting use one of the SILC_STR_*_STRING macros, which
521 * automatically gets the length of the string from the buffer. Note
522 * SILC_STR_STRING does not save the length of the string into the buffer.
523 * The caller must do that in order for the unformatting macros to work.
527 * Formatting: ..., SILC_STR_UINT32(strlen(string)),
528 * SILC_STR_STRING(string), ...
529 * Unformatting: ..., SILC_STR_UI32_STRING(&string), ...
532 #define SILC_STR_STRING(x) SILC_PARAM_UI8_STRING, (x)
534 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_*_STRING
538 * #define SILC_STR_UI8_STRING() ...
539 * #define SILC_STR_UI8_STRING_ALLOC() ...
540 * #define SILC_STR_UI16_STRING() ...
541 * #define SILC_STR_UI16_STRING_ALLOC() ...
542 * #define SILC_STR_UI32_STRING() ...
543 * #define SILC_STR_UI32_STRING_ALLOC() ...
547 * Unsigned NULL terminated string. Note that the string must be
548 * NULL terminated because strlen() will be used to get the length of
551 * Formatting: SILC_STR_UI32_STRING(unsigned char *)
552 * Unformatting: SILC_STR_UI32_STRING(unsigned char **)
554 * Unformatting procedure will check for length of the string from the
555 * buffer before trying to get the string out. Thus, one *must* format the
556 * length as UINT32 or UINT16 or UINT8 into the buffer *before* formatting
557 * the actual string to the buffer, and, in unformatting one ignores the
558 * length of the string because unformatting procedure will take it
563 * Formatting: ..., SILC_STR_UINT32(strlen(string)),
564 * SILC_STR_UI32_STRING(string), ...
565 * Unformatting: ..., SILC_STR_UI32_STRING(&string), ...
567 * I.e., you can ignore the formatted length field in unformatting.
569 * UI8, UI16 and UI32 means that the length is considered to be
570 * either UINT8, UINT16 or UINT32 in unformatting.
572 * _ALLOC routines automatically allocates memory for the variable sent
573 * as argument in unformatting.
576 #define SILC_STR_UI8_STRING(x) SILC_PARAM_UI8_STRING, (x)
577 #define SILC_STR_UI8_STRING_ALLOC(x) SILC_PARAM_UI8_STRING | SILC_PARAM_ALLOC, (x)
578 #define SILC_STR_UI16_STRING(x) SILC_PARAM_UI16_STRING, (x)
579 #define SILC_STR_UI16_STRING_ALLOC(x) SILC_PARAM_UI16_STRING | SILC_PARAM_ALLOC, (x)
580 #define SILC_STR_UI32_STRING(x) SILC_PARAM_UI32_STRING, (x)
581 #define SILC_STR_UI32_STRING_ALLOC(x) SILC_PARAM_UI32_STRING | SILC_PARAM_ALLOC, (x)
583 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_*_NSTRING
587 * #define SILC_STR_UI8_NSTRING() ...
588 * #define SILC_STR_UI8_NSTRING_ALLOC() ...
589 * #define SILC_STR_UI16_NSTRING() ...
590 * #define SILC_STR_UI16_NSTRING_ALLOC() ...
591 * #define SILC_STR_UI32_NSTRING() ...
592 * #define SILC_STR_UI32_NSTRING_ALLOC() ...
596 * Unsigned string. Second argument is the length of the string.
598 * Formatting: SILC_STR_UI32_NSTRING(unsigned char *, SilcUInt32)
599 * Unformatting: SILC_STR_UI32_NSTRING(unsigned char **, SilcUInt32 *)
601 * Unformatting procedure will check for length of the string from the
602 * buffer before trying to get the string out. Thus, one *must* format the
603 * length as UINT32 or UINT16 or UINT8 into the buffer *before* formatting
604 * the actual string to the buffer, and, in unformatting one ignores the
605 * length of the string because unformatting procedure will take it
610 * Formatting: ..., SILC_STR_UINT32(strlen(string)),
611 * SILC_STR_UI32_NSTRING(string, strlen(string)), ...
612 * Unformatting: ..., SILC_STR_UI32_NSTRING(&string, &len), ...
614 * I.e., you can ignore the formatted length field in unformatting. The
615 * length taken from the buffer is returned to the pointer sent as
616 * argument (&len in above example).
618 * UI8, UI16 and UI32 means that the length is considered to be
619 * either UINT8, UINT16 or UINT32 in unformatting.
621 * _ALLOC routines automatically allocates memory for the variable sent
622 * as argument in unformatting.
625 #define SILC_STR_UI8_NSTRING(x, l) SILC_PARAM_UI8_NSTRING, (x), (l)
626 #define SILC_STR_UI8_NSTRING_ALLOC(x, l) \
627 SILC_PARAM_UI8_NSTRING | SILC_PARAM_ALLOC, (x), (l)
628 #define SILC_STR_UI16_NSTRING(x, l) SILC_PARAM_UI16_NSTRING, (x), (l)
629 #define SILC_STR_UI16_NSTRING_ALLOC(x, l) \
630 SILC_PARAM_UI16_NSTRING | SILC_PARAM_ALLOC, (x), (l)
631 #define SILC_STR_UI32_NSTRING(x, l) SILC_PARAM_UI32_NSTRING, (x), (l)
632 #define SILC_STR_UI32_NSTRING_ALLOC(x, l) \
633 SILC_PARAM_UI32_NSTRING | SILC_PARAM_ALLOC, (x), (l)
635 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_DATA
639 * #define SILC_STR_DATA() ...
640 * #define SILC_STR_DATA_ALLOC() ...
644 * Binary data formatting. Second argument is the length of the data.
646 * Formatting: SILC_STR_DATA(unsigned char *, SilcUInt32)
647 * Unformatting: SILC_STR_DATA(unsigned char **, SilcUInt32)
649 * This type can be used to take arbitrary size data block from the buffer
650 * by sending the requested amount of bytes as argument.
652 * _ALLOC routines automatically allocates memory for the variable sent
653 * as argument in unformatting.
656 #define SILC_STR_DATA(x, l) SILC_PARAM_UICHAR, (x), (l)
657 #define SILC_STR_DATA_ALLOC(x, l) SILC_PARAM_UICHAR | SILC_PARAM_ALLOC, (x), (l)
660 #define SILC_STR_UI_XNSTRING(x, l) SILC_PARAM_UICHAR, (x), (l)
661 #define SILC_STR_UI_XNSTRING_ALLOC(x, l) SILC_PARAM_UICHAR | SILC_PARAM_ALLOC, (x), (l)
663 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_BUFFER
667 * #define SILC_STR_BUFFER() ...
668 * #define SILC_STR_BUFFER_ALLOC() ...
672 * SilcBuffer formatting.
674 * Formatting: SILC_STR_BUFFER(SilcBuffer)
675 * Unformatting: SILC_STR_BUFFER(SilcBuffer)
677 * This type can be used to format and unformat SilcBuffer. Note that, the
678 * length of the buffer will be automatically encoded into the buffer as
679 * a 32-bit integer. In unformatting the SilcBuffer context must be
682 * _ALLOC routines automatically allocates memory inside SilcBuffer in
686 #define SILC_STR_BUFFER(x) SILC_PARAM_BUFFER, (x)
687 #define SILC_STR_BUFFER_ALLOC(x) SILC_PARAM_BUFFER | SILC_PARAM_ALLOC, (x)
689 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_FUNC
693 * #define SILC_STR_FUNC() ...
697 * Formatting and unformatting of arbitrary data.
699 * Formatting: SILC_STR_FUNC(function, void *value, void *context)
700 * Unformatting: SILC_STR_FUNC(function, void **value, void *context)
702 * This type can be used to call the `function' of the type
703 * SilcBufferFormatFunc or SilcBufferUnformatFunc to encode or decode
704 * the `value'. In encoding the `value' will be passed to the `function'
705 * and can be encoded into the buffer. The buffer will be passed as
706 * well to the `function' at the location where SILC_STR_FUNC is placed
707 * in formatting. The `context' delivers caller specific context to
710 * In unformatting the `function' will decode the encoded type and
711 * return it to `value' pointer. The decoding function should decide
712 * itself whether to allocate or not the decoded value.
714 * The `function' does not have to encode anything and passing `value'
715 * as NULL is allowed. The `function' could for example modify the
720 * // Encode payload, encrypt and compute MAC.
721 * silc_buffer_format(buf,
722 * SILC_STR_FUNC(foo_encode_id, id, ctx),
723 * SILC_STR_UINT16(len),
724 * SILC_STR_DATA(data, len),
725 * SILC_STR_FUNC(foo_buf_encrypt, NULL, key),
726 * SILC_STR_FUNC(foo_buf_hmac, NULL, hmac),
727 * SILC_STR_DATA(iv, iv_len);
730 * // Check MAC, decrypt and decode payload
731 * silc_buffer_unformat(buf,
732 * SILC_STR_FUNC(foo_buf_hmac, NULL, hmac),
733 * SILC_STR_FUNC(foo_buf_decrypt, NULL, key),
734 * SILC_STR_FUNC(foo_decode_id, &id, ctx),
735 * SILC_STR_UINT16(&len),
739 #define SILC_STR_FUNC(func, val, context) SILC_PARAM_FUNC, \
740 func, (val), (context)
742 /****d* silcutil/SilcBufferFormatAPI/SilcBufferRegexFlags
746 * typedef enum { ... } SilcBufferRegexFlags;
750 * Regular expression flags for SILC_STR_REGEX macro. The flags can be
751 * used to manipulate the behavior of the SILC_STR_REGEX. All flags
752 * may be combined unless otherwise stated.
757 SILC_STR_REGEX_NONE = 0x00000000,
759 /* By default mismatch will be skipped. Set this flag if mismatch should
760 cause error and stopping of the formatting/unformatting. */
761 SILC_STR_REGEX_MISMATCH = 0x00000001,
763 /* By default only the first match is found. Set this flag to find
765 SILC_STR_REGEX_ALL = 0x00000002,
767 /* By default the buffer position is advanced to the position of the
768 first match. Set this flag if the buffer should not be advanced to
770 SILC_STR_REGEX_NO_ADVANCE = 0x00000004,
772 /* By default SILC_STR_REGEX performs the match on the whole buffer. Set
773 this flag to make it behave like sed and match line by line. Each line
774 must end with '\n'. If buffer doesn't have '\n' it is considered to be
775 one line. Note that, any formatting done immediately after SILC_STR_REGEX
776 block with this flag will be formatted to the end of the buffer (after
777 last line). Use SILC_STR_OFFSET* macros to change the position if
778 needed. Also note that, any encoding macro inside the SILC_STR_REGEX
779 block will see only the matched line (including '\n'), instead of whole
780 buffer after the match. */
781 SILC_STR_REGEX_NL = 0x00000008,
783 /* Set this flag to not match the regular expression, but to match everything
784 else. When combined with SILC_STR_REGEX_NL this flag matches all other
785 lines except the ones with matching regular expression. */
786 SILC_STR_REGEX_NOT = 0x00000010,
788 /* By default the buffer is advanced to the first match and the rest of the
789 buffer remains as is. Set this flag to pass the exact match to the
790 SILC_STR_* macros in the SILC_STR_REGEX block; macros see the start of
791 the match and the end of the match, but not rest of the buffer (ie. with
792 match 'foo' the size of the buffer is 3 bytes). */
793 SILC_STR_REGEX_INCLUSIVE = 0x00000020,
794 } SilcBufferRegexFlags;
797 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_REGEX
801 * #define SILC_STR_REGEX() ...
805 * Regular expression matching within the buffer.
807 * Formatting: SILC_STR_REGEX(char *regex, SilcBufferRegexFlags flags)
808 * Unformatting: SILC_STR_REGEX(char *regex, SilcBufferRegexFlags flags)
810 * SILC_STR_REGEX can be used to do regular expression matching within
811 * the SilcBuffer. When the string in the buffer matches the regular
812 * expression the position of the buffer is advanced to the position of
813 * the first match (rest of the buffer remains intact). If the regular
814 * expression does not match it is skipped, unless the flags specify
815 * otherwise. If flags are not needed they can be set to 0.
817 * In addition of matching regular expressions it can be used in a
818 * Stream Editor (sed) and Awk like fashion. The regular expression can be
819 * matched and then edited by any of the SILC_STR_* macros. The flags
820 * can be used to perform complex operations on the data. Some sed
821 * features that cannot be directly done with the flags can be done with
822 * SILC_STR_FUNC and other macros (the SILC_STR_FUNC could do anything
825 * The SILC_STR_REGEX itself is used as an opening of a block of encoding
826 * macros and must be closed with SILC_STR_END. This means that for
827 * each SILC_STR_REGEX there must be one SILC_STR_END. See examples for
830 * The SILC_STR_REGEX can be used in buffer unformatting also to do
831 * string matching and parsing, but not editing, except with SILC_STR_FUNC
832 * macro, which can do anything caller wants.
836 * // sed 's/foo/bar/', replace first foo with bar
837 * silc_buffer_format(buffer,
838 * SILC_STR_REGEX("foo", 0),
839 * SILC_STR_STRING("bar"),
840 * SILC_STR_END, SILC_STR_END);
842 * // sed 's/foo/bar/g', replace all foo's with bar
843 * silc_buffer_format(buffer,
844 * SILC_STR_REGEX("foo", SILC_STR_REGEX_ALL),
845 * SILC_STR_STRING("bar"),
846 * SILC_STR_END, SILC_STR_END);
848 * // sed '/baz/s/foo/bar/g, replace all foo's with bar on lines with baz
849 * silc_buffer_format(buffer,
850 * SILC_STR_REGEX("baz", SILC_STR_REGEX_NL),
851 * SILC_STR_REGEX("foo", SILC_STR_REGEX_ALL),
852 * SILC_STR_STRING("bar"),
854 * SILC_STR_END, SILC_STR_END);
856 * // Print all lines that start with 'R'
857 * int print(SilcStack stack, SilcBuffer buf, void *value, void *context)
859 * return fwrite(silc_buffer_data(buf), 1, silc_buffer_len(buf), stdout);
862 * silc_buffer_unformat(buffer,
863 * SILC_STR_REGEX("^R", SILC_STR_REGEX_NL),
864 * SILC_STR_FUNC(print, NULL, NULL),
865 * SILC_STR_END, SILC_STR_END);
868 #define SILC_STR_REGEX(regex, flags) SILC_PARAM_REGEX, (regex), (flags)
870 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_OFFSET
874 * #define SILC_STR_OFFSET() ...
878 * Offset in buffer. This can be used in formatting and unformatting to
879 * move the data pointer of the buffer either forwards (positive offset)
880 * or backwards (negative offset). It can be used to for example skip
881 * some types during unformatting.
885 * ..., SILC_STR_OFFSET(5), ...
886 * ..., SILC_STR_OFFSET(-3), ...
888 * Moves the data pointer at the point of the offset either forward
889 * or backward and then moves to the next type. Multiple SILC_STR_OFFSETs
890 * can be used in formatting and unformatting at the same time.
893 #define SILC_STR_OFFSET(x) SILC_PARAM_OFFSET, (x)
895 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_OFFSET_START
899 * #define SILC_STR_OFFSET_START ...
903 * Moves the buffer position to the start of the data area.
907 * ..., SILC_STR_OFFSET_START, ...
910 #define SILC_STR_OFFSET_START SILC_PARAM_OFFSET_START
912 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_OFFSET_END
916 * #define SILC_STR_OFFSET_END ...
920 * Moves the buffer position to the end of the data area.
924 * ..., SILC_STR_OFFSET_END, ...
927 #define SILC_STR_OFFSET_END SILC_PARAM_OFFSET_END
929 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_ADVANCE
933 * #define SILC_STR_ADVANCE ...
937 * Advance the buffer to the end of the data after the formatting is
938 * done. In normal operation when the formatted data is written the
939 * buffer is positioned at the start of the data. With SILC_STR_ADVANCE
940 * the buffer will be positioned at the end of the data. This makes it
941 * easy to add new data immediately after the previously added data.
942 * The SILC_STR_ADVANCE may also be used in unformatting.
947 * len = read(fd, buf, sizeof(buf));
949 * // Add read data to the buffer
950 * silc_buffer_format(buffer,
952 * SILC_STR_DATA(buf, len),
956 * // Move to beginning of buffer
957 * silc_buffer_start(buffer);
960 #define SILC_STR_ADVANCE SILC_PARAM_ADVANCE
962 /****d* silcutil/SilcBufferFormatAPI/SILC_STR_END
966 * #define SILC_STR_END ...
970 * Marks end of the argument list. This must be at the end of the
971 * argument list or error will occur.
974 #define SILC_STR_END SILC_PARAM_END
976 /****d* silcutil/SilcBufferFormatAPI/SILC_STRFMT_END
980 * #define SILC_STRFMT_END ...
984 * Marks end of the argument list in silc_buffer_strformat function.
985 * This must be at the end of the argument list or error will occur.
988 #define SILC_STRFMT_END (void *)SILC_STR_END
990 #endif /* !SILCBUFFMT_H */