uat.h File Reference

#include <stdlib.h>
#include "ws_symbol_export.h"
#include <wsutil/strtoi.h>
#include <wsutil/dtoa.h>

Go to the source code of this file.

Classes
struct	_uat_field_t
	Describes a single editable field within a UAT (User Accessible Table). More...

Macros
#define	FLDFILL   NULL
#define	UAT_END_FIELDS   {NULL,NULL,PT_TXTMOD_NONE,{0,0,0},{0,0,0},0,0,FLDFILL}
#define	UAT_AFFECTS_DISSECTION   0x00000001 /* affects packet dissection */
#define	UAT_AFFECTS_FIELDS   0x00000002 /* affects what named fields exist */
#define	UNUSED_PARAMETER(n)   n _U_
#define	UAT_CSTRING_CB_DEF(basename, field_name, rec_t)
#define	UAT_FLD_CSTRING(basename, field_name, title, desc)    {#field_name, title, PT_TXTMOD_STRING,{uat_fld_chk_str,basename ## _ ## field_name ## _set_cb,basename ## _ ## field_name ## _tostr_cb},{0,0,0},0,desc,FLDFILL}
#define	UAT_FLD_CSTRING_ISPRINT(basename, field_name, title, desc)    {#field_name, title, PT_TXTMOD_STRING,{uat_fld_chk_str_isprint,basename ## _ ## field_name ## _set_cb,basename ## _ ## field_name ## _tostr_cb},{0,0,0},0,desc,FLDFILL}
#define	UAT_FLD_CSTRING_OTHER(basename, field_name, title, chk, desc)    {#field_name, title, PT_TXTMOD_STRING,{ chk ,basename ## _ ## field_name ## _set_cb,basename ## _ ## field_name ## _tostr_cb},{0,0,0},0,desc,FLDFILL}
#define	UAT_FILENAME_CB_DEF(basename, field_name, rec_t)   UAT_CSTRING_CB_DEF(basename,field_name,rec_t)
#define	UAT_FLD_FILENAME(basename, field_name, title, desc)    {#field_name, title, PT_TXTMOD_FILENAME,{uat_fld_chk_str,basename ## _ ## field_name ## _set_cb,basename ## _ ## field_name ## _tostr_cb},{0,0,0},0,desc,FLDFILL}
#define	UAT_FLD_FILENAME_OTHER(basename, field_name, title, chk, desc)    {#field_name, title, PT_TXTMOD_FILENAME,{chk,basename ## _ ## field_name ## _set_cb,basename ## _ ## field_name ## _tostr_cb},{0,0,0},0,desc,FLDFILL}
#define	UAT_DIRECTORYNAME_CB_DEF(basename, field_name, rec_t)   UAT_CSTRING_CB_DEF(basename,field_name,rec_t)
#define	UAT_FLD_DIRECTORYNAME(basename, field_name, title, desc)    {#field_name, title, PT_TXTMOD_DIRECTORYNAME,{uat_fld_chk_str,basename ## _ ## field_name ## _set_cb,basename ## _ ## field_name ## _tostr_cb},{0,0,0},0,desc,FLDFILL}
#define	UAT_DISPLAY_FILTER_CB_DEF(basename, field_name, rec_t)   UAT_CSTRING_CB_DEF(basename,field_name,rec_t)
#define	UAT_FLD_DISPLAY_FILTER(basename, field_name, title, desc)    {#field_name, title, PT_TXTMOD_DISPLAY_FILTER, {uat_fld_chk_str,basename ## _ ## field_name ## _set_cb,basename ## _ ## field_name ## _tostr_cb},{0,0,0},0,desc,FLDFILL}
#define	UAT_PROTO_FIELD_CB_DEF(basename, field_name, rec_t)   UAT_CSTRING_CB_DEF(basename,field_name,rec_t)
#define	UAT_FLD_PROTO_FIELD(basename, field_name, title, desc)    {#field_name, title, PT_TXTMOD_PROTO_FIELD, {uat_fld_chk_field,basename ## _ ## field_name ## _set_cb,basename ## _ ## field_name ## _tostr_cb},{0,0,0},0,desc,FLDFILL}
#define	UAT_FLD_OID(basename, field_name, title, desc)    {#field_name, title, PT_TXTMOD_STRING,{uat_fld_chk_oid,basename ## _ ## field_name ## _set_cb,basename ## _ ## field_name ## _tostr_cb},{0,0,0},0,desc,FLDFILL}
#define	UAT_LSTRING_CB_DEF(basename, field_name, rec_t, ptr_element, len_element)
#define	UAT_FLD_LSTRING(basename, field_name, title, desc)   {#field_name, title, PT_TXTMOD_STRING,{0,basename ## _ ## field_name ## _set_cb,basename ## _ ## field_name ## _tostr_cb},{0,0,0},0,desc,FLDFILL}
#define	UAT_BUFFER_CB_DEF(basename, field_name, rec_t, ptr_element, len_element)
#define	UAT_FLD_BUFFER(basename, field_name, title, desc)    {#field_name, title, PT_TXTMOD_HEXBYTES,{0,basename ## _ ## field_name ## _set_cb,basename ## _ ## field_name ## _tostr_cb},{0,0,0},0,desc,FLDFILL}
#define	UAT_DEC_CB_DEF(basename, field_name, rec_t)
#define	UAT_FLD_DEC(basename, field_name, title, desc)    {#field_name, title, PT_TXTMOD_STRING,{uat_fld_chk_num_dec,basename ## _ ## field_name ## _set_cb,basename ## _ ## field_name ## _tostr_cb},{0,0,0},0,desc,FLDFILL}
#define	UAT_DEC64_CB_DEF(basename, field_name, rec_t)
#define	UAT_FLD_DEC64(basename, field_name, title, desc)    {#field_name, title, PT_TXTMOD_STRING,{uat_fld_chk_num_dec64,basename ## _ ## field_name ## _set_cb,basename ## _ ## field_name ## _tostr_cb},{0,0,0},0,desc,FLDFILL}
#define	UAT_SIGNED_DEC_CB_DEF(basename, field_name, rec_t)
#define	UAT_FLD_SIGNED_DEC(basename, field_name, title, desc)    {#field_name, title, PT_TXTMOD_STRING,{uat_fld_chk_num_signed_dec,basename ## _ ## field_name ## _set_cb,basename ## _ ## field_name ## _tostr_cb},{0,0,0},0,desc,FLDFILL}
#define	UAT_SIGNED_DEC64_CB_DEF(basename, field_name, rec_t)
#define	UAT_FLD_SIGNED_DEC64(basename, field_name, title, desc)    {#field_name, title, PT_TXTMOD_STRING,{uat_fld_chk_num_signed_dec64,basename ## _ ## field_name ## _set_cb,basename ## _ ## field_name ## _tostr_cb},{0,0,0},0,desc,FLDFILL}
#define	UAT_FLD_NONE(basename, field_name, title, desc)    {#field_name, title, PT_TXTMOD_NONE,{uat_fld_chk_num_dec,basename ## _ ## field_name ## _set_cb,basename ## _ ## field_name ## _tostr_cb},{0,0,0},0,desc,FLDFILL}
#define	UAT_HEX_CB_DEF(basename, field_name, rec_t)
#define	UAT_FLD_HEX(basename, field_name, title, desc)   {#field_name, title, PT_TXTMOD_STRING,{uat_fld_chk_num_hex,basename ## _ ## field_name ## _set_cb,basename ## _ ## field_name ## _tostr_cb},{0,0,0},0,desc,FLDFILL}
#define	UAT_HEX64_CB_DEF(basename, field_name, rec_t)
#define	UAT_FLD_HEX64(basename, field_name, title, desc)   {#field_name, title, PT_TXTMOD_STRING,{uat_fld_chk_num_hex64,basename ## _ ## field_name ## _set_cb,basename ## _ ## field_name ## _tostr_cb},{0,0,0},0,desc,FLDFILL}
#define	UAT_DBL_CB_DEF(basename, field_name, rec_t)
#define	UAT_FLD_DBL(basename, field_name, title, desc)    {#field_name, title, PT_TXTMOD_STRING,{uat_fld_chk_num_dbl,basename ## _ ## field_name ## _set_cb,basename ## _ ## field_name ## _tostr_cb},{0,0,0},0,desc,FLDFILL}
#define	UAT_BOOL_CB_DEF(basename, field_name, rec_t)
#define	UAT_FLD_BOOL(basename, field_name, title, desc)   {#field_name, title, PT_TXTMOD_BOOL,{uat_fld_chk_bool,basename ## _ ## field_name ## _set_cb,basename ## _ ## field_name ## _tostr_cb},{0,0,0},0,desc,FLDFILL}
#define	UAT_VS_DEF(basename, field_name, rec_t, default_t, default_val, default_str)
#define	UAT_VS_CSTRING_DEF(basename, field_name, rec_t, default_val, default_str)
#define	UAT_FLD_VS(basename, field_name, title, enum, desc)    {#field_name, title, PT_TXTMOD_ENUM,{uat_fld_chk_enum,basename ## _ ## field_name ## _set_cb,basename ## _ ## field_name ## _tostr_cb},{&(enum),&(enum),&(enum)},&(enum),desc,FLDFILL}
#define	UAT_COLOR_CB_DEF(basename, field_name, rec_t)
#define	UAT_FLD_COLOR(basename, field_name, title, desc)   {#field_name, title, PT_TXTMOD_COLOR,{uat_fld_chk_color,basename ## _ ## field_name ## _set_cb,basename ## _ ## field_name ## _tostr_cb},{0,0,0},0,desc,FLDFILL}
#define	UAT_DISSECTOR_DEF(basename, field_name, dissector_field, name_field, rec_t)
#define	UAT_FLD_DISSECTOR(basename, field_name, title, desc)    {#field_name, title, PT_TXTMOD_DISSECTOR,{uat_fld_chk_proto,basename ## _ ## field_name ## _set_cb,basename ## _ ## field_name ## _tostr_cb},{0,0,0},0,desc,FLDFILL}
#define	UAT_FLD_DISSECTOR_OTHER(basename, field_name, title, chk, desc)    {#field_name, title, PT_TXTMOD_DISSECTOR,{chk,basename ## _ ## field_name ## _set_cb,basename ## _ ## field_name ## _tostr_cb},{0,0,0},0,desc,FLDFILL}
#define	UAT_RANGE_CB_DEF(basename, field_name, rec_t)
#define	UAT_FLD_RANGE(basename, field_name, title, max, desc)

