/*
- silcbuffmt.h
+ silcbuffmt.h
Author: Pekka Riikonen <priikone@silcnet.org>
- Copyright (C) 1997 - 2003 Pekka Riikonen
+ Copyright (C) 1997 - 2006 Pekka Riikonen
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
* DESCRIPTION
*
* Formats a buffer from a variable argument list. Returns -1 on error
- * and the length of the formatted buffer otherwise.
+ * and the length of the formatted buffer otherwise. The buffer is
+ * enlarged automatically during formatting, if it doesn't already have
+ * enough space.
*
* EXAMPLE
*
- * ret = silc_buffer_format(buffer,
+ * SilcBufferStruct buffer;
+ *
+ * memset(&buffer, 0, sizeof(buffer));
+ * ret = silc_buffer_format(&buffer,
* SILC_STR_INT(intval),
* SILC_STR_CHAR(charval),
* SILC_STR_INT(intval),
***/
int silc_buffer_format(SilcBuffer dst, ...);
+/****f* silcutil/SilcBufferFormatAPI/silc_buffer_sformat
+ *
+ * SYNOPSIS
+ *
+ * int silc_buffer_sformat(SilcStack stack, SilcBuffer dst, ...);
+ *
+ * DESCRIPTION
+ *
+ * Same as silc_buffer_format but uses `stack' to allocate the memory.
+ * if `stack' is NULL reverts back to silc_buffer_format call.
+ *
+ ***/
+int silc_buffer_sformat(SilcStack stack, SilcBuffer dst, ...);
+
+/****f* silcutil/SilcBufferFormatAPI/silc_buffer_format_vp
+ *
+ * SYNOPSIS
+ *
+ * int silc_buffer_format_vp(SilcBuffer dst, va_list vp);
+ *
+ * DESCRIPTION
+ *
+ * Formats a buffer from a variable argument list indicated by the `ap'.
+ * Returns -1 on error and the length of the formatted buffer otherwise.
+ *
+ ***/
+int silc_buffer_format_vp(SilcBuffer dst, va_list ap);
+
+/****f* silcutil/SilcBufferFormatAPI/silc_buffer_format_vp
+ *
+ * SYNOPSIS
+ *
+ * int silc_buffer_format_vp(SilcBuffer dst, va_list vp);
+ *
+ * DESCRIPTION
+ *
+ * Same as silc_buffer_format_vp but uses `stack' to allocate the memory.
+ * if `stack' is NULL reverts back to silc_buffer_format_vp call.
+ *
+ ***/
+int silc_buffer_sformat_vp(SilcStack stack, SilcBuffer dst, va_list ap);
+
/****f* silcutil/SilcBufferFormatAPI/silc_buffer_unformat
*
* SYNOPSIS
* ret = silc_buffer_unformat(buffer,
* SILC_STR_INT(&intval),
* SILC_STR_CHAR(&charval),
- * SILC_STR_INT(&intval2),
+ * SILC_STR_OFFSET(4),
* SILC_STR_UI16_NSTRING_ALLOC(&str, &str_len),
* SILC_STR_END);
* if (ret < 0)
***/
int silc_buffer_unformat(SilcBuffer src, ...);
-/****f* silcutil/SilcBufferFormatAPI/silc_buffer_format_vp
- *
- * SYNOPSIS
- *
- * int silc_buffer_format_vp(SilcBuffer dst, va_list vp);
- *
- * DESCRIPTION
- *
- * Formats a buffer from a variable argument list indicated by the `ap'.
- * Returns -1 on error and the length of the formatted buffer otherwise.
- *
- ***/
-int silc_buffer_format_vp(SilcBuffer dst, va_list ap);
-
/****f* silcutil/SilcBufferFormatAPI/silc_buffer_unformat_vp
*
* SYNOPSIS
***/
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_STR_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, ...);
+
/* Macros for expanding parameters into variable function argument list.
These are passed to silc_buffer_format and silc_buffer_unformat
functions. */
SILC_BUFFER_PARAM_UI_XNSTRING, /* No copy */
SILC_BUFFER_PARAM_UI_XNSTRING_ALLOC, /* Alloc + memcpy */
+ SILC_BUFFER_PARAM_OFFSET,
+
SILC_BUFFER_PARAM_END
} SilcBufferParamType;
* automatically.
*
* Example:
- *
+ *
* Formatting: ..., SILC_STR_UI_INT(strlen(string)),
* SILC_STR_UI32_STRING(string), ...
* Unformatting: ..., SILC_STR_UI32_STRING(&string), ...
#define SILC_STR_UI_XNSTRING_ALLOC(x, l) \
SILC_BUFFER_PARAM_UI_XNSTRING_ALLOC, (x), (l)
+/****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_BUFFER_PARAM_OFFSET, (x)
+
/****d* silcutil/SilcBufferFormatAPI/SILC_STR_END
*
* NAME
***/
#define SILC_STR_END SILC_BUFFER_PARAM_END
+/****d* silcutil/SilcBufferFormatAPI/SILC_STRFMT_END
+ *
+ * NAME
+ *
+ * #define SILC_STRFMT_END ...
+ *
+ * DESCRIPTION
+ *
+ * Marks end of the argument list in silc_buffer_strformat function.
+ * This must be at the end of the argument list or error will occur.
+ *
+ ***/
+#define SILC_STRFMT_END (void *)SILC_STR_END
+
#endif /* !SILCBUFFMT_H */