epan/uat.h

   1 /*
   2  *  uat.h
   3  *
   4  *  $Id$
   5  *
   6  *  User Accessible Tables
   7  *  Mantain an array of user accessible data strucures
   8  *
   9  * (c) 2007, Luis E. Garcia Ontanon <luis@ontanon.org>
  10  *
  11  * Wireshark - Network traffic analyzer
  12  * By Gerald Combs <gerald@wireshark.org>
  13  * Copyright 2001 Gerald Combs
  14  *
  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.
  19  *
  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.
  24  *
  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.
  28  */
  29
  30 #ifndef _UAT_H_
  31 #define _UAT_H_
  32
  33 /*
  34  * uat mantains a dynamically allocated table accessible to the user
  35  * via a file and/or gui tables.
  36  *
  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).
  39  *
  40  * the behaviour of the table is controlled by a series of callbacks
  41  * the caller must provide.
  42  *
  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).
  46  *
  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.
  50  *
  51  * Only users via gui or editing the file can add/remove records your code cannot.
  52  */
  53
  54 /* obscure data type to handle an uat */
  55 typedef struct _uat_t uat_t;
  56 /********************************************
  57  * Callbacks:
  58  * these instruct uat on how to deal with user info and data in records
  59  ********************************************/
  60
  61 /********
  62  * Callbacks for the entire table (these deal with entire records)
  63  ********/
  64
  65 /*
  66  * Copy CB
  67  * used to copy a record
  68  * optional, memcpy will be used if not given
  69  * copy(dest,orig,len)
  70  */
  71 typedef void* (*uat_copy_cb_t)(void*, const void*, unsigned);
  72
  73 /*
  74  *
  75  * Free CB
  76  *
  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
  80  * free(record)
  81  */
  82 typedef void (*uat_free_cb_t)(void*);
  83
  84 /*
  85  * Update CB
  86  *
  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)
  90  */
  91 typedef void (*uat_update_cb_t)(void* , const char** );
  92
  93
  94 /*******
  95  * Callbacks for single fields (these deal with single values)
  96  * the caller should provide one of these for every field!
  97  ********/
  98
  99 /*
 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)
 106  */
 107 typedef gboolean (*uat_fld_chk_cb_t)(void*, const char*, unsigned, void*, void*, const char**);
 108
 109 /*
 110  * Set Field CB
 111  *
 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
 116  * it is mandatory
 117  * set(record, ptr, len, set_data, fld_data)
 118  */
 119 typedef void (*uat_fld_set_cb_t)(void*, const char*, unsigned, void*, void*);
 120
 121 /*
 122  * given a record returns a string representation of the field
 123  * mandatory
 124  * tostr(record, &out_ptr, &out_len, tostr_data, fld_data)
 125  */
 126 typedef void (*uat_fld_tostr_cb_t)(void*, const char**, unsigned*, void*, void*);
 127
 128 /***********
 129  * Text Mode
 130  *
 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)
 134  ***********/
 135
 136 typedef enum _uat_text_mode_t {
 137         PT_TXTMOD_NONE,
 138         /* not used */
 139
 140         PT_TXTMOD_STRING,
 141         /*
 142          file:
 143                  reads:
 144                          ,"\x20\x00\x30", as " \00",3
 145                          ,"", as "",0
 146                          ,, as NULL,0
 147                  writes:
 148                          ,"\x20\x30\x00\x20", for " 0\0 ",4
 149                          ,"", for *, 0
 150                          ,, for NULL, *
 151          dialog:
 152                  accepts \x?? and other escapes
 153                  gets "",0 on empty string
 154          */
 155         PT_TXTMOD_HEXBYTES,
 156         /*
 157          file:
 158                  reads:
 159                          ,A1b2C3d4, as "\001\002\003\004",4
 160                          ,, as NULL,0
 161                  writes:
 162                          ,, on NULL, *
 163                          ,a1b2c3d4, on "\001\002\003\004",4
 164          dialog:
 165                  "a1b2c3d4" as "\001\002\003\004",4
 166                  "a1 b2:c3d4" as "\001\002\003\004",4
 167                  "" as NULL,0
 168                  "invalid" as NULL,3
 169                  "a1b" as NULL, 1
 170          */
 171         PT_TXTMOD_ENUM
 172 } uat_text_mode_t;
 173
 174 /*
 175  * Fields
 176  *
 177  *
 178  */
 179 typedef struct _uat_field_t {
 180         const char* name;
 181         uat_text_mode_t mode;
 182
 183         struct {
 184                 uat_fld_chk_cb_t chk;
 185                 uat_fld_set_cb_t set;
 186                 uat_fld_tostr_cb_t tostr;
 187         } cb;
 188
 189         struct {
 190                 void* chk;
 191                 void* set;
 192                 void* tostr;
 193         } cbdata;
 194
 195         void* fld_data;
 196
 197         const char* desc;
 198         struct _fld_data_t* priv;
 199 } uat_field_t;
 200
 201 #define FLDFILL NULL
 202 #define UAT_END_FIELDS {0,PT_TXTMOD_NONE,{0,0,0},{0,0,0},0,0,FLDFILL}
 203
 204
 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"
 209
 210 /** Create a new uat
 211  *
 212  * @param name The name of the table
 213  * @param data_ptr A pointer to a null terminated array of pointers to the data
 214  * @param default_data A pointer to a struct containing default values
 215  * @param size The size of the structure
 216  * @param filename The filename to be used (either in userdir or datadir)
 217  * @param copy_cb A function that copies the data in the struct
 218  * @param update_cb Will be called when a record is updated
 219  * @param free_cb Will be called to destroy a struct in the dataset
 220  *
 221  * @return A freshly-allocated and populated uat_t struct.
 222  */
 223 uat_t* uat_new(const char* name,
 224                            size_t size,
 225                            const char* filename,
 226                            gboolean from_profile,
 227                            void** data_ptr,
 228                            guint* num_items,
 229                            const char* category,
 230                            const char* help,
 231                            uat_copy_cb_t copy_cb,
 232                            uat_update_cb_t update_cb,
 233                            uat_free_cb_t free_cb,
 234                            uat_field_t* flds_array);
 235
 236 /** Populate a uat using its file.
 237  *
 238  * @param uat_in Pointer to a uat. Must not be NULL.
 239  * @param err Upon failure, points to an error string.
 240  *
 241  * @return TRUE on success, FALSE on failure.
 242  */
 243 gboolean uat_load(uat_t* uat_in, char** err);
 244
 245 /** Create or update a single uat entry using a string.
 246  *
 247  * @param uat_in Pointer to a uat. Must not be NULL.
 248  * @param entry The string representation of the entry. Format must match
 249  * what's written to the uat's output file.
 250  * @param err Upon failure, points to an error string.
 251  *
 252  * @return TRUE on success, FALSE on failure.
 253  */
 254 gboolean uat_load_str(uat_t* uat_in, char* entry, char** err);
 255
 256 /** Given a uat name or filename, find its pointer.
 257  *
 258  * @param name The name or filename of the uat
 259  *
 260  * @return A pointer to the uat on success, NULL on failure.
 261  */
 262 uat_t *uat_find(gchar *name);
 263
 264 /*
 265  * uat_dup()
 266  * uat_se_dup()
 267  * make a reliable copy of an uat for internal use,
 268  * so that pointers to records can be kept through calls.
 269  * return NULL on zero len.
 270  */
 271 void* uat_dup(uat_t*, guint* len_p); /* to be freed */
 272 void* uat_se_dup(uat_t*, guint* len_p);
 273 uat_t* uat_get_table_by_name(const char* name);
 274
 275 /*
 276  * Some common uat_fld_chk_cbs
 277  */
 278 gboolean uat_fld_chk_str(void*, const char*, unsigned, void*,void*, const char** err);
 279 gboolean uat_fld_chk_proto(void*, const char*, unsigned, void*,void*, const char** err);
 280 gboolean uat_fld_chk_num_dec(void*, const char*, unsigned, void*, void*, const char** err);
 281 gboolean uat_fld_chk_num_hex(void*, const char*, unsigned, void*, void*, const char** err);
 282 gboolean uat_fld_chk_enum(void*, const char*, unsigned, void*, void*, const char**);
 283 gboolean uat_fld_chk_range(void*, const char*, unsigned, void*, void*, const char**);
 284
 285 #define CHK_STR_IS_DECL(what) \
 286 gboolean uat_fld_chk_str_ ## what (void*, const char*, unsigned, void*, void*, const char**)
 287
 288 typedef void (*uat_cb_t)(void* uat,void* user_data);
 289 void uat_foreach_table(uat_cb_t cb,void* user_data);
 290 void uat_unload_all(void);
 291
 292 char* uat_undquote(const char* si, guint in_len, guint* len_p);
 293 char* uat_unbinstring(const char* si, guint in_len, guint* len_p);
 294 char* uat_unesc(const char* si, guint in_len, guint* len_p);
 295 char* uat_esc(const char* buf, guint len);
 296
 297 /* Some strings entirely made of ... already declared */
 298 CHK_STR_IS_DECL(isprint);
 299 CHK_STR_IS_DECL(isalpha);
 300 CHK_STR_IS_DECL(isalnum);
 301 CHK_STR_IS_DECL(isdigit);
 302 CHK_STR_IS_DECL(isxdigit);
 303
 304 #define CHK_STR_IS_DEF(what) \
 305 gboolean uat_fld_chk_str_ ## what (void* u1 _U_, const char* strptr, unsigned len, void* u2 _U_, void* u3 _U_, const char** err) { \
 306         guint i; for (i=0;i<len;i++) { \
 307                 char c = strptr[i]; \
 308                         if (! what((int)c)) { \
 309                                 *err = ep_strdup_printf("invalid char pos=%d value=%.2x",i,c); return FALSE;  } } \
 310                 *err = NULL; return TRUE; }
 311
 312
 313 /*
 314  * Macros
 315  *   to define basic uat_fld_set_cbs, uat_fld_tostr_cbs
 316  *   for those elements in uat_field_t array
 317  */
 318
 319 /*
 320  * CSTRING macros,
 321  *    a simple c-string contained in (((rec_t*)rec)->(field_name))
 322  */
 323 #define UAT_CSTRING_CB_DEF(basename,field_name,rec_t) \
 324 static void basename ## _ ## field_name ## _set_cb(void* rec, const char* buf, unsigned len, void* u1 _U_, void* u2 _U_) {\
 325     char* new_buf = g_strndup(buf,len); \
 326         if ((((rec_t*)rec)->field_name)) g_free((((rec_t*)rec)->field_name)); \
 327         (((rec_t*)rec)->field_name) = new_buf; } \
 328 static void basename ## _ ## field_name ## _tostr_cb(void* rec, const char** out_ptr, unsigned* out_len, void* u1 _U_, void* u2 _U_) {\
 329                 if (((rec_t*)rec)->field_name ) { \
 330                         *out_ptr = (((rec_t*)rec)->field_name); *out_len = strlen((((rec_t*)rec)->field_name)); \
 331                 } else { \
 332                         *out_ptr = ""; *out_len = 0; } }
 333
 334 #define UAT_FLD_CSTRING(basename,field_name,desc) \
 335         {#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}
 336
 337 #define UAT_FLD_CSTRING_ISPRINT(basename,field_name,desc) \
 338         {#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}
 339
 340 #define UAT_FLD_CSTRING_OTHER(basename,field_name,chk,desc) \
 341         {#field_name, PT_TXTMOD_STRING,{ chk ,basename ## _ ## field_name ## _set_cb,basename ## _ ## field_name ## _tostr_cb},{0,0,0},0,desc,FLDFILL}
 342
 343 /*
 344  * LSTRING MACROS
 345  */
 346 #define UAT_LSTRING_CB_DEF(basename,field_name,rec_t,ptr_element,len_element) \
 347 static void basename ## _ ## field_name ## _set_cb(void* rec, const char* buf, unsigned len, void* u1 _U_, void* u2 _U_) {\
 348         char* new_val = uat_unesc(buf,len,&(((rec_t*)rec)->len_element)); \
 349     if ((((rec_t*)rec)->ptr_element)) g_free((((rec_t*)rec)->ptr_element)); \
 350         (((rec_t*)rec)->ptr_element) = new_val; }\
 351 static void basename ## _ ## field_name ## _tostr_cb(void* rec, const char** out_ptr, unsigned* out_len, void* u1 _U_, void* u2 _U_) {\
 352         if (((rec_t*)rec)->ptr_element ) { \
 353                 *out_ptr = uat_esc(((rec_t*)rec)->ptr_element, (((rec_t*)rec)->len_element)); \
 354                 *out_len = strlen(*out_ptr); \
 355         } else { \
 356                 *out_ptr = ""; *out_len = 0; } }
 357
 358 #define UAT_FLD_LSTRING(basename,field_name,desc) \
 359 {#field_name, PT_TXTMOD_STRING,{0,basename ## _ ## field_name ## _set_cb,basename ## _ ## field_name ## _tostr_cb},{0,0,0},0,desc,FLDFILL}
 360
 361
 362 /*
 363  * BUFFER macros,
 364  *    a buffer_ptr contained in (((rec_t*)rec)->(field_name))
 365  *    and its len in (((rec_t*)rec)->(len_name))
 366  *  XXX: UNTESTED and probably BROKEN
 367  */
 368 #define UAT_BUFFER_CB_DEF(basename,field_name,rec_t,ptr_element,len_element) \
 369 static void basename ## _ ## field_name ## _set_cb(void* rec, const char* buf, unsigned len, void* u1 _U_, void* u2 _U_) {\
 370         char* new_buf = len ? g_memdup(buf,len) : NULL; \
 371                 if ((((rec_t*)rec)->ptr_element) ) g_free((((rec_t*)rec)->ptr_element)); \
 372                         (((rec_t*)rec)->ptr_element) = new_buf; \
 373                         (((rec_t*)rec)->len_element) = len; } \
 374 static void basename ## _ ## field_name ## _tostr_cb(void* rec, const char** out_ptr, unsigned* out_len, void* u1 _U_, void* u2 _U_) {\
 375         *out_ptr = ((rec_t*)rec)->ptr_element ? ep_memdup(((rec_t*)rec)->ptr_element,((rec_t*)rec)->len_element) : ""; \
 376         *out_len = ((rec_t*)rec)->len_element; }
 377
 378 #define UAT_FLD_BUFFER(basename,field_name,desc) \
 379         {#field_name, PT_TXTMOD_HEXBYTES,{0,basename ## _ ## field_name ## _set_cb,basename ## _ ## field_name ## _tostr_cb},{0,0,0},0,desc,FLDFILL}
 380
 381
 382 /*
 383  * DEC Macros,
 384  *   a decimal number contained in
 385  */
 386 #define UAT_DEC_CB_DEF(basename,field_name,rec_t) \
 387 static void basename ## _ ## field_name ## _set_cb(void* rec, const char* buf, unsigned len, void* u1 _U_, void* u2 _U_) {\
 388         ((rec_t*)rec)->field_name = strtol(ep_strndup(buf,len),NULL,10); } \
 389 static void basename ## _ ## field_name ## _tostr_cb(void* rec, const char** out_ptr, unsigned* out_len, void* u1 _U_, void* u2 _U_) {\
 390         *out_ptr = ep_strdup_printf("%d",((rec_t*)rec)->field_name); \
 391         *out_len = strlen(*out_ptr); }
 392
 393 #define UAT_FLD_DEC(basename,field_name,desc) \
 394         {#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}
 395
 396
 397 /*
 398  * HEX Macros,
 399  *   an hexadecimal number contained in
 400  */
 401 #define UAT_HEX_CB_DEF(basename,field_name,rec_t) \
 402 static void basename ## _ ## field_name ## _set_cb(void* rec, const char* buf, unsigned len, void* u1 _U_, void* u2 _U_) {\
 403         ((rec_t*)rec)->field_name = strtol(ep_strndup(buf,len),NULL,16); } \
 404 static void basename ## _ ## field_name ## _tostr_cb(void* rec, const char** out_ptr, unsigned* out_len, void* u1 _U_, void* u2 _U_) {\
 405         *out_ptr = ep_strdup_printf("%x",((rec_t*)rec)->field_name); \
 406         *out_len = strlen(*out_ptr); }
 407
 408 #define UAT_FLD_HEX(basename,field_name,desc) \
 409 {#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}
 410
 411
 412 /*
 413  * ENUM macros
 414  *  enum_t: name = ((enum_t*)ptr)->strptr
 415  *          value = ((enum_t*)ptr)->value
 416  *  rec_t:
 417  *        value
 418  */
 419 #define UAT_VS_DEF(basename,field_name,rec_t,default_val,default_str) \
 420 static void basename ## _ ## field_name ## _set_cb(void* rec, const char* buf, unsigned len, void* vs, void* u2 _U_) {\
 421         guint i; \
 422         char* str = ep_strndup(buf,len); \
 423         const char* cstr; ((rec_t*)rec)->field_name = default_val; \
 424         for(i=0; ( cstr = ((value_string*)vs)[i].strptr ) ;i++) { \
 425                 if (g_str_equal(cstr,str)) { \
 426                         ((rec_t*)rec)->field_name = ((value_string*)vs)[i].value; return; } } } \
 427 static void basename ## _ ## field_name ## _tostr_cb(void* rec, const char** out_ptr, unsigned* out_len, void* vs, void* u2 _U_) {\
 428         guint i; \
 429         *out_ptr = ep_strdup(default_str); *out_len = strlen(default_str);\
 430         for(i=0;((value_string*)vs)[i].strptr;i++) { \
 431                 if ( ((value_string*)vs)[i].value == ((rec_t*)rec)->field_name ) { \
 432                         *out_ptr = ep_strdup(((value_string*)vs)[i].strptr); \
 433                         *out_len = strlen(*out_ptr); return; } } }
 434
 435
 436 #define UAT_FLD_VS(basename,field_name,enum,desc) \
 437         {#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}
 438
 439
 440 /*
 441  * PROTO macros
 442  */
 443
 444 #define UAT_PROTO_DEF(basename, field_name, dissector_field, name_field, rec_t) \
 445 static void basename ## _ ## field_name ## _set_cb(void* rec, const char* buf, unsigned len, void* u1 _U_, void* u2 _U_) {\
 446         if (len) { \
 447                 ((rec_t*)rec)->name_field = ep_strndup(buf,len); g_strdown(((rec_t*)rec)->name_field ); g_strchug(((rec_t*)rec)->name_field); \
 448                 ((rec_t*)rec)->dissector_field = find_dissector(((rec_t*)rec)->name_field); \
 449         } else { \
 450                 ((rec_t*)rec)->dissector_field = find_dissector("data"); \
 451                 ((rec_t*)rec)->name_field = NULL; \
 452                 } } \
 453 static void basename ## _ ## field_name ## _tostr_cb(void* rec, const char** out_ptr, unsigned* out_len, void* u1 _U_, void* u2 _U_) {\
 454         if ( ((rec_t*)rec)->name_field ) { \
 455                 *out_ptr = (((rec_t*)rec)->name_field); \
 456                 *out_len = strlen(*out_ptr); \
 457         } else { \
 458                 *out_ptr = ""; *out_len = 0; } }
 459
 460
 461 #define UAT_FLD_PROTO(basename,field_name,desc) \
 462         {#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}
 463
 464 /*
 465  * RANGE macros
 466  */
 467
 468 #define UAT_RANGE_CB_DEF(basename,field_name,rec_t) \
 469 static void basename ## _ ## field_name ## _set_cb(void* rec, const char* buf, unsigned len, void* u1 _U_, void* u2) {\
 470         char* rng = ep_strndup(buf,len);\
 471                 range_convert_str(&(((rec_t*)rec)->field_name), rng,GPOINTER_TO_UINT(u2)); \
 472         } \
 473 static void basename ## _ ## field_name ## _tostr_cb(void* rec, const char** out_ptr, unsigned* out_len, void* u1 _U_, void* u2 _U_) {\
 474         if ( ((rec_t*)rec)->field_name ) { \
 475                 *out_ptr = range_convert_range(((rec_t*)rec)->field_name);  *out_len = strlen(*out_ptr); \
 476         } else { \
 477                 *out_ptr = ""; *out_len = 0; } }
 478
 479
 480 #define UAT_FLD_RANGE(basename,field_name,max,desc) \
 481         {#field_name, PT_TXTMOD_STRING,{uat_fld_chk_range,basename ## _ ## field_name ## _set_cb,basename ## _ ## field_name ## _tostr_cb},\
 482           {GUINT_TO_POINTER(max),GUINT_TO_POINTER(max),GUINT_TO_POINTER(max)},0,desc,FLDFILL}
 483
 484
 485
 486
 487
 488 #endif
 489