Typedefs
typedef struct epan_uat	uat_t
typedef void(*	uat_post_update_cb_t) (void)
typedef void *(*	uat_copy_cb_t) (void *dest, const void *source, size_t len)
typedef void(*	uat_free_cb_t) (void *record)
typedef void(*	uat_reset_cb_t) (void)
typedef bool(*	uat_update_cb_t) (void *record, char **error)
typedef bool(*	uat_fld_chk_cb_t) (void *record, const char *ptr, unsigned len, const void *chk_data, const void *fld_data, char **error)
typedef void(*	uat_fld_set_cb_t) (void *record, const char *ptr, unsigned len, const void *set_data, const void *fld_data)
typedef void(*	uat_fld_tostr_cb_t) (void *record, char **out_ptr, unsigned *out_len, const void *tostr_data, const void *fld_data)
typedef enum _uat_text_mode_t	uat_text_mode_t
	Controls how a UAT (User Accessible Table) field is rendered and parsed in both the preferences file and the GUI editor dialog.
typedef struct _uat_field_t	uat_field_t
	Describes a single editable field within a UAT (User Accessible Table).
typedef void(*	uat_cb_t) (void *uat, void *user_data)

Enumerations
enum	_uat_text_mode_t {   PT_TXTMOD_NONE , PT_TXTMOD_STRING , PT_TXTMOD_HEXBYTES , PT_TXTMOD_ENUM ,   PT_TXTMOD_DISSECTOR , PT_TXTMOD_COLOR , PT_TXTMOD_FILENAME , PT_TXTMOD_DIRECTORYNAME ,   PT_TXTMOD_DISPLAY_FILTER , PT_TXTMOD_PROTO_FIELD , PT_TXTMOD_BOOL }
	Controls how a UAT (User Accessible Table) field is rendered and parsed in both the preferences file and the GUI editor dialog.

Functions
WS_DLL_PUBLIC uat_t *	uat_new (const char *name, size_t size, const char *filename, bool from_profile, void *data_ptr, unsigned *num_items_ptr, unsigned flags, const char *help, uat_copy_cb_t copy_cb, uat_update_cb_t update_cb, uat_free_cb_t free_cb, uat_post_update_cb_t post_update_cb, uat_reset_cb_t reset_cb, uat_field_t *flds_array)
WS_DLL_PUBLIC void	uat_destroy (uat_t *uat)
	Free and deregister a single UAT.
void	uat_cleanup (void)
	Cleanup all UATs.
WS_DLL_PUBLIC bool	uat_load (uat_t *uat_in, const char *filename, const char *app_env_var_prefix, char **err)
	Populate a UAT using its file.
WS_DLL_PUBLIC bool	uat_load_str (uat_t *uat_in, const char *entry, char **err)
	Create or update a single UAT entry using a string.
uat_t *	uat_find (char *name)
	Given a UAT name or filename, find its pointer.
WS_DLL_PUBLIC uat_t *	uat_get_table_by_name (const char *name)
	Retrieve a UAT table by its name.
WS_DLL_PUBLIC void	uat_set_default_values (uat_t *uat_in, const char *default_values[])
WS_DLL_PUBLIC bool	uat_fld_chk_str (void *record, const char *ptr, unsigned len, const void *chk_data, const void *fld_data, char **err)
	UAT field validator for generic string values.
WS_DLL_PUBLIC bool	uat_fld_chk_oid (void *record, const char *ptr, unsigned len, const void *chk_data, const void *fld_data, char **err)
	UAT field validator for ASN.1 Object Identifier strings.
