diff options
Diffstat (limited to 'epan/uat.h')
-rw-r--r-- | epan/uat.h | 247 |
1 files changed, 247 insertions, 0 deletions
diff --git a/epan/uat.h b/epan/uat.h new file mode 100644 index 0000000000..54308940c9 --- /dev/null +++ b/epan/uat.h @@ -0,0 +1,247 @@ +/* + * uat.h + * + * User Accessible Tables + * Mantain an array of user accessible data strucures + * + * (c) 2007, Luis E. Garcia Ontanon + * + */ + +#ifndef _UAT_H_ +#define _UAT_H_ + +/* + * uat mantains a dynamically allocated table accessible to the user + * via a file and/or gui tables. + * + * the file is located either in userdir(when first read or when writen) or + * in datadir for defaults (read only , it will be always written to userdir). + * + * the behaviour of the table is controlled by a series of callbacks + * the caller must provide. + * + * BEWARE that the user can change an uat at (almost) any time, + * That is pointers to records in an uat are valid only during the call + * to the function that obtains them (do not store them). + * + * UATs are meant for short tables of user data (passwords and such) there's + * no quick access, you must iterate through them each time to fetch the record + * you are looking for. Use uat_dup() or uat_se_dup() if necessary. + * + * Only users via gui or editing the file can add/remove records your code cannot. + */ + +/* obscure data type to handle an uat */ +typedef struct _uat_t uat_t; + +/******************************************** + * Callbacks: + * these instruct uat on how to deal with user info and data in records + ********************************************/ + +/******** + * Callbacks for the entire table (these deal with entire records) + ********/ + +/* + * Copy CB + * used to copy a record + * optional, memcpy will be used if not given + * copy(dest,orig,len) + */ +typedef void* (*uat_copy_cb_t)(void*, const void*, unsigned); + +/* + * + * Free CB + * + * destroy a record's child data + * (do not free the container, it will be handled by uat) + * it is optional, no child data will be freed if no present + * free(record) + */ +typedef void (*uat_free_cb_t)(void*); + +/* + * Update CB + * + * to be called after all record fields has been updated + * optional, record will be updated always if not given + * update(record,&error) + */ +typedef void (*uat_update_cb_t)(void* , char** ); + + +/******* + * Callbacks for single fields (these deal with single values) + * the caller should provide one of these for every field! + ********/ + +/* + * given an input string (ptr, len) checks if the value is OK for a field in the record. + * it will return TRUE if OK or else + * it will return FALSE and may set *error to inform the user on what's + * wrong with the given input + * optional, if not given any input is considered OK and the set cb will be called + * chk(record, ptr, len, &error) + */ +typedef gboolean (*uat_fld_chk_cb_t)(void*, const char*, unsigned, char**); + +/* + * Set Field CB + * + * given an input string (ptr, len) sets the value of a field in the record, + * it will return TRUE if OK or else + * it will return FALSE and may set *error to inform the user on what's + * wrong with the given input + * it is mandatory + * set(record, ptr, len) + */ +typedef void (*uat_fld_set_cb_t)(void*, const char*, unsigned); + +/* + * given a record returns a string representation of the field + * mandatory + * tostr(record, &ptr, &len) + */ +typedef void (*uat_fld_tostr_cb_t)(void*, char**, unsigned*); + + + + +/*********** + * Text Mode + * + * used for file and dialog representation of fileds in columns, + * when the file is read it modifies the way the value is passed back to the fld_set_cb + * (see definition bellow for description) + ***********/ + +typedef enum _uat_text_mode_t { + PT_TXTMOD_NONE, + /* not used */ + + PT_TXTMOD_STRING, + /* + file: + reads: + ,"\x20\x00\x30", as " \00",3 + ,"", as "",0 + ,, as NULL,0 + writes: + ,"\x20\x30\x00\x20", for " 0\0 ",4 + ,"", for *, 0 + ,, for NULL, * + dialog: + accepts \x?? and other escapes + gets "",0 on empty string + */ + PT_TXTMOD_HEXBYTES, + /* + file: + reads: + ,A1b2C3d4, as "\001\002\003\004",4 + ,, as NULL,0 + writes: + ,, on NULL, * + ,a1b2c3d4, on "\001\002\003\004",4 + dialog: + "a1b2c3d4" as "\001\002\003\004",4 + "a1 b2:c3d4" as "\001\002\003\004",4 + "" as NULL,0 + "invalid" as NULL,3 + "a1b" as NULL, 1 + */ +} uat_text_mode_t; + + +/* + * uat_new() + * + * creates a new uat + * + * name: the name of the table + * + * data_ptr: a pointer to a null terminated array of pointers to the data + * + * default_data: a pinter to a struct containing default values + * + * size: the size of the structure + * + * filename: the filename to be used (either in userdir or datadir) + * + * 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 + * + * + * followed by a list of N quintuplets terminated by a NULL, each quituplet has: + * + * field_name: a string with the name of the field ([a-zA-Z0-9_-]+) + * + * field_mode: see comments for enum _uat_text_mode_t below + * + * field_chk_cb: a function that given a string will check the given value + * + * field_set_cb: a function that given a string will set the value in the data structure + * + * field_tostr_cb: a function that given a record generates a string,len pair representing this file + * + */ +uat_t* uat_new(const char* name, + size_t size, + char* filename, + void** data_ptr, + guint* num_items, + uat_copy_cb_t copy_cb, + uat_update_cb_t update_cb, + uat_free_cb_t free_cb, + ...); + + +/* + * uat_start() + * as uat_new() but leaves the dyntable without fields + */ +uat_t* uat_start(const char* name, + size_t size, + char* filename, + void** data_ptr, + guint* num_items, + uat_copy_cb_t copy_cb, + uat_update_cb_t update_cb, + uat_free_cb_t free_cb); + +/* + * uat_add_field() + * adds a field to a uat created with uat_start(), + * see uat_new() for description of arguments + */ +void uat_add_field(uat_t*, + const char* name, + uat_text_mode_t mode, + uat_fld_chk_cb_t chk_cb, + uat_fld_set_cb_t set_cb, + uat_fld_tostr_cb_t tostr_cb); + +/* + * uat_finalize() + * once fields have been added it makes the uat usable, leaves it locked. + */ +void uat_finalize(uat_t*); + +/* + * uat_dup() + * uat_se_dup() + * make a reliable copy of an uat for internal use, + * so that pointers to records can be kept through calls. + * return NULL on zero len. + */ +void* uat_dup(uat_t*, guint* len_p); /* to be freed */ +void* uat_se_dup(uat_t*, guint* len_p); + +#endif + |