6 * User Accessible Tables
7 * Mantain an array of user accessible data strucures
9 * (c) 2007, Luis E. Garcia Ontanon <luis.ontanon@gmail.com>
11 * Wireshark - Network traffic analyzer
12 * By Gerald Combs <gerald@wireshark.org>
13 * Copyright 2001 Gerald Combs
15 * This program is free software; you can redistribute it and/or
16 * modify it under the terms of the GNU General Public License
17 * as published by the Free Software Foundation; either version 2
18 * of the License, or (at your option) any later version.
20 * This program is distributed in the hope that it will be useful,
21 * but WITHOUT ANY WARRANTY; without even the implied warranty of
22 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
23 * GNU General Public License for more details.
25 * You should have received a copy of the GNU General Public License
26 * along with this program; if not, write to the Free Software
27 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
34 * uat mantains a dynamically allocated table accessible to the user
35 * via a file and/or gui tables.
37 * the file is located either in userdir(when first read or when writen) or
38 * in datadir for defaults (read only , it will be always written to userdir).
40 * the behaviour of the table is controlled by a series of callbacks
41 * the caller must provide.
43 * BEWARE that the user can change an uat at (almost) any time,
44 * That is pointers to records in an uat are valid only during the call
45 * to the function that obtains them (do not store them).
47 * UATs are meant for short tables of user data (passwords and such) there's
48 * no quick access, you must iterate through them each time to fetch the record
49 * you are looking for. Use uat_dup() or uat_se_dup() if necessary.
51 * Only users via gui or editing the file can add/remove records your code cannot.
54 /* obscure data type to handle an uat */
55 typedef struct _uat_t uat_t;
56 /********************************************
58 * these instruct uat on how to deal with user info and data in records
59 ********************************************/
62 * Callbacks for the entire table (these deal with entire records)
67 * used to copy a record
68 * optional, memcpy will be used if not given
71 typedef void* (*uat_copy_cb_t)(void*, const void*, unsigned);
77 * destroy a record's child data
78 * (do not free the container, it will be handled by uat)
79 * it is optional, no child data will be freed if no present
82 typedef void (*uat_free_cb_t)(void*);
87 * to be called after all record fields has been updated
88 * optional, record will be updated always if not given
89 * update(record,&error)
91 typedef void (*uat_update_cb_t)(void* , const char** );
95 * Callbacks for single fields (these deal with single values)
96 * the caller should provide one of these for every field!
100 * given an input string (ptr, len) checks if the value is OK for a field in the record.
101 * it will return TRUE if OK or else
102 * it will return FALSE and may set *error to inform the user on what's
103 * wrong with the given input
104 * optional, if not given any input is considered OK and the set cb will be called
105 * chk(record, ptr, len, chk_data, fld_data, &error)
107 typedef gboolean (*uat_fld_chk_cb_t)(void*, const char*, unsigned, void*, void*, const char**);
112 * given an input string (ptr, len) sets the value of a field in the record,
113 * it will return TRUE if OK or else
114 * it will return FALSE and may set *error to inform the user on what's
115 * wrong with the given input
117 * set(record, ptr, len, set_data, fld_data)
119 typedef void (*uat_fld_set_cb_t)(void*, const char*, unsigned, void*, void*);
122 * given a record returns a string representation of the field
124 * tostr(record, &out_ptr, &out_len, tostr_data, fld_data)
126 typedef void (*uat_fld_tostr_cb_t)(void*, const char**, unsigned*, void*, void*);
131 * used for file and dialog representation of fileds in columns,
132 * when the file is read it modifies the way the value is passed back to the fld_set_cb
133 * (see definition bellow for description)
136 typedef enum _uat_text_mode_t {
144 ,"\x20\x00\x30", as " \00",3
148 ,"\x20\x30\x00\x20", for " 0\0 ",4
152 accepts \x?? and other escapes
153 gets "",0 on empty string
159 ,A1b2C3d4, as "\001\002\003\004",4
163 ,a1b2c3d4, on "\001\002\003\004",4
165 "a1b2c3d4" as "\001\002\003\004",4
166 "a1 b2:c3d4" as "\001\002\003\004",4
179 typedef struct _uat_field_t {
181 uat_text_mode_t mode;
184 uat_fld_chk_cb_t chk;
185 uat_fld_set_cb_t set;
186 uat_fld_tostr_cb_t tostr;
198 struct _fld_data_t* priv;
202 #define UAT_END_FIELDS {0,PT_TXTMOD_NONE,{0,0,0},{0,0,0},0,0,FLDFILL}
205 #define UAT_CAT_GENERAL "General"
206 #define UAT_CAT_PORTS "Port Assignments"
207 #define UAT_CAT_CRYPTO "Decryption"
208 #define UAT_CAT_FFMT "File Formats"
215 * name: the name of the table
217 * data_ptr: a pointer to a null terminated array of pointers to the data
219 * default_data: a pinter to a struct containing default values
221 * size: the size of the structure
223 * filename: the filename to be used (either in userdir or datadir)
225 * copy_cb: a function that copies the data in the struct
227 * update_cb: will be called when a record is updated
229 * free_cb: will be called to destroy a struct in the dataset
233 uat_t* uat_new(const char* name,
235 const char* filename,
238 const char* category,
240 uat_copy_cb_t copy_cb,
241 uat_update_cb_t update_cb,
242 uat_free_cb_t free_cb,
243 uat_field_t* flds_array);
245 gboolean uat_load(uat_t* uat_in, char** err);
250 * make a reliable copy of an uat for internal use,
251 * so that pointers to records can be kept through calls.
252 * return NULL on zero len.
254 void* uat_dup(uat_t*, guint* len_p); /* to be freed */
255 void* uat_se_dup(uat_t*, guint* len_p);
258 * Some common uat_fld_chk_cbs
260 gboolean uat_fld_chk_str(void*, const char*, unsigned, void*,void*, const char** err);
261 gboolean uat_fld_chk_proto(void*, const char*, unsigned, void*,void*, const char** err);
262 gboolean uat_fld_chk_num_dec(void*, const char*, unsigned, void*, void*, const char** err);
263 gboolean uat_fld_chk_num_hex(void*, const char*, unsigned, void*, void*, const char** err);
264 gboolean uat_fld_chk_enum(void*, const char*, unsigned, void*, void*, const char**);
265 gboolean uat_fld_chk_range(void*, const char*, unsigned, void*, void*, const char**);
267 #define CHK_STR_IS_DECL(what) \
268 gboolean uat_fld_chk_str_ ## what (void*, const char*, unsigned, void*, void*, const char**)
270 typedef void (*uat_cb_t)(void* uat,void* user_data);
271 void uat_foreach_table(uat_cb_t cb,void* user_data);
273 char* uat_undquote(const char* si, guint in_len, guint* len_p);
274 char* uat_unbinstring(const char* si, guint in_len, guint* len_p);
275 char* uat_unesc(const char* si, guint in_len, guint* len_p);
276 char* uat_esc(const char* buf, guint len);
278 /* Some strings entirely made of ... already declared */
279 CHK_STR_IS_DECL(isprint);
280 CHK_STR_IS_DECL(isalpha);
281 CHK_STR_IS_DECL(isalnum);
282 CHK_STR_IS_DECL(isdigit);
283 CHK_STR_IS_DECL(isxdigit);
285 #define CHK_STR_IS_DEF(what) \
286 gboolean uat_fld_chk_str_ ## what (void* u1 _U_, const char* strptr, unsigned len, void* u2 _U_, void* u3 _U_, const char** err) { \
287 guint i; for (i=0;i<len;i++) { \
288 char c = strptr[i]; \
289 if (! what((int)c)) { \
290 *err = ep_strdup_printf("invalid char pos=%d value=%.2x",i,c); return FALSE; } } \
291 *err = NULL; return TRUE; }
296 * to define basic uat_fld_set_cbs, uat_fld_tostr_cbs
297 * for those elements in uat_field_t array
302 * a simple c-string contained in (((rec_t*)rec)->(field_name))
304 #define UAT_CSTRING_CB_DEF(basename,field_name,rec_t) \
305 static void basename ## _ ## field_name ## _set_cb(void* rec, const char* buf, unsigned len, void* u1 _U_, void* u2 _U_) {\
306 if ((((rec_t*)rec)->field_name)) g_free((((rec_t*)rec)->field_name)); \
307 (((rec_t*)rec)->field_name) = g_strndup(buf,len); } \
308 static void basename ## _ ## field_name ## _tostr_cb(void* rec, const char** out_ptr, unsigned* out_len, void* u1 _U_, void* u2 _U_) {\
309 if (((rec_t*)rec)->field_name ) { \
310 *out_ptr = (((rec_t*)rec)->field_name); *out_len = strlen((((rec_t*)rec)->field_name)); \
312 *out_ptr = ""; *out_len = 0; } }
314 #define UAT_FLD_CSTRING(basename,field_name,desc) \
315 {#field_name, PT_TXTMOD_STRING,{uat_fld_chk_str,basename ## _ ## field_name ## _set_cb,basename ## _ ## field_name ## _tostr_cb},{0,0,0},0,desc,FLDFILL}
317 #define UAT_FLD_CSTRING_ISPRINT(basename,field_name,desc) \
318 {#field_name, PT_TXTMOD_STRING,{uat_fld_chk_str_isprint,basename ## _ ## field_name ## _set_cb,basename ## _ ## field_name ## _tostr_cb},{0,0,0},0,desc,FLDFILL}
320 #define UAT_FLD_CSTRING_OTHER(basename,field_name,chk,desc) \
321 {#field_name, PT_TXTMOD_STRING,{ chk ,basename ## _ ## field_name ## _set_cb,basename ## _ ## field_name ## _tostr_cb},{0,0,0},0,desc,FLDFILL}
326 #define UAT_LSTRING_CB_DEF(basename,field_name,rec_t,ptr_element,len_element) \
327 static void basename ## _ ## field_name ## _set_cb(void* rec, const char* buf, unsigned len, void* u1 _U_, void* u2 _U_) {\
328 if ((((rec_t*)rec)->ptr_element)) g_free((((rec_t*)rec)->ptr_element)); \
329 (((rec_t*)rec)->ptr_element) = uat_unesc(buf,len,&(((rec_t*)rec)->len_element)); }\
330 static void basename ## _ ## field_name ## _tostr_cb(void* rec, const char** out_ptr, unsigned* out_len, void* u1 _U_, void* u2 _U_) {\
331 if (((rec_t*)rec)->ptr_element ) { \
332 *out_ptr = uat_esc(((rec_t*)rec)->ptr_element, (((rec_t*)rec)->len_element)); \
333 *out_len = strlen(*out_ptr); \
335 *out_ptr = ""; *out_len = 0; } }
337 #define UAT_FLD_LSTRING(basename,field_name,desc) \
338 {#field_name, PT_TXTMOD_STRING,{0,basename ## _ ## field_name ## _set_cb,basename ## _ ## field_name ## _tostr_cb},{0,0,0},0,desc,FLDFILL}
343 * a buffer_ptr contained in (((rec_t*)rec)->(field_name))
344 * and its len in (((rec_t*)rec)->(len_name))
347 #define UAT_BUFFER_CB_DEF(basename,field_name,rec_t,ptr_element,len_element) \
348 static void basename ## _ ## field_name ## _set_cb(void* rec, const char* buf, unsigned len, void* u1 _U_, void* u2 _U_) {\
349 if ((((rec_t*)rec)->ptr_element) ) g_free((((rec_t*)rec)->ptr_element)); \
350 (((rec_t*)rec)->ptr_element) = len ? g_memdup(buf,len) : NULL; \
351 (((rec_t*)rec)->len_element) = len; } \
352 static void basename ## _ ## field_name ## _tostr_cb(void* rec, const char** out_ptr, unsigned* out_len, void* u1 _U_, void* u2 _U_) {\
353 *out_ptr = ((rec_t*)rec)->ptr_element ? ep_memdup(((rec_t*)rec)->ptr_element,((rec_t*)rec)->len_element) : ""; \
354 *out_len = ((rec_t*)rec)->len_element; }
356 #define UAT_FLD_BUFFER(basename,field_name,desc) \
357 {#field_name, PT_TXTMOD_HEXBYTES,{0,basename ## _ ## field_name ## _set_cb,basename ## _ ## field_name ## _tostr_cb},{0,0,0},0,desc,FLDFILL}
362 * a decimal number contained in
364 #define UAT_DEC_CB_DEF(basename,field_name,rec_t) \
365 static void basename ## _ ## field_name ## _set_cb(void* rec, const char* buf, unsigned len, void* u1 _U_, void* u2 _U_) {\
366 ((rec_t*)rec)->field_name = strtol(ep_strndup(buf,len),NULL,10); } \
367 static void basename ## _ ## field_name ## _tostr_cb(void* rec, const char** out_ptr, unsigned* out_len, void* u1 _U_, void* u2 _U_) {\
368 *out_ptr = ep_strdup_printf("%d",((rec_t*)rec)->field_name); \
369 *out_len = strlen(*out_ptr); }
371 #define UAT_FLD_DEC(basename,field_name,desc) \
372 {#field_name, PT_TXTMOD_STRING,{uat_fld_chk_num_dec,basename ## _ ## field_name ## _set_cb,basename ## _ ## field_name ## _tostr_cb},{0,0,0},0,desc,FLDFILL}
377 * an hexadecimal number contained in
379 #define UAT_HEX_CB_DEF(basename,field_name,rec_t) \
380 static void basename ## _ ## field_name ## _set_cb(void* rec, const char* buf, unsigned len, void* u1 _U_, void* u2 _U_) {\
381 ((rec_t*)rec)->field_name = strtol(ep_strndup(buf,len),NULL,16); } \
382 static void basename ## _ ## field_name ## _tostr_cb(void* rec, const char** out_ptr, unsigned* out_len, void* u1 _U_, void* u2 _U_) {\
383 *out_ptr = ep_strdup_printf("%x",((rec_t*)rec)->field_name); \
384 *out_len = strlen(*out_ptr); }
386 #define UAT_FLD_HEX(basename,field_name,desc) \
387 {#field_name, PT_TXTMOD_STRING,{uat_fld_chk_num_hex,basename ## _ ## field_name ## _set_cb,basename ## _ ## field_name ## _tostr_cb},{0,0,0},0,desc,FLDFILL}
392 * enum_t: name = ((enum_t*)ptr)->strptr
393 * value = ((enum_t*)ptr)->value
397 #define UAT_VS_DEF(basename,field_name,rec_t,default_val,default_str) \
398 static void basename ## _ ## field_name ## _set_cb(void* rec, const char* buf, unsigned len, void* vs, void* u2 _U_) {\
400 char* str = ep_strndup(buf,len); \
401 const char* cstr; ((rec_t*)rec)->field_name = default_val; \
402 for(i=0; ( cstr = ((value_string*)vs)[i].strptr ) ;i++) { \
403 if (g_str_equal(cstr,str)) { \
404 ((rec_t*)rec)->field_name = ((value_string*)vs)[i].value; return; } } } \
405 static void basename ## _ ## field_name ## _tostr_cb(void* rec, const char** out_ptr, unsigned* out_len, void* vs, void* u2 _U_) {\
407 *out_ptr = ep_strdup(default_str); *out_len = strlen(default_str);\
408 for(i=0;((value_string*)vs)[i].strptr;i++) { \
409 if ( ((value_string*)vs)[i].value == ((rec_t*)rec)->field_name ) { \
410 *out_ptr = ep_strdup(((value_string*)vs)[i].strptr); \
411 *out_len = strlen(*out_ptr); return; } } }
414 #define UAT_FLD_VS(basename,field_name,enum,desc) \
415 {#field_name, PT_TXTMOD_ENUM,{uat_fld_chk_enum,basename ## _ ## field_name ## _set_cb,basename ## _ ## field_name ## _tostr_cb},{&(enum),&(enum),&(enum)},&(enum),desc,FLDFILL}
422 #define UAT_PROTO_DEF(basename, field_name, dissector_field, name_field, rec_t) \
423 static void basename ## _ ## field_name ## _set_cb(void* rec, const char* buf, unsigned len, void* u1 _U_, void* u2 _U_) {\
425 ((rec_t*)rec)->name_field = ep_strndup(buf,len); g_strdown(((rec_t*)rec)->name_field ); g_strchug(((rec_t*)rec)->name_field); \
426 ((rec_t*)rec)->dissector_field = find_dissector(((rec_t*)rec)->name_field); \
428 ((rec_t*)rec)->dissector_field = find_dissector("data"); \
429 ((rec_t*)rec)->name_field = NULL; \
431 static void basename ## _ ## field_name ## _tostr_cb(void* rec, const char** out_ptr, unsigned* out_len, void* u1 _U_, void* u2 _U_) {\
432 if ( ((rec_t*)rec)->name_field ) { \
433 *out_ptr = (((rec_t*)rec)->name_field); \
434 *out_len = strlen(*out_ptr); \
436 *out_ptr = ""; *out_len = 0; } }
439 #define UAT_FLD_PROTO(basename,field_name,desc) \
440 {#field_name, PT_TXTMOD_STRING,{uat_fld_chk_proto,basename ## _ ## field_name ## _set_cb,basename ## _ ## field_name ## _tostr_cb},{0,0,0},0,desc,FLDFILL}
446 #define UAT_RANGE_CB_DEF(basename,field_name,rec_t) \
447 static void basename ## _ ## field_name ## _set_cb(void* rec, const char* buf, unsigned len, void* u1 _U_, void* u2) {\
448 char* rng = ep_strndup(buf,len);\
449 range_convert_str(&(((rec_t*)rec)->field_name), rng,GPOINTER_TO_UINT(u2)); \
451 static void basename ## _ ## field_name ## _tostr_cb(void* rec, const char** out_ptr, unsigned* out_len, void* u1 _U_, void* u2 _U_) {\
452 if ( ((rec_t*)rec)->field_name ) { \
453 *out_ptr = range_convert_range(((rec_t*)rec)->field_name); *out_len = strlen(*out_ptr); \
455 *out_ptr = ""; *out_len = 0; } }
458 #define UAT_FLD_RANGE(basename,field_name,max,desc) \
459 {#field_name, PT_TXTMOD_STRING,{uat_fld_chk_range,basename ## _ ## field_name ## _set_cb,basename ## _ ## field_name ## _tostr_cb},\
460 {GUINT_TO_POINTER(max),GUINT_TO_POINTER(max),GUINT_TO_POINTER(max)},0,desc,FLDFILL}