WS_DLL_PUBLIC bool	uat_fld_chk_proto (void *record, const char *ptr, unsigned len, const void *chk_data, const void *fld_data, char **err)
	UAT field validator for Wireshark protocol name strings.
WS_DLL_PUBLIC bool	uat_fld_chk_field (void *u1, const char *strptr, unsigned len, const void *u2, const void *u3, char **err)
	Checks if a field name is valid.
WS_DLL_PUBLIC bool	uat_fld_chk_num_dec (void *u1, const char *strptr, unsigned len, const void *u2, const void *u3, char **err)
	Checks if a field value is a valid decimal number.
WS_DLL_PUBLIC bool	uat_fld_chk_num_dec64 (void *u1, const char *strptr, unsigned len, const void *u2, const void *u3, char **err)
	Checks if a field value is a valid decimal 64-bit number.
WS_DLL_PUBLIC bool	uat_fld_chk_num_hex (void *u1, const char *strptr, unsigned len, const void *u2, const void *u3, char **err)
	Checks if a field contains a valid hexadecimal number.
WS_DLL_PUBLIC bool	uat_fld_chk_num_hex64 (void *u1, const char *strptr, unsigned len, const void *u2, const void *u3, char **err)
	Check if a field contains a valid hexadecimal number.
WS_DLL_PUBLIC bool	uat_fld_chk_num_signed_dec (void *u1, const char *strptr, unsigned len, const void *u2, const void *u3, char **err)
	Check if a field contains a signed decimal number.
WS_DLL_PUBLIC bool	uat_fld_chk_num_signed_dec64 (void *u1, const char *strptr, unsigned len, const void *u2, const void *u3, char **err)
	Check if a field value is a signed decimal 64-bit number.
WS_DLL_PUBLIC bool	uat_fld_chk_num_dbl (void *u1, const char *strptr, unsigned len, const void *u2, const void *u3, char **err)
	Check if a field value is a numeric double.
WS_DLL_PUBLIC bool	uat_fld_chk_bool (void *u1, const char *strptr, unsigned len, const void *u2, const void *u3, char **err)
	Check if a field value is a boolean.
WS_DLL_PUBLIC bool	uat_fld_chk_enum (void *u1, const char *strptr, unsigned len, const void *v, const void *u3, char **err)
	Checks if a field value is a valid enum.
WS_DLL_PUBLIC bool	uat_fld_chk_range (void *u1, const char *strptr, unsigned len, const void *u2, const void *u3, char **err)
	Checks if a field value is a range object.
WS_DLL_PUBLIC bool	uat_fld_chk_color (void *u1, const char *strptr, unsigned len, const void *u2, const void *u3, char **err)
	Checks if a color field is valid.
WS_DLL_PUBLIC void	uat_foreach_table (uat_cb_t cb, void *user_data)
	Iterates over all UAT tables and calls a callback function for each.
void	uat_unload_all (void)
	Unloads all UATs that are not loaded from a profile.
uint8_t *	uat_unesc (const char *si, unsigned in_len, unsigned *len_p)
	Converts an ASCII string using C-style escapes (e.g., for unprintable.
char *	uat_undquote (const char *si, unsigned in_len, unsigned *len_p)
	Decode a quoted, C-style escaped ASCII string into a raw byte array.
char *	uat_esc (const uint8_t *buf, unsigned len)
	Encode a raw byte array as a NUL-terminated C-style escaped ASCII string.
char *	uat_unbinstring (const char *si, unsigned in_len, unsigned *len_p)
	Decode an ASCII hex-digit string into a raw byte array.
WS_DLL_PUBLIC bool	uat_fld_chk_str_isprint (void *u1, const char *strptr, unsigned len, const void *u2, const void *u3, char **err)
	Checks if a string contains only printable characters.
WS_DLL_PUBLIC bool	uat_fld_chk_str_isalpha (void *u1, const char *strptr, unsigned len, const void *u2, const void *u3, char **err)
	Checks if a string contains only alphabetic characters.
WS_DLL_PUBLIC bool	uat_fld_chk_str_isalnum (void *u1, const char *strptr, unsigned len, const void *u2, const void *u3, char **err)
	Checks if a string is alphanumeric.
WS_DLL_PUBLIC bool	uat_fld_chk_str_isdigit (void *u1, const char *strptr, unsigned len, const void *u2, const void *u3, char **err)
	Checks if a string contains only digits.
WS_DLL_PUBLIC bool	uat_fld_chk_str_isxdigit (void *u1, const char *strptr, unsigned len, const void *u2, const void *u3, char **err)
	Checks if a string contains only hexadecimal digits.

Detailed Description

User Accessible Tables Maintain an array of user accessible data structures

(c) 2007, Luis E. Garcia Ontanon luis@.nosp@m.onta.nosp@m.non.o.nosp@m.rg

Wireshark - Network traffic analyzer By Gerald Combs geral.nosp@m.d@wi.nosp@m.resha.nosp@m.rk.o.nosp@m.rg Copyright 2001 Gerald Combs

SPDX-License-Identifier: GPL-2.0-or-later

Macro Definition Documentation

UAT_BOOL_CB_DEF

#define UAT_BOOL_CB_DEF	(		basename,
			field_name,
			rec_t
	)

Value:

static void basename ## _ ## field_name ## _set_cb(void* rec, const char* buf, unsigned len, const void* UNUSED_PARAMETER(u1), const void* UNUSED_PARAMETER(u2)) {\
    char* tmp_str = g_strndup(buf,len); \
    if (tmp_str && g_ascii_strcasecmp(tmp_str, "true") == 0) \
        ((rec_t*)rec)->field_name = 1; \
    else \
        ((rec_t*)rec)->field_name = 0; \
    g_free(tmp_str); } \
static void basename ## _ ## field_name ## _tostr_cb(void* rec, char** out_ptr, unsigned* out_len, const void* UNUSED_PARAMETER(u1), const void* UNUSED_PARAMETER(u2)) {\
    *out_ptr = ws_strdup_printf("%s",((rec_t*)rec)->field_name ? "TRUE" : "FALSE"); \
    *out_len = (unsigned)strlen(*out_ptr); }

UAT_BUFFER_CB_DEF

#define UAT_BUFFER_CB_DEF	(		basename,
			field_name,
			rec_t,
			ptr_element,
			len_element
	)

Value:

static void basename ## _ ## field_name ## _set_cb(void* rec, const char* buf, unsigned len, const void* UNUSED_PARAMETER(u1), const void* UNUSED_PARAMETER(u2)) {\
    unsigned char* new_buf = len ? (unsigned char *)g_memdup2(buf,len) : NULL; \
    g_free((((rec_t*)rec)->ptr_element)); \
    (((rec_t*)rec)->ptr_element) = new_buf; \
    (((rec_t*)rec)->len_element) = len; } \
