Although yet untested (but it compiles and is still unused) add UAT to the repo.

UAT is an API to handle User Accessible Tables,
an UAT is basically an array of arbitrary structs that has a file representation
as a mean for mantaining things like:
- the snmp_users_table
- dfilter macros
- ipsec/ssl key bindings
- k12 configuration,
- and many other table-like user modifiable preferences

comming soon gtk's uat_window() and prefs_add_uat()

uat.h is fairly doc[uo]m[m]?ented, a README with a simple example of how is to be used will be available as I write them


svn path=/trunk/; revision=20586

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
+