diff options
author | Guy Harris <guy@alum.mit.edu> | 2016-07-14 16:01:57 -0700 |
---|---|---|
committer | Guy Harris <guy@alum.mit.edu> | 2016-07-14 23:02:39 +0000 |
commit | 1f8999bb96018446e48529e75e56bf17dd3c77cf (patch) | |
tree | 0103d875702fa1a7c64816e21e079d7ceee190c2 /wiretap/wtap_opttypes.h | |
parent | 42e72d529cdbab62d52a26332985ecf28b997a87 (diff) |
Redo the block options APIs.
A block can have zero or more instances of a given option. We
distinguish between "one instance only" options, where a block can have
zero or one instance, and "multiple instances allowed" options, where a
block can have zero or more instances.
For "one instance only" options:
"add" routines add an instance if there isn't one already
and fail if there is;
"set" routines add an instance if there isn't one already
and change the value of the existing instance if there is one;
"set nth" routines fail;
"get" routines return the value of the instance if there is one
and fail if there isn't;
"get nth" routines fail.
For "multiple instances allowed" options:
"add" routines add an instance;
"set" routines fail;
"set nth" routines set the value of the nth instance if there is
one and fail otherwise;
"get" routines fail;
"get nth" routines get the value if the nth instance if there is
one and fail otherwise.
Rename "optionblock" to just "block"; it describes the contents of a
block, including both mandatory items and options.
Add some support for NRB options, including IPv4 and IPv6 option types.
Change-Id: Iad184f668626c3d1498b2ed00c7f1672e4abf52e
Reviewed-on: https://code.wireshark.org/review/16444
Reviewed-by: Guy Harris <guy@alum.mit.edu>
Diffstat (limited to 'wiretap/wtap_opttypes.h')
-rw-r--r-- | wiretap/wtap_opttypes.h | 294 |
1 files changed, 218 insertions, 76 deletions
diff --git a/wiretap/wtap_opttypes.h b/wiretap/wtap_opttypes.h index 120e167c64..688de52aa5 100644 --- a/wiretap/wtap_opttypes.h +++ b/wiretap/wtap_opttypes.h @@ -24,6 +24,8 @@ #include "ws_symbol_export.h" +#include <wsutil/inet_ipv6.h> + #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ @@ -31,7 +33,7 @@ extern "C" { /* * We use the pcapng option codes for option type values. */ -#define OPT_EOFOPT 0x0000 /**< Appears in pcapng files, but not in option blocks. */ +#define OPT_EOFOPT 0x0000 /**< Appears in pcapng files, but not in blocks. */ #define OPT_COMMENT 0x0001 /**< NULL if not available */ /* Section Header block (SHB) */ @@ -109,6 +111,10 @@ extern "C" { * second offsets be useful for highly syncronized capture systems? */ +#define OPT_NS_DNSNAME 2 +#define OPT_NS_DNSIP4ADDR 3 +#define OPT_NS_DNSIP6ADDR 4 + #define OPT_ISB_STARTTIME 0x0002 #define OPT_ISB_ENDTIME 0x0003 #define OPT_ISB_IFRECV 0x0004 @@ -117,64 +123,73 @@ extern "C" { #define OPT_ISB_OSDROP 0x0007 #define OPT_ISB_USRDELIV 0x0008 -struct wtap_optionblock; -typedef struct wtap_optionblock *wtap_optionblock_t; +struct wtap_block; +typedef struct wtap_block *wtap_block_t; -/* Currently supported option blocks */ +/* + * Currently supported blocks; these are not the pcapng block type values + * for them, they're identifiers used internally. + */ typedef enum { - WTAP_OPTION_BLOCK_IF_DESCR = 0, - WTAP_OPTION_BLOCK_IF_STATS, - WTAP_OPTION_BLOCK_NG_SECTION, - WTAP_OPTION_BLOCK_NG_NRB, - WTAP_OPTION_BLOCK_END_OF_LIST -} wtap_optionblock_type_t; + WTAP_BLOCK_NG_SECTION = 0, + WTAP_BLOCK_IF_DESCR, + WTAP_BLOCK_NG_NRB, + WTAP_BLOCK_IF_STATS, + WTAP_BLOCK_END_OF_LIST +} wtap_block_type_t; /* Currently supported option types */ typedef enum { WTAP_OPTTYPE_UINT8, WTAP_OPTTYPE_UINT64, WTAP_OPTTYPE_STRING, + WTAP_OPTTYPE_IPv4, + WTAP_OPTTYPE_IPv6, WTAP_OPTTYPE_CUSTOM } wtap_opttype_e; typedef enum { WTAP_OPTTYPE_SUCCESS = 0, - WTAP_OPTTYPE_NOT_FOUND = -1, - WTAP_OPTTYPE_TYPE_MISMATCH = -2, - WTAP_OPTTYPE_ALREADY_EXISTS = -3 + WTAP_OPTTYPE_NO_SUCH_OPTION = -1, + WTAP_OPTTYPE_NOT_FOUND = -2, + WTAP_OPTTYPE_TYPE_MISMATCH = -3, + WTAP_OPTTYPE_NUMBER_MISMATCH = -4, + WTAP_OPTTYPE_ALREADY_EXISTS = -5, } wtap_opttype_return_val; -typedef void (*wtap_opttype_free_custom_func)(void* data); - struct wtap_opttype_custom { void* data; guint size; - wtap_opttype_free_custom_func free_func; }; +/* + * Structure describing a value of an option. + */ typedef union { guint8 uint8val; guint64 uint64val; + guint32 ipv4val; /* network byte order */ + struct e_in6_addr ipv6val; char *stringval; struct wtap_opttype_custom customval; -} wtap_option_type; +} wtap_optval_t; -struct wtap_dumper; +/* + * Structure describing an option in a block. + */ +typedef struct { + guint option_id; /**< option code for the option */ + wtap_optval_t value; /**< value */ +} wtap_option_t; -typedef void (*wtap_block_create_func)(wtap_optionblock_t block); -typedef void (*wtap_mand_free_func)(wtap_optionblock_t block); -typedef void (*wtap_mand_copy_func)(wtap_optionblock_t dest_block, wtap_optionblock_t src_block); +struct wtap_dumper; -typedef struct wtap_optblock_reg { - const char *name; /**< name of option */ - const char *description; /**< human-readable description of option */ - wtap_opttype_e type; /**< type of that option */ - wtap_option_type option; /**< pointer to variable storing the value */ - wtap_option_type default_val; /**< the default value of the option */ -} wtap_optblock_reg_t; +typedef void (*wtap_block_create_func)(wtap_block_t block); +typedef void (*wtap_mand_free_func)(wtap_block_t block); +typedef void (*wtap_mand_copy_func)(wtap_block_t dest_block, wtap_block_t src_block); -/** Initialize option block types. +/** Initialize block types. * * This is currently just a placeholder as nothing needs to be * initialized yet. Should handle "registration" when code is @@ -182,76 +197,96 @@ typedef struct wtap_optblock_reg { */ WS_DLL_PUBLIC void wtap_opttypes_initialize(void); -/** Create an option block by type +/** Create a block by type * - * Return a newly allocated option block with default options provided + * Return a newly allocated block with default options provided * - * @param[in] block_type Option block type to be created - * @return Newly allocated option block + * @param[in] block_type Block type to be created + * @return Newly allocated block */ -WS_DLL_PUBLIC wtap_optionblock_t wtap_optionblock_create(int block_type); +WS_DLL_PUBLIC wtap_block_t wtap_block_create(wtap_block_type_t block_type); -/** Free an option block +/** Free a block * - * Needs to be called to clean up any allocated option block + * Needs to be called to clean up any allocated block * * @param[in] block Block to be freed */ -WS_DLL_PUBLIC void wtap_optionblock_free(wtap_optionblock_t block); +WS_DLL_PUBLIC void wtap_block_free(wtap_block_t block); -/** Free an array of option blocks +/** Free an array of blocks * - * Needs to be called to clean up option blocks allocated + * Needs to be called to clean up blocks allocated * through GArray (for multiple blocks of same type) * Includes freeing the GArray * * @param[in] block_array Array of blocks to be freed */ -WS_DLL_PUBLIC void wtap_optionblock_array_free(GArray* block_array); +WS_DLL_PUBLIC void wtap_block_array_free(GArray* block_array); -/** Provide mandatory data of an option block +/** Provide mandatory data of a block * * @param[in] block Block from which to retrieve mandatory data - * @return Option block mandatory data. Structure varies based on option block type + * @return Block mandatory data. Structure varies based on block type */ -WS_DLL_PUBLIC void* wtap_optionblock_get_mandatory_data(wtap_optionblock_t block); +WS_DLL_PUBLIC void* wtap_block_get_mandatory_data(wtap_block_t block); -/** Add an option to the option block +/** Add UINT8 option value to a block * - * @param[in] block Block to which to add option + * @param[in] block Block to which to add the option * @param[in] option_id Identifier value for option - * @param[in] option structure explaining it + * @param[in] value Value of option * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful, * error code otherwise */ WS_DLL_PUBLIC wtap_opttype_return_val -wtap_optionblock_add_option(wtap_optionblock_t block, guint option_id, wtap_optblock_reg_t* option); +wtap_block_add_uint8_option(wtap_block_t block, guint option_id, guint8 value); -/** Set string option value in an option block +/** Set UINT8 option value in a block * * @param[in] block Block in which to set the option value * @param[in] option_id Identifier value for option * @param[in] value New value of option - * @param[in] value_length Maximum length of string to copy. * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful, * error code otherwise */ WS_DLL_PUBLIC wtap_opttype_return_val -wtap_optionblock_set_option_string(wtap_optionblock_t block, guint option_id, char* value, gsize value_length); +wtap_block_set_uint8_option_value(wtap_block_t block, guint option_id, guint8 value); + +/** Get UINT8 option value from a block + * + * @param[in] block Block from which to get the option value + * @param[in] option_id Identifier value for option + * @param[out] value Returned value of option + * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful, + * error code otherwise + */ +WS_DLL_PUBLIC wtap_opttype_return_val +wtap_block_get_uint8_option_value(wtap_block_t block, guint option_id, guint8* value) G_GNUC_WARN_UNUSED_RESULT; + +/** Add UINT64 option value to a block + * + * @param[in] block Block to which to add the option + * @param[in] option_id Identifier value for option + * @param[in] value Value of option + * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful, + * error code otherwise + */ +WS_DLL_PUBLIC wtap_opttype_return_val +wtap_block_add_uint64_option(wtap_block_t block, guint option_id, guint64 value); -/** Set string option value in an option block to a printf-formatted string +/** Set UINT64 option value in a block * * @param[in] block Block in which to set the option value * @param[in] option_id Identifier value for option - * @param[in] format printf-like format string + * @param[in] value New value of option * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful, * error code otherwise */ WS_DLL_PUBLIC wtap_opttype_return_val -wtap_optionblock_set_option_string_format(wtap_optionblock_t block, guint option_id, const char *format, ...) - G_GNUC_PRINTF(3,4); +wtap_block_set_uint64_option_value(wtap_block_t block, guint option_id, guint64 value); -/** Get string option value from an option block +/** Get UINT64 option value from a block * * @param[in] block Block from which to get the option value * @param[in] option_id Identifier value for option @@ -260,20 +295,20 @@ wtap_optionblock_set_option_string_format(wtap_optionblock_t block, guint option * error code otherwise */ WS_DLL_PUBLIC wtap_opttype_return_val -wtap_optionblock_get_option_string(wtap_optionblock_t block, guint option_id, char** value); +wtap_block_get_uint64_option_value(wtap_block_t block, guint option_id, guint64* value) G_GNUC_WARN_UNUSED_RESULT; -/** Get array of string option values from an option block +/** Add IPv4 address option value to a block * - * @param[in] block Block from which to get option values + * @param[in] block Block to which to add the option * @param[in] option_id Identifier value for option - * @param[out] value Returned GArray of option values + * @param[in] value Value of option * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful, * error code otherwise */ WS_DLL_PUBLIC wtap_opttype_return_val -wtap_optionblock_get_string_options(wtap_optionblock_t block, guint option_id, GArray **value); +wtap_block_add_ipv4_option(wtap_block_t block, guint option_id, guint32 value); -/** Set UINT64 option value in an option block +/** Set IPv4 option value in a block * * @param[in] block Block in which to set the option value * @param[in] option_id Identifier value for option @@ -282,9 +317,9 @@ wtap_optionblock_get_string_options(wtap_optionblock_t block, guint option_id, G * error code otherwise */ WS_DLL_PUBLIC wtap_opttype_return_val -wtap_optionblock_set_option_uint64(wtap_optionblock_t block, guint option_id, guint64 value); +wtap_block_set_ipv4_option_value(wtap_block_t block, guint option_id, guint32 value); -/** Get UINT64 option value from an option block +/** Get IPv4 option value from a block * * @param[in] block Block from which to get the option value * @param[in] option_id Identifier value for option @@ -293,9 +328,20 @@ wtap_optionblock_set_option_uint64(wtap_optionblock_t block, guint option_id, gu * error code otherwise */ WS_DLL_PUBLIC wtap_opttype_return_val -wtap_optionblock_get_option_uint64(wtap_optionblock_t block, guint option_id, guint64* value); +wtap_block_get_ipv4_option_value(wtap_block_t block, guint option_id, guint32* value) G_GNUC_WARN_UNUSED_RESULT; + +/** Add IPv6 address option value to a block + * + * @param[in] block Block to which to add the option + * @param[in] option_id Identifier value for option + * @param[in] value Value of option + * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful, + * error code otherwise + */ +WS_DLL_PUBLIC wtap_opttype_return_val +wtap_block_add_ipv6_option(wtap_block_t block, guint option_id, struct e_in6_addr *value); -/** Set UINT8 option value in an option block +/** Set IPv6 option value in a block * * @param[in] block Block in which to set the option value * @param[in] option_id Identifier value for option @@ -304,9 +350,9 @@ wtap_optionblock_get_option_uint64(wtap_optionblock_t block, guint option_id, gu * error code otherwise */ WS_DLL_PUBLIC wtap_opttype_return_val -wtap_optionblock_set_option_uint8(wtap_optionblock_t block, guint option_id, guint8 value); +wtap_block_set_ipv6_option_value(wtap_block_t block, guint option_id, struct e_in6_addr *value); -/** Get UINT8 option value from an option block +/** Get IPv6 option value from a block * * @param[in] block Block from which to get the option value * @param[in] option_id Identifier value for option @@ -315,9 +361,105 @@ wtap_optionblock_set_option_uint8(wtap_optionblock_t block, guint option_id, gui * error code otherwise */ WS_DLL_PUBLIC wtap_opttype_return_val -wtap_optionblock_get_option_uint8(wtap_optionblock_t block, guint option_id, guint8* value); +wtap_block_get_ipv6_option_value(wtap_block_t block, guint option_id, struct e_in6_addr* value) G_GNUC_WARN_UNUSED_RESULT; + +/** Add a string option to a block + * + * @param[in] block Block to which to add the option + * @param[in] option_id Identifier value for option + * @param[in] value Value of option + * @param[in] value_length Maximum length of string to copy. + * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful, + * error code otherwise + */ +WS_DLL_PUBLIC wtap_opttype_return_val +wtap_block_add_string_option(wtap_block_t block, guint option_id, const char *value, gsize value_length); + +/** Add a string option to a block witha printf-formatted string as its value + * + * @param[in] block Block to which to add the option + * @param[in] option_id Identifier value for option + * @param[in] format printf-like format string + * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful, + * error code otherwise + */ +WS_DLL_PUBLIC wtap_opttype_return_val +wtap_block_add_string_option_format(wtap_block_t block, guint option_id, const char *format, ...) + G_GNUC_PRINTF(3,4); + +/** Set string option value in a block + * + * @param[in] block Block in which to set the option value + * @param[in] option_id Identifier value for option + * @param[in] value New value of option + * @param[in] value_length Maximum length of string to copy. + * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful, + * error code otherwise + */ +WS_DLL_PUBLIC wtap_opttype_return_val +wtap_block_set_string_option_value(wtap_block_t block, guint option_id, const char* value, gsize value_length); + +/** Set string option value for nth instance of a particular option in a block + * + * @param[in] block Block in which to set the option value + * @param[in] option_id Identifier value for option + * @param[in] idx Instance number of option with that ID + * @param[in] value New value of option + * @param[in] value_length Maximum length of string to copy. + * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful, + * error code otherwise + */ +WS_DLL_PUBLIC wtap_opttype_return_val +wtap_block_set_nth_string_option_value(wtap_block_t block, guint option_id, guint idx, const char* value, gsize value_length); + +/** Set string option value in a block to a printf-formatted string + * + * @param[in] block Block in which to set the option value + * @param[in] option_id Identifier value for option + * @param[in] format printf-like format string + * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful, + * error code otherwise + */ +WS_DLL_PUBLIC wtap_opttype_return_val +wtap_block_set_string_option_value_format(wtap_block_t block, guint option_id, const char *format, ...) + G_GNUC_PRINTF(3,4); + +/** Get string option value from a block + * + * @param[in] block Block from which to get the option value + * @param[in] option_id Identifier value for option + * @param[out] value Returned value of option + * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful, + * error code otherwise + */ +WS_DLL_PUBLIC wtap_opttype_return_val +wtap_block_get_string_option_value(wtap_block_t block, guint option_id, char** value) G_GNUC_WARN_UNUSED_RESULT; + +/** Get string option value for nth instance of a particular option in a block + * + * @param[in] block Block from which to get the option value + * @param[in] option_id Identifier value for option + * @param[in] idx Instance number of option with that ID + * @param[out] value Returned value of option + * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful, + * error code otherwise + */ +WS_DLL_PUBLIC wtap_opttype_return_val +wtap_block_get_nth_string_option_value(wtap_block_t block, guint option_id, guint idx, char** value) G_GNUC_WARN_UNUSED_RESULT; + +/** Add a "custom" option value to a block + * + * @param[in] block Block to which to add the option + * @param[in] option_id Identifier value for option + * @param[in] value Value of option + * @param[in] value_size Size of value + * @return wtap_opttype_return_val - WTAP_OPTTYPE_SUCCESS if successful, + * error code otherwise + */ +WS_DLL_PUBLIC wtap_opttype_return_val +wtap_block_add_custom_option(wtap_block_t block, guint option_id, void* value, size_t value_size); -/** Set a "custom" option value in an option block +/** Set a "custom" option value in a block * * @param[in] block Block in which to set the option value * @param[in] option_id Identifier value for option @@ -326,9 +468,9 @@ wtap_optionblock_get_option_uint8(wtap_optionblock_t block, guint option_id, gui * error code otherwise */ WS_DLL_PUBLIC wtap_opttype_return_val -wtap_optionblock_set_option_custom(wtap_optionblock_t block, guint option_id, void* value); +wtap_block_set_custom_option_value(wtap_block_t block, guint option_id, void* value); -/** Get a "custom" option value from an option block +/** Get a "custom" option value from a block * * @param[in] block Block from which to get the option value * @param[in] option_id Identifier value for option @@ -337,9 +479,9 @@ wtap_optionblock_set_option_custom(wtap_optionblock_t block, guint option_id, vo * error code otherwise */ WS_DLL_PUBLIC wtap_opttype_return_val -wtap_optionblock_get_option_custom(wtap_optionblock_t block, guint option_id, void** value); +wtap_block_get_custom_option_value(wtap_block_t block, guint option_id, void** value) G_GNUC_WARN_UNUSED_RESULT; -/** Copy an option block to another. +/** Copy a block to another. * * Any options that are in the destination but not the source are not removed. * Options that are just in source will be added to destination @@ -347,11 +489,11 @@ wtap_optionblock_get_option_custom(wtap_optionblock_t block, guint option_id, vo * @param[in] dest_block Block to be copied to * @param[in] src_block Block to be copied from */ -WS_DLL_PUBLIC void wtap_optionblock_copy_options(wtap_optionblock_t dest_block, wtap_optionblock_t src_block); +WS_DLL_PUBLIC void wtap_block_copy(wtap_block_t dest_block, wtap_block_t src_block); -typedef void (*wtap_optionblock_foreach_func)(wtap_optionblock_t block, guint option_id, wtap_opttype_e option_type, wtap_option_type* option, void* user_data); -WS_DLL_PUBLIC void wtap_optionblock_foreach_option(wtap_optionblock_t block, wtap_optionblock_foreach_func func, void* user_data); +typedef void (*wtap_block_foreach_func)(wtap_block_t block, guint option_id, wtap_opttype_e option_type, wtap_optval_t *option, void *user_data); +WS_DLL_PUBLIC void wtap_block_foreach_option(wtap_block_t block, wtap_block_foreach_func func, void* user_data); WS_DLL_PUBLIC int wtap_opttype_register_custom_block_type(const char* name, const char* description, wtap_block_create_func create, wtap_mand_free_func free_mand, wtap_mand_copy_func copy_mand); |