static void basename ## _ ## field_name ## _tostr_cb(void* rec, char** out_ptr, unsigned* out_len, const void* UNUSED_PARAMETER(u1), const void* UNUSED_PARAMETER(u2)) {\
    *out_ptr = ((rec_t*)rec)->ptr_element ? (char*)g_memdup2(((rec_t*)rec)->ptr_element,((rec_t*)rec)->len_element) : g_strdup(""); \
    *out_len = ((rec_t*)rec)->len_element; }

UAT_COLOR_CB_DEF

#define UAT_COLOR_CB_DEF	(		basename,
			field_name,
			rec_t
	)

Value:

static void basename ## _ ## field_name ## _set_cb(void* rec, const char* buf, unsigned len, const void* UNUSED_PARAMETER(u1), const void* UNUSED_PARAMETER(u2)) {\
    if (len < 1) { \
        ((rec_t*)rec)->field_name = 0; \
        return; \
    } \
    char* tmp_str = g_strndup(buf+1,len-1); \
    ((rec_t*)rec)->field_name = (unsigned)strtol(tmp_str,NULL,16); \
    g_free(tmp_str); } \
static void basename ## _ ## field_name ## _tostr_cb(void* rec, char** out_ptr, unsigned* out_len, const void* UNUSED_PARAMETER(u1), const void* UNUSED_PARAMETER(u2)) {\
    *out_ptr = ws_strdup_printf("#%06X",((rec_t*)rec)->field_name); \
    *out_len = (unsigned)strlen(*out_ptr); }

UAT_CSTRING_CB_DEF

#define UAT_CSTRING_CB_DEF	(		basename,
			field_name,
			rec_t
	)

Value:

static void basename ## _ ## field_name ## _set_cb(void* rec, const char* buf, unsigned len, const void* UNUSED_PARAMETER(u1), const void* UNUSED_PARAMETER(u2)) {\
    char* new_buf = g_strndup(buf,len); \
    g_free((((rec_t*)rec)->field_name)); \
    (((rec_t*)rec)->field_name) = new_buf; } \
static void basename ## _ ## field_name ## _tostr_cb(void* rec, char** out_ptr, unsigned* out_len, const void* UNUSED_PARAMETER(u1), const void* UNUSED_PARAMETER(u2)) {\
    if (((rec_t*)rec)->field_name ) { \
        *out_ptr = g_strdup((((rec_t*)rec)->field_name)); \
        *out_len = (unsigned)strlen((((rec_t*)rec)->field_name)); \
    } else { \
        *out_ptr = g_strdup(""); *out_len = 0; \
    } }

UAT_DBL_CB_DEF

#define UAT_DBL_CB_DEF	(		basename,
			field_name,
			rec_t
	)

Value:

static void basename ## _ ## field_name ## _set_cb(void* rec, const char* buf, unsigned len, const void* UNUSED_PARAMETER(u1), const void* UNUSED_PARAMETER(u2)) {\
    char* tmp_str = g_strndup(buf,len); \
    ((rec_t*)rec)->field_name = g_ascii_strtod(tmp_str, NULL); \
    g_free(tmp_str); } \
static void basename ## _ ## field_name ## _tostr_cb(void* rec, char** out_ptr, unsigned* out_len, const void* UNUSED_PARAMETER(u1), const void* UNUSED_PARAMETER(u2)) {\
    char buf[32]; \
    *out_ptr = ws_strdup(dtoa_g_fmt(buf, ((rec_t*)rec)->field_name)); \
    *out_len = (unsigned)strlen(*out_ptr); }

UAT_DEC64_CB_DEF

#define UAT_DEC64_CB_DEF	(		basename,
			field_name,
			rec_t
	)

Value:

static void basename ## _ ## field_name ## _set_cb(void* rec, const char* buf, unsigned len, const void* UNUSED_PARAMETER(u1), const void* UNUSED_PARAMETER(u2)) {\
    char* tmp_str = g_strndup(buf,len); \
    ws_strtou64(tmp_str, NULL, &((rec_t*)rec)->field_name); \
    g_free(tmp_str); } \
static void basename ## _ ## field_name ## _tostr_cb(void* rec, char** out_ptr, unsigned* out_len, const void* UNUSED_PARAMETER(u1), const void* UNUSED_PARAMETER(u2)) {\
    *out_ptr = ws_strdup_printf("%" PRIu64,((rec_t*)rec)->field_name); \
    *out_len = (unsigned)strlen(*out_ptr); }

UAT_DEC_CB_DEF

#define UAT_DEC_CB_DEF	(		basename,
			field_name,
			rec_t
	)

Value:

static void basename ## _ ## field_name ## _set_cb(void* rec, const char* buf, unsigned len, const void* UNUSED_PARAMETER(u1), const void* UNUSED_PARAMETER(u2)) {\
    char* tmp_str = g_strndup(buf,len); \
    ws_strtou32(tmp_str, NULL, &((rec_t*)rec)->field_name); \
    g_free(tmp_str); } \
static void basename ## _ ## field_name ## _tostr_cb(void* rec, char** out_ptr, unsigned* out_len, const void* UNUSED_PARAMETER(u1), const void* UNUSED_PARAMETER(u2)) {\
    *out_ptr = ws_strdup_printf("%u",((rec_t*)rec)->field_name); \
    *out_len = (unsigned)strlen(*out_ptr); }

UAT_DISSECTOR_DEF

#define UAT_DISSECTOR_DEF	(		basename,
			field_name,
			dissector_field,
			name_field,
			rec_t
	)

Value:

static void basename ## _ ## field_name ## _set_cb(void* rec, const char* buf, unsigned len, const void* UNUSED_PARAMETER(u1), const void* UNUSED_PARAMETER(u2)) {\
    if (len) { \
        ((rec_t*)rec)->name_field = g_strndup(buf, len); \
        g_strstrip(((rec_t*)rec)->name_field); \
        ((rec_t*)rec)->dissector_field = find_dissector(((rec_t*)rec)->name_field); \
    } else { \
        ((rec_t*)rec)->dissector_field = find_dissector("data"); \
        ((rec_t*)rec)->name_field = NULL; \
    } } \
static void basename ## _ ## field_name ## _tostr_cb(void* rec, char** out_ptr, unsigned* out_len, const void* UNUSED_PARAMETER(u1), const void* UNUSED_PARAMETER(u2)) {\
    if ( ((rec_t*)rec)->name_field ) { \
        *out_ptr = g_strdup((((rec_t*)rec)->name_field)); \
        *out_len = (unsigned)strlen(*out_ptr); \
    } else { \
        *out_ptr = g_strdup(""); *out_len = 0; \
    } }

UAT_FLD_RANGE

#define UAT_FLD_RANGE	(		basename,
			field_name,
			title,
			max,
			desc
	)

Value:

    {#field_name, title, PT_TXTMOD_STRING,{uat_fld_chk_range,basename ## _ ## field_name ## _set_cb,basename ## _ ## field_name ## _tostr_cb},\
      {0,0,0},GUINT_TO_POINTER(max),desc,FLDFILL}

UAT_HEX64_CB_DEF

#define UAT_HEX64_CB_DEF	(		basename,
			field_name,
			rec_t
	)

Value:

