From Harald Welte:
[obnox/wireshark/wip.git] / epan / tvbparse.h
index 7030dc409867f9f443c4d892c773080f8faf2eb7..c4560f1d014e8fe946d2427add663d3c2ce24143 100644 (file)
@@ -1,4 +1,3 @@
-
 /* tvbparse.h
 *
 * an API for text tvb parsers
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version 2
 * of the License, or (at your option) any later version.
-* 
+*
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
-* 
+*
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 /*
  The intention behind this is to ease the writing of dissectors that have to
  parse text without the need of writing into buffers.
+
  It was originally written to avoid using lex and yacc for the xml dissector.
+
  the parser is able to look for wanted elements these can be:
+
  simple tokens:
  - a char out of a string of needles
  - a char not belonging to a string of needles
  - a string
  - a caseless string
  - all the characters up to a certain wanted element (included or excluded)
+
  composed elements:
  - one of a given group of wanted elements
  - a sequence of wanted elements
  - some (at least one) instances of a wanted element
+
  Once a wanted element is successfully extracted, by either tvbparse_get or
- tvbparse_find, the parser will invoke a given callback 
+ tvbparse_find, the parser will invoke a given callback
  before and another one after every of its component's subelement's callbacks
  are being called.
+
  If tvbparse_get or tvbparse_find fail to extract the wanted element the
  subelements callbacks are not going to be invoked.
+
  The wanted elements are instantiated once by the proto_register_xxx function.
+
  The parser is instantiated for every packet and it mantains its state.
+
  The element's data is destroyed before the next packet is dissected.
  */
 
