X-Git-Url: http://git.silcnet.org/gitweb/?a=blobdiff_plain;f=lib%2Fsilcutil%2Fsilcbuffmt.h;h=86c155e3a7bb65cd143cfacafa3398b4db365c22;hb=413da0f8686910f5e627393157566ae729ca99c4;hp=e69e90bb6c6ce31cf11b0fe213cf5c30a807b8b8;hpb=a818c5b5411bbc4436d1c5f011236985c96bb787;p=silc.git diff --git a/lib/silcutil/silcbuffmt.h b/lib/silcutil/silcbuffmt.h index e69e90bb..86c155e3 100644 --- a/lib/silcutil/silcbuffmt.h +++ b/lib/silcutil/silcbuffmt.h @@ -1,16 +1,15 @@ /* - silcbuffmt.h + silcbuffmt.h - Author: Pekka Riikonen + Author: Pekka Riikonen - Copyright (C) 1997 - 2000 Pekka Riikonen + Copyright (C) 1997 - 2003 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 - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - + the Free Software Foundation; version 2 of the License. + This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the @@ -18,20 +17,129 @@ */ -/****h* silcutil/SilcBufferFormatAPI +/****h* silcutil/SILC Buffer Format Interface * * DESCRIPTION * - * SILC Buffer Format API provides a few functions for formatting - * various different data types into a buffer, and retrieving - * various data from buffer into specific data types. It is usefull - * to format for example packets and later unformat them. + * SILC Buffer Format API provides a few functions for formatting + * various different data types into a buffer, and retrieving + * various data from buffer into specific data types. It is usefull + * to format for example packets and later unformat them. * ***/ #ifndef SILCBUFFMT_H #define SILCBUFFMT_H +/* Prototypes */ + +/****f* silcutil/SilcBufferFormatAPI/silc_buffer_format + * + * SYNOPSIS + * + * int silc_buffer_format(SilcBuffer dst, ...); + * + * DESCRIPTION + * + * Formats a buffer from a variable argument list. Returns -1 on error + * and the length of the formatted buffer otherwise. + * + * EXAMPLE + * + * ret = silc_buffer_format(buffer, + * SILC_STR_INT(intval), + * SILC_STR_CHAR(charval), + * SILC_STR_INT(intval), + * SILC_STR_SHORT(str_len), + * SILC_STR_UI_XNSTRING(str, str_len), + * SILC_STR_END); + * if (ret < 0) + * error; + * + ***/ +int silc_buffer_format(SilcBuffer dst, ...); + +/****f* silcutil/SilcBufferFormatAPI/silc_buffer_unformat + * + * SYNOPSIS + * + * int silc_buffer_unformat(SilcBuffer src, ...); + * + * DESCRIPTION + * + * Unformats a buffer from a variable argument list. Returns -1 on error + * and the length of the unformatted buffer otherwise. + * + * EXAMPLE + * + * ret = silc_buffer_unformat(buffer, + * SILC_STR_INT(&intval), + * SILC_STR_CHAR(&charval), + * SILC_STR_INT(&intval2), + * SILC_STR_UI16_NSTRING_ALLOC(&str, &str_len), + * SILC_STR_END); + * if (ret < 0) + * error; + * + ***/ +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_unformat_vp(SilcBuffer src, va_list vp); + * + * DESCRIPTION + * + * Unformats a buffer from a variable argument list indicated by the `ap'. + * Returns -1 on error and the length of the unformatted buffer otherwise. + * + ***/ +int silc_buffer_unformat_vp(SilcBuffer src, va_list ap); + +/****f* silcutil/SilcBufferFormatAPI/silc_buffer_strformat + * + * SYNOPSIS + * + * 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. + * + * EXAMPLE + * + * ret = silc_buffer_strformat(buffer, "foo", "bar", SILC_STR_END); + * if (ret < 0) + * error; + * + ***/ +int silc_buffer_strformat(SilcBuffer dst, ...); + +/* Macros for expanding parameters into variable function argument list. + These are passed to silc_buffer_format and silc_buffer_unformat + functions. */ + /* Buffer parameter types. _SI_ = signed @@ -41,7 +149,7 @@ memcpy the data to the pointer sent as argument (in unformatting). Any XXX_STRING will not allocate or copy any data. Instead it - will set the pointer to the data. Note that the data pointer + will set the pointer to the data. Note that the data pointer returned (in unformatting) must not be freed. */ @@ -76,82 +184,129 @@ typedef enum { SILC_BUFFER_PARAM_END } SilcBufferParamType; -/* Macros for expanding parameters into variable function argument list. - These are passed to silc_buffer_format and silc_buffer_unformat - functions. */ - -/* One signed/unsigned character. - - Formatting: SILC_STR_SI_CHAR(char) - SILC_STR_UI_CHAR(unsigned char) - Unformatting: SILC_STR_SI_CHAR(char *) - SILC_STR_UI_CHAR(unsigned char *) - -*/ +/****d* silcutil/SilcBufferFormatAPI/SILC_STR_*_CHAR + * + * NAME + * + * #define SILC_STR_UI_CHAR() ... + * #define SILC_STR_SI_CHAR() ... + * + * DESCRIPTION + * + * One signed/unsigned character. + * + * Formatting: SILC_STR_SI_CHAR(char) + * SILC_STR_UI_CHAR(unsigned char) + * Unformatting: SILC_STR_SI_CHAR(char *) + * SILC_STR_UI_CHAR(unsigned char *) + * + ***/ #define SILC_STR_SI_CHAR(x) SILC_BUFFER_PARAM_SI8_CHAR, (x) #define SILC_STR_UI_CHAR(x) SILC_BUFFER_PARAM_UI8_CHAR, (x) -/* Signed/SilcUInt16. - - Formatting: SILC_STR_SI_SHORT(short) - SILC_STR_UI_SHORT(SilcUInt16) - Unformatting: SILC_STR_SI_SHORT(short *) - SILC_STR_UI_SHORT(SilcUInt16 *) - -*/ +/****d* silcutil/SilcBufferFormatAPI/SILC_STR_*_SHORT + * + * NAME + * + * #define SILC_STR_UI_SHORT() ... + * #define SILC_STR_SI_SHORT() ... + * + * DESCRIPTION + * + * Signed/SilcUInt16. + * + * Formatting: SILC_STR_SI_SHORT(short) + * SILC_STR_UI_SHORT(SilcUInt16) + * Unformatting: SILC_STR_SI_SHORT(short *) + * SILC_STR_UI_SHORT(SilcUInt16 *) + * + ***/ #define SILC_STR_SI_SHORT(x) SILC_BUFFER_PARAM_SI16_SHORT, (x) #define SILC_STR_UI_SHORT(x) SILC_BUFFER_PARAM_UI16_SHORT, (x) -/* Signed/SilcUInt32. - - Formatting: SILC_STR_SI_INT(int) - SILC_STR_UI_INT(SilcUInt32) - Unformatting: SILC_STR_SI_INT(int *) - SILC_STR_UI_INT(SilcUInt32 *) - -*/ +/****d* silcutil/SilcBufferFormatAPI/SILC_STR_*_INT + * + * NAME + * + * #define SILC_STR_UI_INT() ... + * #define SILC_STR_SI_INT() ... + * + * DESCRIPTION + * + * Signed/SilcUInt32. + * + * Formatting: SILC_STR_SI_INT(int) + * SILC_STR_UI_INT(SilcUInt32) + * Unformatting: SILC_STR_SI_INT(int *) + * SILC_STR_UI_INT(SilcUInt32 *) + * + ***/ #define SILC_STR_SI_INT(x) SILC_BUFFER_PARAM_SI32_INT, (x) #define SILC_STR_UI_INT(x) SILC_BUFFER_PARAM_UI32_INT, (x) -/* Signed/SilcUInt64. - - Formatting: SILC_STR_SI_INT64(int) - SILC_STR_UI_INT64(SilcUInt32) - Unformatting: SILC_STR_SI_INT64(int *) - SILC_STR_UI_INT64(SilcUInt32 *) - -*/ +/****d* silcutil/SilcBufferFormatAPI/SILC_STR_*_INT64 + * + * NAME + * + * #define SILC_STR_UI_INT64() ... + * #define SILC_STR_SI_INT64() ... + * + * DESCRIPTION + * + * Signed/SilcUInt64. + * + * Formatting: SILC_STR_SI_INT64(int) + * SILC_STR_UI_INT64(SilcUInt32) + * Unformatting: SILC_STR_SI_INT64(int *) + * SILC_STR_UI_INT64(SilcUInt32 *) + * + ***/ #define SILC_STR_SI_INT64(x) SILC_BUFFER_PARAM_SI64_INT, (x) #define SILC_STR_UI_INT64(x) SILC_BUFFER_PARAM_UI64_INT, (x) -/* Unsigned NULL terminated string. Note that the string must be - NULL terminated because strlen() will be used to get the length of - the string. - - Formatting: SILC_STR_UI32_STRING(unsigned char *) - Unformatting: SILC_STR_UI32_STRING(unsigned char **) - - Unformatting procedure will check for length of the string from the - buffer before trying to get the string out. Thus, one *must* format the - length as UI_INT or UI_SHORT into the buffer *before* formatting the - actual string to the buffer, and, in unformatting one must ignore the - length of the string because unformatting procedure will take it - automatically. - - Example: - - Formatting: ..., SILC_STR_UI_INT(strlen(string)), - SILC_STR_UI32_STRING(string), ... - Unformatting: ..., SILC_STR_UI32_STRING(&string), ... - - I.e., you ignore the formatted length field in unformatting. If you don't - the unformatting procedure might fail and it definitely does not unformat - the data reliably. - - _ALLOC routines automatically allocates memory for the variable sent - as argument in unformatting. - -*/ +/****d* silcutil/SilcBufferFormatAPI/SILC_STR_*_STRING + * + * NAME + * + * #define SILC_STR_UI8_STRING() ... + * #define SILC_STR_UI8_STRING_ALLOC() ... + * #define SILC_STR_UI16_STRING() ... + * #define SILC_STR_UI16_STRING_ALLOC() ... + * #define SILC_STR_UI32_STRING() ... + * #define SILC_STR_UI32_STRING_ALLOC() ... + * + * DESCRIPTION + * + * Unsigned NULL terminated string. Note that the string must be + * NULL terminated because strlen() will be used to get the length of + * the string. + * + * Formatting: SILC_STR_UI32_STRING(unsigned char *) + * Unformatting: SILC_STR_UI32_STRING(unsigned char **) + * + * Unformatting procedure will check for length of the string from the + * buffer before trying to get the string out. Thus, one *must* format the + * length as UI_INT or UI_SHORT into the buffer *before* formatting the + * actual string to the buffer, and, in unformatting one must ignore the + * length of the string because unformatting procedure will take it + * automatically. + * + * Example: + * + * Formatting: ..., SILC_STR_UI_INT(strlen(string)), + * SILC_STR_UI32_STRING(string), ... + * Unformatting: ..., SILC_STR_UI32_STRING(&string), ... + * + * I.e., you can ignore the formatted length field in unformatting. + * + * UI8, UI16 and UI32 means that the length is considered to be + * either char (8 bits), short (16 bits) or int (32 bits) in + * unformatting. + * + * _ALLOC routines automatically allocates memory for the variable sent + * as argument in unformatting. + * + ***/ #define SILC_STR_UI8_STRING(x) SILC_BUFFER_PARAM_UI8_STRING, (x) #define SILC_STR_UI8_STRING_ALLOC(x) SILC_BUFFER_PARAM_UI8_STRING_ALLOC, (x) #define SILC_STR_UI16_STRING(x) SILC_BUFFER_PARAM_UI16_STRING, (x) @@ -159,128 +314,102 @@ typedef enum { #define SILC_STR_UI32_STRING(x) SILC_BUFFER_PARAM_UI32_STRING, (x) #define SILC_STR_UI32_STRING_ALLOC(x) SILC_BUFFER_PARAM_UI32_STRING_ALLOC, (x) -/* Unsigned string. Second argument is the length of the string. - - Formatting: SILC_STR_UI32_NSTRING(unsigned char *, SilcUInt32) - Unformatting: SILC_STR_UI32_NSTRING(unsigned char **, SilcUInt32 *) - - Unformatting procedure will check for length of the string from the - buffer before trying to get the string out. Thus, one *must* format the - length as UI_INT or UI_SHORT into the buffer *before* formatting the - actual string to the buffer, and, in unformatting one must ignore the - length of the string because unformatting procedure will take it - automatically. - - Example: - - Formatting: ..., SILC_STR_UI_INT(strlen(string)), - SILC_STR_UI32_NSTRING(string, strlen(string)), ... - Unformatting: ..., SILC_STR_UI32_NSTRING(&string, &len), ... - - I.e., you ignore the formatted length field in unformatting. If you don't - the unformatting procedure might fail and it definitely does not unformat - the data reliably. The length taken from the buffer is returned to the - pointer sent as argument (&len in above example). - - UI/SI16 and UI/SI32 means that the length is considered to be either - short (16 bits) or int (32 bits) in unformatting. - - _ALLOC routines automatically allocates memory for the variable sent - as argument in unformatting. - -*/ -#define SILC_STR_UI8_NSTRING(x, l) SILC_BUFFER_PARAM_UI8_NSTRING, (x), (l) -#define SILC_STR_UI8_NSTRING_ALLOC(x, l) \ - SILC_BUFFER_PARAM_UI8_NSTRING_ALLOC, (x), (l) -#define SILC_STR_UI16_NSTRING(x, l) SILC_BUFFER_PARAM_UI16_NSTRING, (x), (l) -#define SILC_STR_UI16_NSTRING_ALLOC(x, l) \ - SILC_BUFFER_PARAM_UI16_NSTRING_ALLOC, (x), (l) -#define SILC_STR_UI32_NSTRING(x, l) SILC_BUFFER_PARAM_UI32_NSTRING, (x), (l) -#define SILC_STR_UI32_NSTRING_ALLOC(x, l) \ - SILC_BUFFER_PARAM_UI32_NSTRING_ALLOC, (x), (l) - -/* Extended Unsigned string formatting. Second argument is the length of - the string. - - Formatting: This is equal to using *_NSTRING - Unformatting: SILC_STR_UI_XNSTRING(unsigned char **, SilcUInt32) - - This type can be used to take arbitrary length string from the buffer - by sending the requested amount of bytes as argument. This differs - from *_STRING and *_NSTRING so that this doesn't try to find the - length of the data from the buffer but the length of the data is - sent as argument. This a handy way to unformat fixed length strings - from the buffer without having the length of the string formatted - in the buffer. - - _ALLOC routines automatically allocates memory for the variable sent - as argument in unformatting. - -*/ -#define SILC_STR_UI_XNSTRING(x, l) SILC_BUFFER_PARAM_UI_XNSTRING, (x), (l) -#define SILC_STR_UI_XNSTRING_ALLOC(x, l) \ - SILC_BUFFER_PARAM_UI_XNSTRING_ALLOC, (x), (l) - -/* Marks end of the argument list. This must be at the end of the - argument list or error will occur. */ -#define SILC_STR_END SILC_BUFFER_PARAM_END - -/* Prototypes */ - -/****f* silcutil/SilcBufferFormatAPI/silc_buffer_format +/****d* silcutil/SilcBufferFormatAPI/SILC_STR_*_NSTRING * - * SYNOPSIS + * NAME * - * int silc_buffer_format(SilcBuffer dst, ...); + * #define SILC_STR_UI8_NSTRING() ... + * #define SILC_STR_UI8_NSTRING_ALLOC() ... + * #define SILC_STR_UI16_NSTRING() ... + * #define SILC_STR_UI16_NSTRING_ALLOC() ... + * #define SILC_STR_UI32_NSTRING() ... + * #define SILC_STR_UI32_NSTRING_ALLOC() ... * * DESCRIPTION * - * Formats a buffer from a variable argument list. Returns -1 on error - * and the length of the formatted buffer otherwise. + * Unsigned string. Second argument is the length of the string. * - ***/ -int silc_buffer_format(SilcBuffer dst, ...); - -/****f* silcutil/SilcBufferFormatAPI/silc_buffer_unformat + * Formatting: SILC_STR_UI32_NSTRING(unsigned char *, SilcUInt32) + * Unformatting: SILC_STR_UI32_NSTRING(unsigned char **, SilcUInt32 *) * - * SYNOPSIS + * Unformatting procedure will check for length of the string from the + * buffer before trying to get the string out. Thus, one *must* format the + * length as UI_INT or UI_SHORT into the buffer *before* formatting the + * actual string to the buffer, and, in unformatting one must ignore the + * length of the string because unformatting procedure will take it + * automatically. * - * int silc_buffer_unformat(SilcBuffer src, ...); + * Example: * - * DESCRIPTION + * Formatting: ..., SILC_STR_UI_INT(strlen(string)), + * SILC_STR_UI32_NSTRING(string, strlen(string)), ... + * Unformatting: ..., SILC_STR_UI32_NSTRING(&string, &len), ... * - * Formats a buffer from a variable argument list. Returns -1 on error - * and the length of the formatted buffer otherwise. + * I.e., you can ignore the formatted length field in unformatting. The + * length taken from the buffer is returned to the pointer sent as + * argument (&len in above example). + * + * UI8, UI16 and UI32 means that the length is considered to be + * either char (8 bits), short (16 bits) or int (32 bits) in + * unformatting. + * + * _ALLOC routines automatically allocates memory for the variable sent + * as argument in unformatting. * ***/ -int silc_buffer_unformat(SilcBuffer src, ...); +#define SILC_STR_UI8_NSTRING(x, l) SILC_BUFFER_PARAM_UI8_NSTRING, (x), (l) +#define SILC_STR_UI8_NSTRING_ALLOC(x, l) \ + SILC_BUFFER_PARAM_UI8_NSTRING_ALLOC, (x), (l) +#define SILC_STR_UI16_NSTRING(x, l) SILC_BUFFER_PARAM_UI16_NSTRING, (x), (l) +#define SILC_STR_UI16_NSTRING_ALLOC(x, l) \ + SILC_BUFFER_PARAM_UI16_NSTRING_ALLOC, (x), (l) +#define SILC_STR_UI32_NSTRING(x, l) SILC_BUFFER_PARAM_UI32_NSTRING, (x), (l) +#define SILC_STR_UI32_NSTRING_ALLOC(x, l) \ + SILC_BUFFER_PARAM_UI32_NSTRING_ALLOC, (x), (l) -/****f* silcutil/SilcBufferFormatAPI/silc_buffer_format_vp +/****d* silcutil/SilcBufferFormatAPI/SILC_STR_UI_XNSTRING * - * SYNOPSIS + * NAME * - * int silc_buffer_format_vp(SilcBuffer dst, va_list vp); + * #define SILC_STR_UI_XNSTRING() ... + * #define SILC_STR_UI_XNSTRING_ALLOC() ... * * 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. + * Extended Unsigned string formatting. Second argument is the length of + * the string. + * + * Formatting: SILC_STR_UI_XNSTRING(unsigned char *, SilcUInt32) + * Unformatting: SILC_STR_UI_XNSTRING(unsigned char **, SilcUInt32) + * + * This type can be used to take arbitrary length string from the buffer + * by sending the requested amount of bytes as argument. This differs + * from *_STRING and *_NSTRING so that this doesn't try to find the + * length of the data from the buffer but the length of the data is + * sent as argument. This a handy way to unformat fixed length strings + * from the buffer without having the length of the string formatted + * in the buffer. + * + * _ALLOC routines automatically allocates memory for the variable sent + * as argument in unformatting. * ***/ -int silc_buffer_format_vp(SilcBuffer dst, va_list ap); +#define SILC_STR_UI_XNSTRING(x, l) SILC_BUFFER_PARAM_UI_XNSTRING, (x), (l) +#define SILC_STR_UI_XNSTRING_ALLOC(x, l) \ + SILC_BUFFER_PARAM_UI_XNSTRING_ALLOC, (x), (l) -/****f* silcutil/SilcBufferFormatAPI/silc_buffer_unformat_vp +/****d* silcutil/SilcBufferFormatAPI/SILC_STR_END * - * SYNOPSIS + * NAME * - * int silc_buffer_unformat_vp(SilcBuffer src, va_list vp); + * #define SILC_STR_END ... * * 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. + * Marks end of the argument list. This must be at the end of the + * argument list or error will occur. * ***/ -int silc_buffer_unformat_vp(SilcBuffer src, va_list ap); +#define SILC_STR_END SILC_BUFFER_PARAM_END -#endif +#endif /* !SILCBUFFMT_H */