static void basename ## _ ## field_name ## _set_cb(void* rec, const char* buf, unsigned len, const void* UNUSED_PARAMETER(u1), const void* UNUSED_PARAMETER(u2)) {\
    char* tmp_str = g_strndup(buf,len); \
    ws_hexstrtou64(tmp_str, NULL, &((rec_t*)rec)->field_name); \
    g_free(tmp_str); } \
static void basename ## _ ## field_name ## _tostr_cb(void* rec, char** out_ptr, unsigned* out_len, const void* UNUSED_PARAMETER(u1), const void* UNUSED_PARAMETER(u2)) {\
    *out_ptr = ws_strdup_printf("%" PRIx64,((rec_t*)rec)->field_name); \
    *out_len = (unsigned)strlen(*out_ptr); }

UAT_HEX_CB_DEF

#define UAT_HEX_CB_DEF	(		basename,
			field_name,
			rec_t
	)

Value:

static void basename ## _ ## field_name ## _set_cb(void* rec, const char* buf, unsigned len, const void* UNUSED_PARAMETER(u1), const void* UNUSED_PARAMETER(u2)) {\
    char* tmp_str = g_strndup(buf,len); \
    ws_hexstrtou32(tmp_str, NULL, &((rec_t*)rec)->field_name); \
    g_free(tmp_str); } \
static void basename ## _ ## field_name ## _tostr_cb(void* rec, char** out_ptr, unsigned* out_len, const void* UNUSED_PARAMETER(u1), const void* UNUSED_PARAMETER(u2)) {\
    *out_ptr = ws_strdup_printf("%x",((rec_t*)rec)->field_name); \
    *out_len = (unsigned)strlen(*out_ptr); }

UAT_LSTRING_CB_DEF

#define UAT_LSTRING_CB_DEF	(		basename,
			field_name,
			rec_t,
			ptr_element,
			len_element
	)

Value:

static void basename ## _ ## field_name ## _set_cb(void* rec, const char* buf, unsigned len, const void* UNUSED_PARAMETER(u1), const void* UNUSED_PARAMETER(u2)) {\
    uint8_t* new_val = uat_unesc(buf,len,&(((rec_t*)rec)->len_element)); \
    g_free((((rec_t*)rec)->ptr_element)); \
    (((rec_t*)rec)->ptr_element) = new_val; } \
static void basename ## _ ## field_name ## _tostr_cb(void* rec, char** out_ptr, unsigned* out_len, const void* UNUSED_PARAMETER(u1), const void* UNUSED_PARAMETER(u2)) {\
    if (((rec_t*)rec)->ptr_element ) { \
        *out_ptr = uat_esc(((rec_t*)rec)->ptr_element, (((rec_t*)rec)->len_element)); \
        *out_len = (unsigned)strlen(*out_ptr); \
    } else { \
        *out_ptr = g_strdup(""); \
        *out_len = 0; \
    } }

UAT_RANGE_CB_DEF

#define UAT_RANGE_CB_DEF	(		basename,
			field_name,
			rec_t
	)

Value:

static void basename ## _ ## field_name ## _set_cb(void* rec, const char* buf, unsigned len, const void* UNUSED_PARAMETER(u1), const void* u2) {\
    char* rng = g_strndup(buf,len);\
        range_convert_str(NULL, &(((rec_t*)rec)->field_name), rng,GPOINTER_TO_UINT(u2)); \
        g_free(rng); \
    } \
static void basename ## _ ## field_name ## _tostr_cb(void* rec, char** out_ptr, unsigned* out_len, const void* UNUSED_PARAMETER(u1), const void* UNUSED_PARAMETER(u2)) {\
    if ( ((rec_t*)rec)->field_name ) { \
        *out_ptr = range_convert_range(NULL, ((rec_t*)rec)->field_name); \
        *out_len = (unsigned)strlen(*out_ptr); \
    } else { \
        *out_ptr = g_strdup(""); *out_len = 0; \
    } }

UAT_SIGNED_DEC64_CB_DEF

#define UAT_SIGNED_DEC64_CB_DEF	(		basename,
			field_name,
			rec_t
	)

Value:

static void basename ## _ ## field_name ## _set_cb(void* rec, const char* buf, unsigned len, const void* UNUSED_PARAMETER(u1), const void* UNUSED_PARAMETER(u2)) {\
    char* tmp_str = g_strndup(buf,len); \
    ws_strtoi64(tmp_str, NULL, &((rec_t*)rec)->field_name); \
    g_free(tmp_str); } \
static void basename ## _ ## field_name ## _tostr_cb(void* rec, char** out_ptr, unsigned* out_len, const void* UNUSED_PARAMETER(u1), const void* UNUSED_PARAMETER(u2)) {\
    *out_ptr = ws_strdup_printf("%" PRId64,((rec_t*)rec)->field_name); \
    *out_len = (unsigned)strlen(*out_ptr); }

UAT_SIGNED_DEC_CB_DEF

#define UAT_SIGNED_DEC_CB_DEF	(		basename,
			field_name,
			rec_t
	)

Value:

static void basename ## _ ## field_name ## _set_cb(void* rec, const char* buf, unsigned len, const void* UNUSED_PARAMETER(u1), const void* UNUSED_PARAMETER(u2)) {\
    char* tmp_str = g_strndup(buf,len); \
    ws_strtoi32(tmp_str, NULL, &((rec_t*)rec)->field_name); \
    g_free(tmp_str); } \
static void basename ## _ ## field_name ## _tostr_cb(void* rec, char** out_ptr, unsigned* out_len, const void* UNUSED_PARAMETER(u1), const void* UNUSED_PARAMETER(u2)) {\
    *out_ptr = ws_strdup_printf("%d",((rec_t*)rec)->field_name); \
    *out_len = (unsigned)strlen(*out_ptr); }

UAT_VS_CSTRING_DEF

#define UAT_VS_CSTRING_DEF	(		basename,
			field_name,
			rec_t,
			default_val,
			default_str
	)

Value:

static void basename ## _ ## field_name ## _set_cb(void* rec, const char* buf, unsigned len, const void* vs, const void* UNUSED_PARAMETER(u2)) {\
    unsigned i; \
    char* str = g_strndup(buf,len); \
    const char* cstr; \
    ((rec_t*)rec)->field_name = default_val; \
    for(i=0; ( cstr = ((const value_string*)vs)[i].strptr ) ;i++) { \
        if (g_str_equal(cstr,str)) { \
          ((rec_t*)rec)->field_name = g_strdup(((const value_string*)vs)[i].strptr); \
          g_free(str); \
          return; \
        } \
    } \
    g_free(str);} \
static void basename ## _ ## field_name ## _tostr_cb(void* rec, char** out_ptr, unsigned* out_len, const void* UNUSED_PARAMETER(vs), const void* UNUSED_PARAMETER(u2)) {\
    if (((rec_t*)rec)->field_name ) { \
        *out_ptr = g_strdup((((rec_t*)rec)->field_name)); \
        *out_len = (unsigned)strlen((((rec_t*)rec)->field_name)); \
    } else { \
        *out_ptr = g_strdup(""); *out_len = 0; } }