@@ -90,7 +89,7 @@ typedef void (*tvbparse_action_t)(void* tvbparse_data, const void* wanted_data,
 
 typedef int (*tvbparse_condition_t)
 (tvbparse_t*, const int,
- const tvbparse_wanted_t*, 
+ const tvbparse_wanted_t*,
  tvbparse_elem_t**);
 
 
@@ -103,52 +102,51 @@ typedef enum  {
 
 struct _tvbparse_wanted_t {
        int id;
-    tvbparse_condition_t condition;
-    
+       tvbparse_condition_t condition;
+
        union {
-        const gchar* str;
-        struct _tvbparse_wanted_t** handle;
-        struct {
-            union {
-                gint64 i;
-                guint64 u;
-                gdouble f;
-            } value;            
-            gboolean (*comp)(void*,const void*);
-            void* (*extract)(tvbuff_t*,guint);
-        } number;
-        enum ftenum ftenum;
-        struct {
-            until_mode_t mode;
-            const tvbparse_wanted_t* subelem;
-        } until;
-        struct {
-            GHashTable* table;
-            struct _tvbparse_wanted_t* key;
-            struct _tvbparse_wanted_t* other;
-        } hash;
-        GPtrArray* elems;
-        const tvbparse_wanted_t* subelem;
-        void* p;
-    } control;
-    
+               const gchar* str;
+               struct _tvbparse_wanted_t** handle;
+               struct {
+                       union {
+                               gint64 i;
+                               guint64 u;
+                               gdouble f;
+                       } value;
+                       gboolean (*comp)(void*,const void*);
+                       void* (*extract)(tvbuff_t*,guint);
+               } number;
+               enum ftenum ftenum;
+               struct {
+                       until_mode_t mode;
+                       const tvbparse_wanted_t* subelem;
+               } until;
+               struct {
+                       GHashTable* table;
+                       struct _tvbparse_wanted_t* key;
+                       struct _tvbparse_wanted_t* other;
+               } hash;
+               GPtrArray* elems;
+               const tvbparse_wanted_t* subelem;
+               void* p;
+       } control;
+
        int len;
-       
+
        guint min;
        guint max;
-       
+
        const void* data;
-    
+
        tvbparse_action_t before;
        tvbparse_action_t after;
-       
 };
 
 /* an instance of a per packet parser */
 struct _tvbparse_t {
        tvbuff_t* tvb;
        int offset;
-    int end_offset;
+       int end_offset;
        void* data;
        const tvbparse_wanted_t* ignore;
 };
@@ -157,18 +155,18 @@ struct _tvbparse_t {
 /* a matching token returned by either tvbparser_get or tvb_parser_find */
 struct _tvbparse_elem_t {
        int id;
-       
+
        tvbuff_t* tvb;
        int offset;
        int len;
-       
+
        void* data;
-       
+
        struct _tvbparse_elem_t* sub;
-       
+
        struct _tvbparse_elem_t* next;
        struct _tvbparse_elem_t* last;
-       
+
        const tvbparse_wanted_t* wanted;
 };
 
@@ -215,7 +213,7 @@ tvbparse_wanted_t* tvbparse_not_char(const int id,
  *
  * When looked for it returns a simple element one or more characters long if
  * one or more char(s) starting from the current offset match one of the needles.
- * An element will be returned if at least min_len chars are given (1 if it's 0) 
+ * An element will be returned if at least min_len chars are given (1 if it's 0)
  * It will get at most max_len chars or as much as it can if max_len is 0.
  */
 tvbparse_wanted_t* tvbparse_chars(const int id,
@@ -232,7 +230,7 @@ tvbparse_wanted_t* tvbparse_chars(const int id,
  * When looked for it returns a simple element one or more characters long if
  * one or more char(s) starting from the current offset do not match one of the
  * needles.
- * An element will be returned if at least min_len chars are given (1 if it's 0) 
+ * An element will be returned if at least min_len chars are given (1 if it's 0)
  * It will get at most max_len chars or as much as it can if max_len is 0.
  */
 tvbparse_wanted_t* tvbparse_not_chars(const int id,
@@ -247,7 +245,7 @@ tvbparse_wanted_t* tvbparse_not_chars(const int id,
  * a string element
  *
  * When looked for it returns a simple element if we have the given string at
- * the current offset 
+ * the current offset
  */
 tvbparse_wanted_t* tvbparse_string(const int id,
                                                                   const gchar* string,
@@ -259,7 +257,7 @@ tvbparse_wanted_t* tvbparse_string(const int id,
  * casestring
  *
  * When looked for it returns a simple element if we have a matching string at
- * the current offset 
+ * the current offset
  */
 tvbparse_wanted_t* tvbparse_casestring(const int id,
                                                                           const gchar* str,
@@ -270,18 +268,18 @@ tvbparse_wanted_t* tvbparse_casestring(const int id,
 /*
  * until
  *
- * When looked for it returns a simple element containing all the characters 
+ * When looked for it returns a simple element containing all the characters
  * found until the first match of the ending element if the ending element is
  * found.
  *
- * When looking for until elements it calls tvbparse_find so it can be very slow. 
+ * When looking for until elements it calls tvbparse_find so it can be very slow.
  *
  * It won't have a subelement, the ending's callbacks won't get called.
  */
 
 /*
  * op_mode values determine how the terminating element and the current offset
- * of the parser are handled 
+ * of the parser are handled
  */
 tvbparse_wanted_t* tvbparse_until(const int id,
                                                                  const void* private_data,
@@ -305,17 +303,16 @@ tvbparse_wanted_t* tvbparse_set_oneof(const int id,
                                                                          tvbparse_action_t after_cb,
                                                                          ...);
 
-/* 
+/*
  * hashed
  */
-
 tvbparse_wanted_t* tvbparse_hashed(const int id,
-                                   const void* data, 
-                                   tvbparse_action_t before_cb,
-                                   tvbparse_action_t after_cb,
-                                   tvbparse_wanted_t* key,
-                                   tvbparse_wanted_t* other,
-                                   ...);
+                                                                  const void* data,
+                                                                  tvbparse_action_t before_cb,
+                                                                  tvbparse_action_t after_cb,
+                                                                  tvbparse_wanted_t* key,
+                                                                  tvbparse_wanted_t* other,
+                                                                  ...);
 
 void tvbparse_hashed_add(tvbparse_wanted_t* w, ...);
 
@@ -334,6 +331,7 @@ tvbparse_wanted_t* tvbparse_set_seq(const int id,
                                                                        tvbparse_action_t before_cb,
                                                                        tvbparse_action_t after_cb,
                                                                        ...);
+
 /*
  * some
  *
@@ -354,7 +352,7 @@ tvbparse_wanted_t* tvbparse_some(const int id,
        tvbparse_some(id, 1, G_MAXINT, private_data, before_cb, after_cb, wanted)
 
 
-/* 
+/*
  * handle
  *
  * this is a pointer to a pointer to a wanted element (that might have not
@@ -422,12 +420,12 @@ void tvbparse_shrink_token_cb(void* tvbparse_data,
 
 
 /* initialize the parser (at every packet)
-* tvb: what are we parsing? 
-* offset: from where
-* len: for how many bytes
-* private_data: will be passed to the action callbacks 
-* ignore: a wanted token type to be ignored (the associated cb WILL be called when it matches)
-*/
+ * tvb: what are we parsing?
+ * offset: from where
+ * len: for how many bytes
+ * private_data: will be passed to the action callbacks
+ * ignore: a wanted token type to be ignored (the associated cb WILL be called when it matches)
+ */
 tvbparse_t* tvbparse_init(tvbuff_t* tvb,
                                                  const int offset,
                                                  int len,
@@ -435,7 +433,7 @@ tvbparse_t* tvbparse_init(tvbuff_t* tvb,
                                                  const tvbparse_wanted_t* ignore);
 
 /* reset the parser */
-gboolean tvbparse_reset(tvbparse_t* tt, int offset, int len);
+gboolean tvbparse_reset(tvbparse_t* tt, const int offset, int len);
 
 guint tvbparse_curr_offset(tvbparse_t* tt);
 guint tvbparse_len_left(tvbparse_t* tt);
@@ -446,16 +444,16 @@ guint tvbparse_len_left(tvbparse_t* tt);
  * This will look for the wanted token at the current offset or after any given
  * number of ignored tokens returning FALSE if there's no match or TRUE if there
  * is a match.
- * The parser will be left in its original state and no callbacks will be called. 
+ * The parser will be left in its original state and no callbacks will be called.
  */
 gboolean tvbparse_peek(tvbparse_t* tt,
-                        const tvbparse_wanted_t* wanted);
+                                          const tvbparse_wanted_t* wanted);
 
 /*
  * This will look for the wanted token at the current offset or after any given
  * number of ignored tokens returning NULL if there's no match.
  * if there is a match it will set the offset of the current parser after
- * the end of the token 
+ * the end of the token
  */
 tvbparse_elem_t* tvbparse_get(tvbparse_t* tt,
                                                          const tvbparse_wanted_t* wanted);
@@ -465,7 +463,6 @@ tvbparse_elem_t* tvbparse_get(tvbparse_t* tt,
  * current offset.
  * This function is slow.
  */
-
 tvbparse_elem_t* tvbparse_find(tvbparse_t* tt,
                                                           const tvbparse_wanted_t* wanted);