/* Check that buffer has enough room to format data in it, if not
allocate more. */
-#define FORMAT_HAS_SPACE(__s__, __x__, __req__) \
-do { \
- if (__req__ > silc_buffer_len((__x__))) \
- if (!silc_buffer_srealloc_size((__s__), (__x__), \
- silc_buffer_truelen((__x__)) + __req__)) \
- goto fail; \
- flen += __req__; \
+#define FORMAT_HAS_SPACE(s, b, req) \
+do { \
+ if (!silc_buffer_senlarge(s, b, req)) \
+ goto fail; \
+ flen += req; \
} while(0)
/* Check that there is data to be unformatted */
-#define UNFORMAT_HAS_SPACE(__x__, __req__) \
+#define UNFORMAT_HAS_SPACE(b, req) \
do { \
- if (__req__ > silc_buffer_len((__x__))) \
+ if (req > silc_buffer_len(b)) \
goto fail; \
- if ((__req__ + 1) <= 0) \
+ if ((req + 1) <= 0) \
goto fail; \
} while(0)
fmt = va_arg(ap, SilcBufferParamType);
switch(fmt) {
- case SILC_PARAM_OFFSET:
- {
- int offst = va_arg(ap, int);
- if (!offst)
- break;
- if (offst > 1) {
- if (offst > silc_buffer_len(dst))
- goto fail;
- silc_buffer_pull(dst, offst);
- flen += offst;
- } else {
- silc_buffer_push(dst, -(offst));
- flen += -(offst);
+ case SILC_PARAM_FUNC:
+ {
+ SilcBufferFormatFunc func;
+ SilcBufferSFormatFunc funcs;
+ void *val;
+ void *context;
+ int tmp_len;
+ if (!stack)
+ func = va_arg(ap, SilcBufferFormatFunc);
+ else
+ funcs = va_arg(ap, SilcBufferSFormatFunc);
+ val = va_arg(ap, void *);
+ context = va_arg(ap, void *);
+ if (!stack)
+ tmp_len = func(dst, val, context);
+ else
+ tmp_len = funcs(stack, dst, val, context);
+ if (tmp_len < 0)
+ goto fail;
+ if (tmp_len) {
+ silc_buffer_pull(dst, tmp_len);
+ flen += tmp_len;
}
+ }
+ break;
+ case SILC_PARAM_UI8_STRING:
+ case SILC_PARAM_UI16_STRING:
+ case SILC_PARAM_UI32_STRING:
+ case SILC_PARAM_UI8_STRING_ALLOC:
+ case SILC_PARAM_UI16_STRING_ALLOC:
+ case SILC_PARAM_UI32_STRING_ALLOC:
+ {
+ unsigned char *x = va_arg(ap, unsigned char *);
+ SilcUInt32 tmp_len = strlen(x);
+ FORMAT_HAS_SPACE(stack, dst, tmp_len);
+ silc_buffer_put(dst, x, tmp_len);
+ silc_buffer_pull(dst, tmp_len);
break;
}
- case SILC_PARAM_SI8_CHAR:
+ case SILC_PARAM_UI8_NSTRING:
+ case SILC_PARAM_UI16_NSTRING:
+ case SILC_PARAM_UI32_NSTRING:
+ case SILC_PARAM_UI_XNSTRING:
+ case SILC_PARAM_DATA:
+ case SILC_PARAM_UI8_NSTRING_ALLOC:
+ case SILC_PARAM_UI16_NSTRING_ALLOC:
+ case SILC_PARAM_UI32_NSTRING_ALLOC:
+ case SILC_PARAM_UI_XNSTRING_ALLOC:
+ case SILC_PARAM_DATA_ALLOC:
{
- char x = (char)va_arg(ap, int);
- FORMAT_HAS_SPACE(stack, dst, 1);
- silc_buffer_put(dst, &x, 1);
- silc_buffer_pull(dst, 1);
+ unsigned char *x = va_arg(ap, unsigned char *);
+ SilcUInt32 tmp_len = va_arg(ap, SilcUInt32);
+ if (x && tmp_len) {
+ FORMAT_HAS_SPACE(stack, dst, tmp_len);
+ silc_buffer_put(dst, x, tmp_len);
+ silc_buffer_pull(dst, tmp_len);
+ }
break;
}
case SILC_PARAM_UI8_CHAR:
silc_buffer_pull(dst, 1);
break;
}
- case SILC_PARAM_SI16_SHORT:
- {
- unsigned char xf[2];
- SilcInt16 x = (SilcInt16)va_arg(ap, int);
- FORMAT_HAS_SPACE(stack, dst, 2);
- SILC_PUT16_MSB(x, xf);
- silc_buffer_put(dst, xf, 2);
- silc_buffer_pull(dst, 2);
- break;
- }
case SILC_PARAM_UI16_SHORT:
{
unsigned char xf[2];
silc_buffer_pull(dst, 2);
break;
}
- case SILC_PARAM_SI32_INT:
- {
- unsigned char xf[4];
- SilcInt32 x = va_arg(ap, SilcInt32);
- FORMAT_HAS_SPACE(stack, dst, 4);
- SILC_PUT32_MSB(x, xf);
- silc_buffer_put(dst, xf, 4);
- silc_buffer_pull(dst, 4);
- break;
- }
case SILC_PARAM_UI32_INT:
{
unsigned char xf[4];
silc_buffer_pull(dst, 4);
break;
}
- case SILC_PARAM_SI64_INT:
- {
- unsigned char xf[8];
- SilcInt64 x = va_arg(ap, SilcInt64);
- FORMAT_HAS_SPACE(stack, dst, sizeof(SilcInt64));
- SILC_PUT64_MSB(x, xf);
- silc_buffer_put(dst, xf, sizeof(SilcInt64));
- silc_buffer_pull(dst, sizeof(SilcInt64));
- break;
- }
case SILC_PARAM_UI64_INT:
{
unsigned char xf[8];
silc_buffer_pull(dst, sizeof(SilcUInt64));
break;
}
- case SILC_PARAM_UI8_STRING:
- case SILC_PARAM_UI16_STRING:
- case SILC_PARAM_UI32_STRING:
- case SILC_PARAM_UI8_STRING_ALLOC:
- case SILC_PARAM_UI16_STRING_ALLOC:
- case SILC_PARAM_UI32_STRING_ALLOC:
+ case SILC_PARAM_SI8_CHAR:
{
- unsigned char *x = va_arg(ap, unsigned char *);
- SilcUInt32 tmp_len = strlen(x);
- FORMAT_HAS_SPACE(stack, dst, tmp_len);
- silc_buffer_put(dst, x, tmp_len);
- silc_buffer_pull(dst, tmp_len);
+ char x = (char)va_arg(ap, int);
+ FORMAT_HAS_SPACE(stack, dst, 1);
+ silc_buffer_put(dst, &x, 1);
+ silc_buffer_pull(dst, 1);
break;
}
- case SILC_PARAM_UI8_NSTRING:
- case SILC_PARAM_UI16_NSTRING:
- case SILC_PARAM_UI32_NSTRING:
- case SILC_PARAM_UI_XNSTRING:
- case SILC_PARAM_DATA:
- case SILC_PARAM_UI8_NSTRING_ALLOC:
- case SILC_PARAM_UI16_NSTRING_ALLOC:
- case SILC_PARAM_UI32_NSTRING_ALLOC:
- case SILC_PARAM_UI_XNSTRING_ALLOC:
- case SILC_PARAM_DATA_ALLOC:
+ case SILC_PARAM_SI16_SHORT:
{
- unsigned char *x = va_arg(ap, unsigned char *);
- SilcUInt32 tmp_len = va_arg(ap, SilcUInt32);
- if (x && tmp_len) {
- FORMAT_HAS_SPACE(stack, dst, tmp_len);
- silc_buffer_put(dst, x, tmp_len);
- silc_buffer_pull(dst, tmp_len);
- }
+ unsigned char xf[2];
+ SilcInt16 x = (SilcInt16)va_arg(ap, int);
+ FORMAT_HAS_SPACE(stack, dst, 2);
+ SILC_PUT16_MSB(x, xf);
+ silc_buffer_put(dst, xf, 2);
+ silc_buffer_pull(dst, 2);
+ break;
+ }
+ case SILC_PARAM_SI32_INT:
+ {
+ unsigned char xf[4];
+ SilcInt32 x = va_arg(ap, SilcInt32);
+ FORMAT_HAS_SPACE(stack, dst, 4);
+ SILC_PUT32_MSB(x, xf);
+ silc_buffer_put(dst, xf, 4);
+ silc_buffer_pull(dst, 4);
+ break;
+ }
+ case SILC_PARAM_SI64_INT:
+ {
+ unsigned char xf[8];
+ SilcInt64 x = va_arg(ap, SilcInt64);
+ FORMAT_HAS_SPACE(stack, dst, sizeof(SilcInt64));
+ SILC_PUT64_MSB(x, xf);
+ silc_buffer_put(dst, xf, sizeof(SilcInt64));
+ silc_buffer_pull(dst, sizeof(SilcInt64));
break;
}
case SILC_PARAM_BUFFER:
}
}
break;
- case SILC_PARAM_END:
- goto ok;
- break;
+ case SILC_PARAM_OFFSET:
+ {
+ int offst = va_arg(ap, int);
+ if (!offst)
+ break;
+ if (offst > 1) {
+ if (offst > silc_buffer_len(dst))
+ goto fail;
+ silc_buffer_pull(dst, offst);
+ flen += offst;
+ } else {
+ silc_buffer_push(dst, -(offst));
+ flen += -(offst);
+ }
+ break;
+ }
case SILC_PARAM_ADVANCE:
advance = TRUE;
break;
+ case SILC_PARAM_END:
+ goto ok;
+ break;
default:
SILC_LOG_DEBUG(("Bad buffer formatting type `%d'. Could not "
"format the data.", fmt));
fmt = va_arg(ap, SilcBufferParamType);
switch(fmt) {
- case SILC_PARAM_OFFSET:
- {
- int offst = va_arg(ap, int);
- if (!offst)
- break;
- if (offst > 1) {
- UNFORMAT_HAS_SPACE(src, offst);
- silc_buffer_pull(src, offst);
- } else {
- silc_buffer_push(src, -(offst));
+ case SILC_PARAM_FUNC:
+ {
+ SilcBufferUnformatFunc func;
+ SilcBufferSUnformatFunc funcs;
+ void **val;
+ void *context;
+ int tmp_len;
+ if (!stack)
+ func = va_arg(ap, SilcBufferUnformatFunc);
+ else
+ funcs = va_arg(ap, SilcBufferSUnformatFunc);
+ val = va_arg(ap, void **);
+ context = va_arg(ap, void *);
+ if (!stack)
+ tmp_len = func(src, val, context);
+ else
+ tmp_len = funcs(stack, src, val, context);
+ if (tmp_len < 0)
+ goto fail;
+ if (tmp_len) {
+ UNFORMAT_HAS_SPACE(src, tmp_len);
+ silc_buffer_pull(src, tmp_len);
}
+ }
+ case SILC_PARAM_UI_XNSTRING:
+ case SILC_PARAM_DATA:
+ {
+ unsigned char **x = va_arg(ap, unsigned char **);
+ SilcUInt32 len2 = va_arg(ap, SilcUInt32);
+ UNFORMAT_HAS_SPACE(src, len2);
+ if (len2 && x)
+ *x = src->data;
+ silc_buffer_pull(src, len2);
break;
}
- case SILC_PARAM_SI8_CHAR:
+ case SILC_PARAM_UI_XNSTRING_ALLOC:
+ case SILC_PARAM_DATA_ALLOC:
{
- char *x = va_arg(ap, char *);
- UNFORMAT_HAS_SPACE(src, 1);
- if (x)
- *x = src->data[0];
- silc_buffer_pull(src, 1);
+ unsigned char **x = va_arg(ap, unsigned char **);
+ SilcUInt32 len2 = va_arg(ap, SilcUInt32);
+ UNFORMAT_HAS_SPACE(src, len2);
+ if (len2 && x) {
+ *x = silc_scalloc(stack, len2 + 1, sizeof(unsigned char));
+ memcpy(*x, src->data, len2);
+ }
+ silc_buffer_pull(src, len2);
break;
}
case SILC_PARAM_UI8_CHAR:
silc_buffer_pull(src, 1);
break;
}
- case SILC_PARAM_SI16_SHORT:
- {
- SilcInt16 *x = va_arg(ap, SilcInt16 *);
- UNFORMAT_HAS_SPACE(src, 2);
- if (x)
- SILC_GET16_MSB(*x, src->data);
- silc_buffer_pull(src, 2);
- break;
- }
case SILC_PARAM_UI16_SHORT:
{
SilcUInt16 *x = va_arg(ap, SilcUInt16 *);
silc_buffer_pull(src, 2);
break;
}
- case SILC_PARAM_SI32_INT:
+ case SILC_PARAM_UI32_INT:
{
- SilcInt32 *x = va_arg(ap, SilcInt32 *);
+ SilcUInt32 *x = va_arg(ap, SilcUInt32 *);
UNFORMAT_HAS_SPACE(src, 4);
if (x)
SILC_GET32_MSB(*x, src->data);
silc_buffer_pull(src, 4);
break;
}
- case SILC_PARAM_UI32_INT:
+ case SILC_PARAM_UI64_INT:
{
- SilcUInt32 *x = va_arg(ap, SilcUInt32 *);
+ SilcUInt64 *x = va_arg(ap, SilcUInt64 *);
+ UNFORMAT_HAS_SPACE(src, sizeof(SilcUInt64));
+ if (x)
+ SILC_GET64_MSB(*x, src->data);
+ silc_buffer_pull(src, sizeof(SilcUInt64));
+ break;
+ }
+ case SILC_PARAM_SI8_CHAR:
+ {
+ char *x = va_arg(ap, char *);
+ UNFORMAT_HAS_SPACE(src, 1);
+ if (x)
+ *x = src->data[0];
+ silc_buffer_pull(src, 1);
+ break;
+ }
+ case SILC_PARAM_SI16_SHORT:
+ {
+ SilcInt16 *x = va_arg(ap, SilcInt16 *);
+ UNFORMAT_HAS_SPACE(src, 2);
+ if (x)
+ SILC_GET16_MSB(*x, src->data);
+ silc_buffer_pull(src, 2);
+ break;
+ }
+ case SILC_PARAM_SI32_INT:
+ {
+ SilcInt32 *x = va_arg(ap, SilcInt32 *);
UNFORMAT_HAS_SPACE(src, 4);
if (x)
SILC_GET32_MSB(*x, src->data);
silc_buffer_pull(src, sizeof(SilcInt64));
break;
}
- case SILC_PARAM_UI64_INT:
- {
- SilcUInt64 *x = va_arg(ap, SilcUInt64 *);
- UNFORMAT_HAS_SPACE(src, sizeof(SilcUInt64));
- if (x)
- SILC_GET64_MSB(*x, src->data);
- silc_buffer_pull(src, sizeof(SilcUInt64));
- break;
- }
case SILC_PARAM_UI8_STRING:
{
SilcUInt8 len2;
silc_buffer_pull(src, len2);
break;
}
- case SILC_PARAM_UI_XNSTRING:
- case SILC_PARAM_DATA:
- {
- unsigned char **x = va_arg(ap, unsigned char **);
- SilcUInt32 len2 = va_arg(ap, SilcUInt32);
- UNFORMAT_HAS_SPACE(src, len2);
- if (len2 && x)
- *x = src->data;
- silc_buffer_pull(src, len2);
- break;
- }
- case SILC_PARAM_UI_XNSTRING_ALLOC:
- case SILC_PARAM_DATA_ALLOC:
- {
- unsigned char **x = va_arg(ap, unsigned char **);
- SilcUInt32 len2 = va_arg(ap, SilcUInt32);
- UNFORMAT_HAS_SPACE(src, len2);
- if (len2 && x) {
- *x = silc_scalloc(stack, len2 + 1, sizeof(unsigned char));
- memcpy(*x, src->data, len2);
- }
- silc_buffer_pull(src, len2);
- break;
- }
case SILC_PARAM_BUFFER:
{
SilcBuffer x = va_arg(ap, SilcBuffer);
silc_buffer_pull(src, len2);
}
break;
+ case SILC_PARAM_OFFSET:
+ {
+ int offst = va_arg(ap, int);
+ if (!offst)
+ break;
+ if (offst > 1) {
+ UNFORMAT_HAS_SPACE(src, offst);
+ silc_buffer_pull(src, offst);
+ } else {
+ silc_buffer_push(src, -(offst));
+ }
+ break;
+ }
+ case SILC_PARAM_ADVANCE:
+ break;
case SILC_PARAM_END:
goto ok;
break;
- case SILC_PARAM_ADVANCE:
- break;
default:
SILC_LOG_DEBUG(("Bad buffer formatting type `%d'. Could not "
"format the data.", fmt));
#ifndef SILCBUFFMT_H
#define SILCBUFFMT_H
+/****f* silcutil/SilcBufferFormatAPI/SilcBufferFormatFunc
+ *
+ * SYNOPSIS
+ *
+ * typedef int (*SilcBufferFormatFunc)(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_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
+ * of the currently formatted data area. It is also possible to use
+ * silc_buffer_sformat 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.
+ *
+ * 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);
+
+/****f* silcutil/SilcBufferFormatAPI/SilcBufferUnformatFunc
+ *
+ * SYNOPSIS
+ *
+ * typedef int (*SilcBufferUnformatFunc)(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.
+ *
+ ***/
+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);
+
/* Prototypes */
/****f* silcutil/SilcBufferFormatAPI/silc_buffer_format
*
* EXAMPLE
*
+ * Three basic ways of using silc_buffer_format:
+ *
+ * // Statically allocated zero size buffer
* SilcBufferStruct buffer;
- * SilcBuffer buf;
*
* memset(&buffer, 0, sizeof(buffer));
* ret = silc_buffer_format(&buffer,
- * SILC_STR_INT(intval),
+ * SILC_STR_UI_INT(intval),
* SILC_STR_CHAR(charval),
- * SILC_STR_INT(intval),
+ * SILC_STR_UI_INT(intval),
* SILC_STR_SHORT(str_len),
- * SILC_STR_UI_XNSTRING(str, str_len),
+ * SILC_STR_DATA(str, str_len),
* SILC_STR_END);
* if (ret < 0)
* error;
* // Free the allocated data
* silc_buffer_purge(&buffer);
*
- * // Allocate zero size buffer
+ * // Dynamically allocated zero size buffer
+ * SilcBuffer buf;
* buf = silc_buffer_alloc(0);
* ret = silc_buffer_format(buf,
- * SILC_STR_INT(intval),
+ * SILC_STR_UI_INT(intval),
* SILC_STR_CHAR(charval),
* SILC_STR_END);
+ * if (ret < 0)
+ * error;
*
* // Free the allocated buffer
* silc_buffer_free(buf);
*
+ * // Dynamically allocated buffer with enough space
+ * SilcBuffer buf;
+ * buf = silc_buffer_alloc(2 + str_len);
+ * ret = silc_buffer_format(buf,
+ * SILC_STR_UI_SHORT(str_len),
+ * SILC_STR_DATA(str, str_len),
+ * SILC_STR_END);
+ * if (ret < 0)
+ * error;
+ *
***/
int silc_buffer_format(SilcBuffer dst, ...);
* EXAMPLE
*
* ret = silc_buffer_unformat(buffer,
- * SILC_STR_INT(&intval),
+ * SILC_STR_UI_INT(&intval),
* SILC_STR_CHAR(&charval),
* SILC_STR_OFFSET(4),
* SILC_STR_UI16_NSTRING_ALLOC(&str, &str_len),
SILC_PARAM_OFFSET,
SILC_PARAM_ADVANCE,
+ SILC_PARAM_FUNC,
SILC_PARAM_UI_XNSTRING,
SILC_PARAM_UI_XNSTRING_ALLOC,
*
* SilcBuffer formatting.
*
- * Formatting: SILC_STR_DATA(SilcBuffer)
- * Unformatting: SILC_STR_DATA(SilcBuffer)
+ * Formatting: SILC_STR_BUFFER(SilcBuffer)
+ * Unformatting: SILC_STR_BUFFER(SilcBuffer)
*
- * This type can be used to format and unformat SilcBuffer. The lenght
- * of the buffer will be automatically encoded into the buffer as a 32-bit
- * integer. In unformatting the SilcBuffer context must be pre-allocated.
+ * 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_BUFFER_DATA, (x)
+#define SILC_STR_BUFFER(x) SILC_PARAM_BUFFER, (x)
#define SILC_STR_BUFFER_ALLOC(x) SILC_PARAM_BUFFER_ALLOC, (x)
+/****d* silcutil/SilcBufferFormatAPI/SILC_STR_FUNC
+ *
+ * NAME
+ *
+ * #define SILC_STR_FUNC() ...
+ *
+ * DESCRIPTION
+ *
+ * SilcBuffer formatting.
+ *
+ * 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_UI_SHORT(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_UI_SHORT(&len),
+ * SILC_STR_END);
+ *
+ ***/
+#define SILC_STR_FUNC(func, val, context) SILC_PARAM_FUNC, \
+ func, (val), (context)
+
/****d* silcutil/SilcBufferFormatAPI/SILC_STR_OFFSET
*
* NAME
* // Add read data to the buffer
* silc_buffer_format(buffer,
* SILC_STR_ADVANCE,
- * SILC_STR_UI_XNSTRING(buf, len),
+ * SILC_STR_DATA(buf, len),
* SILC_STR_END);
* } while (len > 0);
*
projects / silc.git / commitdiff