UAT_VS_DEF

#define UAT_VS_DEF	(		basename,
			field_name,
			rec_t,
			default_t,
			default_val,
			default_str
	)

Value:

static void basename ## _ ## field_name ## _set_cb(void* rec, const char* buf, unsigned len, const void* vs, const void* UNUSED_PARAMETER(u2)) {\
    unsigned i; \
    char* str = g_strndup(buf,len); \
    const char* cstr; \
    ((rec_t*)rec)->field_name = default_val; \
    for(i=0; ( cstr = ((const value_string*)vs)[i].strptr ) ;i++) { \
        if (g_str_equal(cstr,str)) { \
            ((rec_t*)rec)->field_name = (default_t)((const value_string*)vs)[i].value; \
            g_free(str); \
            return; \
        } \
    } \
    g_free(str); } \
static void basename ## _ ## field_name ## _tostr_cb(void* rec, char** out_ptr, unsigned* out_len, const void* vs, const void* UNUSED_PARAMETER(u2)) {\
    unsigned i; \
    for(i=0;((const value_string*)vs)[i].strptr;i++) { \
        if ( ((const value_string*)vs)[i].value == ((rec_t*)rec)->field_name ) { \
            *out_ptr = g_strdup(((const value_string*)vs)[i].strptr); \
            *out_len = (unsigned)strlen(*out_ptr); \
            return; \
        } \
    } \
    *out_ptr = g_strdup(default_str); \
    *out_len = (unsigned)strlen(default_str); }

Typedef Documentation

uat_copy_cb_t

typedef void *(* uat_copy_cb_t) (void *dest, const void *source, size_t len)

Copy CB copy(dest, source, len)

Used to duplicate the contents of one record to another. Optional, memcpy will be used if not given.

uat_free_cb_t

typedef void(* uat_free_cb_t) (void *record)

Free CB free(record)

Destroy the contents of a record, possibly freeing some fields. Do not free the container itself, this memory is owned by the UAT core. Optional if the record contains no pointers that need to be freed.

uat_reset_cb_t

typedef void(* uat_reset_cb_t) (void)

Reset DB

Used to free resources associated with a UAT loaded from file (e.g. post_update_cb) Optional.

uat_update_cb_t

typedef bool(* uat_update_cb_t) (void *record, char **error)

Update CB update(record,&error)

Validates the contents of the record contents, to be called after any record fields had been updated (either from file or after modifications in the GUI).

Optional, the record will be considered valid if the callback is omitted. It must return true if the contents are considered valid and false otherwise in which case the failure reason is set in 'error'. The error string will be freed by g_free.

XXX: This should only validate the record. Any changes to the record made here will not be persistent if the UAT is saved again, unless the same changes are also done to a new record created by the copy cb, e.g. by having the the copy callback call this. It should probably be made into a const void* to make that clear.

Function Documentation

uat_destroy()

WS_DLL_PUBLIC void uat_destroy

(

uat_t *

uat

)

Free and deregister a single UAT.

Parameters

uat	The UAT to be destroyed.

uat_esc()

char * uat_esc	(	const uint8_t *	buf,
		unsigned	len
	)

Encode a raw byte array as a NUL-terminated C-style escaped ASCII string.

Converts a "stringlike" array of bytes into a null-terminated ASCII string using C-style escapes. The inverse of uat_unesc.

Parameters

buf	The raw byte array to encode.
len	Number of bytes in buf.

Returns

A newly allocated NUL-terminated escaped ASCII string. The caller must free it with g_free().

uat_find()

uat_t * uat_find

(

char *

name

)

Given a UAT name or filename, find its pointer.

Parameters

name	The name or filename of the uat

Returns

A pointer to the uat on success, NULL on failure.

uat_fld_chk_bool()

WS_DLL_PUBLIC bool uat_fld_chk_bool	(	void *	u1,
		const char *	strptr,
		unsigned	len,
		const void *	u2,
		const void *	u3,
		char **	err
	)

Check if a field value is a boolean.

Parameters

u1	User data pointer, not used in this function.
strptr	String to check.
len	Length of the string being checked.
u2	User data pointer, not used in this function.
u3	User data pointer, not used in this function.
err	Error message buffer if an error occurs.

Returns

true if the field value is valid, false otherwise.

uat_fld_chk_color()

WS_DLL_PUBLIC bool uat_fld_chk_color	(	void *	u1,
		const char *	strptr,
		unsigned	len,
		const void *	u2,
		const void *	u3,
		char **	err
	)

Checks if a color field is valid.

Parameters

u1	User data pointer, not used in this function.
strptr	String to check.
len	Length of the string being checked.
u2	User data pointer, not used in this function.
u3	User data pointer, not used in this function.
err	Error message buffer if an error occurs.

Returns

true if the field value is valid, false otherwise.

uat_fld_chk_enum()

WS_DLL_PUBLIC bool uat_fld_chk_enum	(	void *	u1,
		const char *	strptr,
		unsigned	len,
		const void *	v,
		const void *	u3,
		char **	err
	)

Checks if a field value is a valid enum.

Parameters

u1	User data pointer, not used in this function.
strptr	String to check.
len	Length of the string being checked.
v	Value string.
u3	User data pointer, not used in this function.
err	Error message buffer if an error occurs.

Returns

true if the field value is valid, false otherwise.

uat_fld_chk_field()

WS_DLL_PUBLIC bool uat_fld_chk_field	(	void *	u1,
		const char *	strptr,
		unsigned	len,
		const void *	u2,
		const void *	u3,
		char **	err
	)

Checks if a field name is valid.

Parameters

u1	User data pointer, not used in this function.
strptr	String to check.
len	Length of the string being checked.
u2	User data pointer, not used in this function.
u3	User data pointer, not used in this function.
err	Error message buffer if an error occurs.

Returns

true if the field value is valid, false otherwise.

uat_fld_chk_num_dbl()

WS_DLL_PUBLIC bool uat_fld_chk_num_dbl	(	void *	u1,
		const char *	strptr,
		unsigned	len,
		const void *	u2,
		const void *	u3,
		char **	err
	)

Check if a field value is a numeric double.

Parameters

u1	User data pointer, not used in this function.
strptr	String to check.
len	Length of the string being checked.
u2	User data pointer, not used in this function.
u3	User data pointer, not used in this function.
err	Error message buffer if an error occurs.

Returns

true if the field value is valid, false otherwise.

uat_fld_chk_num_dec()

WS_DLL_PUBLIC bool uat_fld_chk_num_dec	(	void *	u1,
		const char *	strptr,
		unsigned	len,
		const void *	u2,
		const void *	u3,
		char **	err
	)

Checks if a field value is a valid decimal number.

Parameters

u1	User data pointer, not used in this function.
strptr	String to check.
len	Length of the string being checked.
u2	User data pointer, not used in this function.
u3	User data pointer, not used in this function.
err	Error message buffer if an error occurs.

Returns

true if the field value is valid, false otherwise.

uat_fld_chk_num_dec64()

