Author: Pekka Riikonen <priikone@silcnet.org>
- Copyright (C) 1997 - 2006 Pekka Riikonen
+ Copyright (C) 1997 - 2007 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
* in multithreaded environment with a same SilcBuffer context without
* concurrency control.
*
+ * EXAMPLE
+ *
+ * SilcBufferStruct buffer;
+ *
+ * memset(&buffer, 0, sizeof(buffer));
+ * ret = silc_buffer_format(&buffer,
+ * SILC_STR_UI_INT(intval),
+ * SILC_STR_CHAR(charval),
+ * SILC_STR_UI_INT(intval),
+ * SILC_STR_SHORT(str_len),
+ * SILC_STR_DATA(str, str_len),
+ * SILC_STR_END);
+ * if (ret < 0)
+ * error;
+ *
***/
#ifndef SILCBUFFMT_H
*
* SYNOPSIS
*
- * typedef int (*SilcBufferFormatFunc)(SilcBuffer buffer,
+ * typedef int (*SilcBuffeSFormatFunc)(SilcStack stack,
+ * SilcBuffer buffer,
* void *value,
* void *context);
*
* Formatting function callback given with SILC_STR_FUNC type. The
* `buffer' is the buffer being formatted at the location where the
* SILC_STR_FUNC was placed in formatting. The function should call
- * silc_buffer_enlarge before it adds the data to the buffer to make
- * sure that it has enough space. The buffer->head points to the
- * start of the buffer and silc_buffer_headlen() gives the length
- * of the currently formatted data area. It is also possible to use
- * silc_buffer_format with `buffer' which will enlarge the buffer if
- * needed.
- *
- * The `value' is the value given to SILC_STR_FUNC that is to be formatted
- * into the buffer. It may be NULL if the function is not formatting
- * new data into the buffer. The `context' is caller specific context.
- * Returns -1 on error and length of the formatted value otherwise, and
- * 0 if nothing was formatted.
- *
- ***/
-typedef int (*SilcBufferFormatFunc)(SilcBuffer buffer, void *value,
- void *context);
-
-/****f* silcutil/SilcBufferFormatAPI/SilcBufferSFormatFunc
- *
- * SYNOPSIS
- *
- * typedef int (*SilcBufferSFormatFunc)(SilcStack stack,
- * SilcBuffer buffer,
- * void *value,
- * void *context);
- *
- * DESCRIPTION
- *
- * Formatting function callback given with SILC_STR_FUNC type. The
- * `buffer' is the buffer being formatted at the location where the
- * SILC_STR_FUNC was placed in formatting. The function should call
* silc_buffer_senlarge before it adds the data to the buffer to make
* sure that it has enough space. The buffer->head points to the
* start of the buffer and silc_buffer_headlen() gives the length
* Returns -1 on error and length of the formatted value otherwise, and
* 0 if nothing was formatted.
*
- * This is same as SilcBufferFormatFunc except the SilcStack will be
- * delivered. This callback must be used when SilcStack is used with
- * formatting.
- *
***/
-typedef int (*SilcBufferSFormatFunc)(SilcStack stack, SilcBuffer buffer,
- void *value, void *context);
+typedef int (*SilcBufferFormatFunc)(SilcStack stack, SilcBuffer buffer,
+ void *value, void *context);
/****f* silcutil/SilcBufferFormatAPI/SilcBufferUnformatFunc
*
* unformatted.
*
***/
-typedef int (*SilcBufferUnformatFunc)(SilcBuffer buffer, void **value,
- void *context);
-
-/****f* silcutil/SilcBufferFormatAPI/SilcBufferSUnformatFunc
- *
- * SYNOPSIS
- *
- * typedef int (*SilcBufferSUnformatFunc)(SilcStack stack,
- * SilcBuffer buffer,
- * void **value,
- * void *context);
- *
- * DESCRIPTION
- *
- * Unformatting function callback given with SILC_STR_FUNC type. The
- * `buffer' is the buffer being unformatted and is at the location where
- * the SILC_STR_FUNC was placed in unformatting. The function should
- * check there is enough data in the `buffer' before trying to decode
- * from it.
- *
- * If this function unformats anything from the buffer its value is to
- * be returned to the `value' pointer. The implementation should itself
- * decide whether the unformatted value is allocated or not. If this
- * function does not unformat anything, nothing is returned to `value'
- *
- * The `context' is caller specific context. Returns -1 on error, and
- * length of the unformatted value otherwise, and 0 if nothing was
- * unformatted.
- *
- * This is same as SilcBufferUnformatFunc except the SilcStack will be
- * delivered. This callback must be used when SilcStack is used with
- * unformatting.
- *
- ***/
-typedef int (*SilcBufferSUnformatFunc)(SilcStack stack, SilcBuffer buffer,
- void **value, void *context);
+typedef int (*SilcBufferUnformatFunc)(SilcStack stack, SilcBuffer buffer,
+ void **value, void *context);
/* Prototypes */
*
* DESCRIPTION
*
- * Formats a buffer from a variable argument list. Returns -1 on error
- * and the length of the formatted buffer otherwise. The buffer is
- * enlarged automatically during formatting, if it doesn't already have
- * enough space.
+ * Formats a buffer from a variable argument list. Returns -1 if the
+ * system is out of memory and the length of the formatted buffer otherwise.
+ * The buffer is enlarged automatically during formatting, if it doesn't
+ * already have enough space.
*
* EXAMPLE
*
* DESCRIPTION
*
* Same as silc_buffer_format but uses `stack' to allocate the memory.
- * if `stack' is NULL reverts back to silc_buffer_format call.
+ * if `stack' is NULL reverts back to silc_buffer_format call. Returns
+ * -1 if system is out of memory.
+ *
+ * Note that this call consumes the `stack'. The caller should push the
+ * stack before calling the function and pop it later.
*
***/
int silc_buffer_sformat(SilcStack stack, SilcBuffer dst, ...);
* 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.
+ * Returns -1 if system is out of memory 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
+/****f* silcutil/SilcBufferFormatAPI/silc_buffer_sformat_vp
*
* SYNOPSIS
*
- * int silc_buffer_format_vp(SilcBuffer dst, va_list vp);
+ * int silc_buffer_sformat_vp(SilcStack stack, 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.
+ * if `stack' is NULL reverts back to silc_buffer_format_vp call. Returns
+ * -1 if system is out of memory.
+ *
+ * Note that this call consumes the `stack'. The caller should push the
+ * stack before calling the function and pop it later.
*
***/
int silc_buffer_sformat_vp(SilcStack stack, SilcBuffer dst, va_list ap);
* Same as silc_buffer_unformat but uses `stack' to allocate the memory.
* if `stack' is NULL reverts back to silc_buffer_format call.
*
+ * Note that this call consumes the `stack'. The caller should push the
+ * stack before calling the function and pop it later.
+ *
***/
int silc_buffer_sunformat(SilcStack stack, SilcBuffer src, ...);
* 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.
*
+ * Note that this call consumes the `stack'. The caller should push the
+ * stack before calling the function and pop it later.
+ *
***/
int silc_buffer_sunformat_vp(SilcStack stack, SilcBuffer src, va_list ap);
*
* SYNOPSIS
*
- * int silc_buffer_strformat(SilcBuffer dst, ...);
+ * 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_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.
+ * 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. Returns -1 if system is out of memory.
*
* EXAMPLE
*
*
* SYNOPSIS
*
- * int silc_buffer_strformat(SilcStack stack, SilcBuffer dst, ...);
+ * 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'.
+ * 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'. Returns -1
+ * if system is out of memory.
+ *
+ * Note that this call consumes the `stack'. The caller should push the
+ * stack before calling the function and pop it later.
*
***/
int silc_buffer_sstrformat(SilcStack stack, SilcBuffer dst, ...);
*
* SilcInt16/SilcUInt16.
*
- * Formatting: SILC_STR_SI_SHORT(short)
+ * Formatting: SILC_STR_SI_SHORT(SilcInt16)
* SILC_STR_UI_SHORT(SilcUInt16)
- * Unformatting: SILC_STR_SI_SHORT(short *)
+ * Unformatting: SILC_STR_SI_SHORT(SilcInt16 *)
* SILC_STR_UI_SHORT(SilcUInt16 *)
*
***/
*
* SilcInt32/SilcUInt32.
*
- * Formatting: SILC_STR_SI_INT(int)
+ * Formatting: SILC_STR_SI_INT(SilcInt32)
* SILC_STR_UI_INT(SilcUInt32)
- * Unformatting: SILC_STR_SI_INT(int *)
+ * Unformatting: SILC_STR_SI_INT(SilcInt32 *)
* SILC_STR_UI_INT(SilcUInt32 *)
*
***/
*
* SilcInt64/SilcUInt64.
*
- * Formatting: SILC_STR_SI_INT64(int)
- * SILC_STR_UI_INT64(SilcUInt32)
- * Unformatting: SILC_STR_SI_INT64(int *)
- * SILC_STR_UI_INT64(SilcUInt32 *)
+ * 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)
* buffer is located at the start of the data. With SILC_STR_ADVANCE
* the buffer will be located 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
*
* } while (len > 0);
*
* // Move to beginning of buffer
- * silc_buffer_push(buffer, silc_buffer_truelen(buffer));
+ * silc_buffer_start(buffer);
*
***/
#define SILC_STR_ADVANCE SILC_PARAM_ADVANCE