WS_DLL_PUBLIC bool uat_fld_chk_num_dec64	(	void *	u1,
		const char *	strptr,
		unsigned	len,
		const void *	u2,
		const void *	u3,
		char **	err
	)

Checks if a field value is a valid decimal 64-bit number.

Parameters

u1	User data pointer, not used in this function.
strptr	String to check.
len	Length of the string being checked.
u2	User data pointer, not used in this function.
u3	User data pointer, not used in this function.
err	Error message buffer if an error occurs.

Returns

true if the field value is valid, false otherwise.

uat_fld_chk_num_hex()

WS_DLL_PUBLIC bool uat_fld_chk_num_hex	(	void *	u1,
		const char *	strptr,
		unsigned	len,
		const void *	u2,
		const void *	u3,
		char **	err
	)

Checks if a field contains a valid hexadecimal number.

Parameters

u1	User data pointer, not used in this function.
strptr	String to check.
len	Length of the string being checked.
u2	User data pointer, not used in this function.
u3	User data pointer, not used in this function.
err	Error message buffer if an error occurs.

Returns

true if the field value is valid, false otherwise.

uat_fld_chk_num_hex64()

WS_DLL_PUBLIC bool uat_fld_chk_num_hex64	(	void *	u1,
		const char *	strptr,
		unsigned	len,
		const void *	u2,
		const void *	u3,
		char **	err
	)

Check if a field contains a valid hexadecimal number.

Parameters

u1	User data pointer, not used in this function.
strptr	String to check.
len	Length of the string being checked.
u2	User data pointer, not used in this function.
u3	User data pointer, not used in this function.
err	Error message buffer if an error occurs.

Returns

true if the field value is valid, false otherwise.

uat_fld_chk_num_signed_dec()

WS_DLL_PUBLIC bool uat_fld_chk_num_signed_dec	(	void *	u1,
		const char *	strptr,
		unsigned	len,
		const void *	u2,
		const void *	u3,
		char **	err
	)

Check if a field contains a signed decimal number.

Parameters

u1	User data pointer, not used in this function.
strptr	String to check.
len	Length of the string being checked.
u2	User data pointer, not used in this function.
u3	User data pointer, not used in this function.
err	Error message buffer if an error occurs.

Returns

true if the field value is valid, false otherwise.

uat_fld_chk_num_signed_dec64()

WS_DLL_PUBLIC bool uat_fld_chk_num_signed_dec64	(	void *	u1,
		const char *	strptr,
		unsigned	len,
		const void *	u2,
		const void *	u3,
		char **	err
	)

Check if a field value is a signed decimal 64-bit number.

Parameters

u1	User data pointer, not used in this function.
strptr	String to check.
len	Length of the string being checked.
u2	User data pointer, not used in this function.
u3	User data pointer, not used in this function.
err	Error message buffer if an error occurs.

Returns

true if the field value is valid, false otherwise.

uat_fld_chk_oid()

WS_DLL_PUBLIC bool uat_fld_chk_oid	(	void *	record,
		const char *	ptr,
		unsigned	len,
		const void *	chk_data,
		const void *	fld_data,
		char **	err
	)

UAT field validator for ASN.1 Object Identifier strings.

Parameters

record	Pointer to the UAT record being validated (unused).
ptr	The NUL-terminated OID string to validate.
len	Length of ptr in bytes, not including the terminator.
chk_data	Field-level checker data supplied at UAT field registration time (unused).
fld_data	Record-level field data (unused).
err	On failure, receives a newly allocated error string describing the OID syntax violation. Set to NULL on success.

Returns

true if ptr is a valid dotted-decimal OID; false otherwise.

uat_fld_chk_proto()

WS_DLL_PUBLIC bool uat_fld_chk_proto	(	void *	record,
		const char *	ptr,
		unsigned	len,
		const void *	chk_data,
		const void *	fld_data,
		char **	err
	)

UAT field validator for Wireshark protocol name strings.

Parameters

record	Pointer to the UAT record being validated (unused).
ptr	The NUL-terminated protocol short name to validate (e.g. "http", "tls").
len	Length of ptr in bytes, not including the terminator.
chk_data	Field-level checker data supplied at UAT field registration time (unused).
fld_data	Record-level field data (unused).
err	On failure, receives a newly allocated error string stating that the protocol is unknown. Set to NULL on success.

Returns

true if ptr names a registered protocol; false otherwise.

uat_fld_chk_range()

WS_DLL_PUBLIC bool uat_fld_chk_range	(	void *	u1,
		const char *	strptr,
		unsigned	len,
		const void *	u2,
		const void *	u3,
		char **	err
	)

Checks if a field value is a range object.

Parameters

u1	User data pointer, not used in this function.
strptr	String to check.
len	Length of the string being checked.
u2	User data pointer, not used in this function.
u3	User data pointer, not used in this function.
err	Error message buffer if an error occurs.

Returns

true if the field value is valid, false otherwise.

uat_fld_chk_str()

WS_DLL_PUBLIC bool uat_fld_chk_str	(	void *	record,
		const char *	ptr,
		unsigned	len,
		const void *	chk_data,
		const void *	fld_data,
		char **	err
	)

UAT field validator for generic string values.

Parameters

record	Pointer to the UAT record being validated (unused).
ptr	The NUL-terminated string value to validate.
len	Length of ptr in bytes, not including the terminator.
chk_data	Field-level checker data supplied at UAT field registration time (unused).
fld_data	Record-level field data (unused).
err	On failure, receives a newly allocated human-readable error string that the UAT framework will display and then g_free(). Set to NULL on success.

Returns

true if the value is acceptable; false if validation failed and *err has been set.

uat_fld_chk_str_isalnum()

WS_DLL_PUBLIC bool uat_fld_chk_str_isalnum	(	void *	u1,
		const char *	strptr,
		unsigned	len,
		const void *	u2,
		const void *	u3,
		char **	err
	)

Checks if a string is alphanumeric.

Parameters

u1	User data pointer, not used in this function.
strptr	String to check.
len	Length of the string being checked.
u2	User data pointer, not used in this function.
u3	User data pointer, not used in this function.
err	Error message buffer if an error occurs.

Returns

true if the field value is valid, false otherwise.

uat_fld_chk_str_isalpha()

WS_DLL_PUBLIC bool uat_fld_chk_str_isalpha	(	void *	u1,
		const char *	strptr,
		unsigned	len,
		const void *	u2,
		const void *	u3,
		char **	err
	)

Checks if a string contains only alphabetic characters.

Parameters

u1	User data pointer, not used in this function.
strptr	String to check.
len	Length of the string being checked.
u2	User data pointer, not used in this function.
u3	User data pointer, not used in this function.
err	Error message buffer if an error occurs.

Returns

true if the field value is valid, false otherwise.

uat_fld_chk_str_isdigit()

WS_DLL_PUBLIC bool uat_fld_chk_str_isdigit	(	void *	u1,
		const char *	strptr,
		unsigned	len,
		const void *	u2,
		const void *	u3,
		char **	err
	)

Checks if a string contains only digits.

Parameters

u1	User data pointer, not used in this function.
strptr	String to check.
len	Length of the string being checked.
u2	User data pointer, not used in this function.
u3	User data pointer, not used in this function.
err	Error message buffer if an error occurs.

Returns

true if the field value is valid, false otherwise.

uat_fld_chk_str_isprint()

WS_DLL_PUBLIC bool uat_fld_chk_str_isprint	(	void *	u1,
		const char *	strptr,
		unsigned	len,
		const void *	u2,
		const void *	u3,
		char **	err
	)

Checks if a string contains only printable characters.

Parameters

u1	User data pointer, not used in this function.
strptr	String to check.
len	Length of the string being checked.
u2	User data pointer, not used in this function.
u3	User data pointer, not used in this function.
err	Error message buffer if an error occurs.

Returns

true if the field value is valid, false otherwise.

uat_fld_chk_str_isxdigit()

WS_DLL_PUBLIC bool uat_fld_chk_str_isxdigit	(	void *	u1,
		const char *	strptr,
		unsigned	len,
		const void *	u2,
		const void *	u3,
		char **	err
	)

Checks if a string contains only hexadecimal digits.

Parameters

u1	User data pointer, not used in this function.
strptr	String to check.
len	Length of the string being checked.
u2	User data pointer, not used in this function.
u3	User data pointer, not used in this function.
err	Error message buffer if an error occurs.

Returns

true if the field value is valid, false otherwise.

uat_foreach_table()

WS_DLL_PUBLIC void uat_foreach_table	(	uat_cb_t	cb,
		void *	user_data
	)

Iterates over all UAT tables and calls a callback function for each.

Parameters

cb	Callback function to be called for each UAT table.
user_data	User data to be passed to the callback function.

uat_get_table_by_name()

WS_DLL_PUBLIC uat_t * uat_get_table_by_name

(

const char *

name

)

Retrieve a UAT table by its name.

Parameters

name	The name of the UAT table to retrieve. Must not be NULL.

Returns

Pointer to the UAT table if found, otherwise NULL.

uat_load()

WS_DLL_PUBLIC bool uat_load	(	uat_t *	uat_in,
		const char *	filename,
		const char *	app_env_var_prefix,
		char **	err
	)

Populate a UAT using its file.

Parameters

uat_in	Pointer to a uat. Must not be NULL.
filename	Filename to load, NULL to fetch from current profile.
app_env_var_prefix	The prefix for the application environment variable used to get the personal config directory.
err	Upon failure, points to an error string.

Returns

true on success, false on failure.

uat_load_str()

WS_DLL_PUBLIC bool uat_load_str	(	uat_t *	uat_in,
		const char *	entry,
		char **	err
	)

Create or update a single UAT entry using a string.

Parameters

uat_in	Pointer to a uat. Must not be NULL.
entry	The string representation of the entry. Format must match what's written to the uat's output file.
err	Upon failure, points to an error string.

Returns

true on success, false on failure.

uat_new()

WS_DLL_PUBLIC uat_t * uat_new	(	const char *	name,
		size_t	size,
		const char *	filename,
		bool	from_profile,
		void *	data_ptr,
		unsigned *	num_items_ptr,
		unsigned	flags,
		const char *	help,
		uat_copy_cb_t	copy_cb,
		uat_update_cb_t	update_cb,
		uat_free_cb_t	free_cb,
		uat_post_update_cb_t	post_update_cb,
		uat_reset_cb_t	reset_cb,
		uat_field_t *	flds_array
	)

Create a new UAT.

Parameters

name	The name of the table
size	The size of the structure
filename	The filename to be used (either in userdir or datadir)
from_profile	true if profile directory to be used
data_ptr	Although a void*, this is really a pointer to a null terminated array of pointers to the data
num_items_ptr	A pointer with number of items
flags	flags indicating what this UAT affects
help	A pointer to the name of a Users Guide section
copy_cb	A function that copies the data in the struct
update_cb	Will be called when a record is updated
free_cb	Will be called to destroy a struct in the dataset
post_update_cb	Will be called once the user clicks the Apply or OK button
reset_cb	Will be called to destroy internal data
flds_array	A pointer to an array of uat_field_t structs

Returns

A freshly-allocated and populated uat_t struct.

uat_set_default_values()

WS_DLL_PUBLIC void uat_set_default_values	(	uat_t *	uat_in,
		const char *	default_values[]
	)

Provide default field values for a UAT.

This can be used to provide forward compatibility when fields are added to a UAT.

Parameters

uat_in	Pointer to a uat. Must not be NULL.
default_values	An array of strings with default values. Must be the same length as flds_array. Individual elements can be NULL, and can be used to distinguish between mandatory and optional fields, e.g. { NULL, NULL, NULL, "default value (optional)" }

Todo:

Use this to provide default values for empty tables.

uat_unbinstring()

char * uat_unbinstring	(	const char *	si,
		unsigned	in_len,
		unsigned *	len_p
	)

Decode an ASCII hex-digit string into a raw byte array.

Converts a ASCII hexstring into an array of bytes. Used to convert the PT_TXTMOD_HEXBYTES format. TODO - This should probably return a uint8_t* as well.

Parameters

si	The ASCII hex-digit input string.
in_len	Length of si in bytes.
len_p	Receives the number of decoded bytes in the returned array.

Returns

A newly allocated byte array of *len_p bytes, or NULL if si contains non-hex characters or an odd number of digits. The caller must free it with g_free().

uat_undquote()

char * uat_undquote	(	const char *	si,
		unsigned	in_len,
		unsigned *	len_p
	)

Decode a quoted, C-style escaped ASCII string into a raw byte array.

The same as uat_unesc, but removing the first and last byte. The assumption is that the first and last byte are quote characters. When writing the PT_TEXTMOD_STRING format to file, the escaped string is enclosed in quotes; this function undoes that.

TODO - This should probably return a uint8_t* as well, but requires changing types (or casting pointers) in several other files to do so.

Parameters

si	The quoted, escaped ASCII input string (including surrounding quote characters).
in_len	Length of si in bytes, including the quote characters.
len_p	Receives the length of the decoded byte array in bytes.

Returns

A newly allocated byte array of *len_p bytes. The caller must free it with g_free().

uat_unesc()

uint8_t * uat_unesc	(	const char *	si,
		unsigned	in_len,
		unsigned *	len_p
	)

Converts an ASCII string using C-style escapes (e.g., for unprintable.

Converts an ASCII string using C-style escapes (e.g., for unprintable characters) into a "stringlike" array of bytes that may include internal NUL bytes and other unprintable characters. This is the PT_TEXTMOD_STRING format.

Parameters

si	The escaped ASCII input string.
in_len	Length of si in bytes, not including any NUL terminator.
len_p	Receives the length of the returned byte array in bytes.

Returns

A newly allocated byte array of *len_p bytes. The caller must free it with g_free().

uat_unload_all()

void uat_unload_all

(

void

)

Unloads all UATs that are not loaded from a profile.

This function iterates through all UATs and unloads those that are not marked as being loaded from a profile.