tvbparse.h

Go to the documentation of this file.

 
/*
 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 sequence of chars that belong to a set of chars
 - a sequence of chars that do not belong to a set of chars
 - 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
 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 maintains its state.
 
 The element's data is destroyed before the next packet is dissected.
 */
#pragma once
#include <epan/tvbuff.h>
#include "ws_symbol_export.h"
 
typedef struct _tvbparse_elem_t tvbparse_elem_t;
typedef struct _tvbparse_wanted_t tvbparse_wanted_t;
typedef struct _tvbparse_t tvbparse_t;
 
 
/*
 * a callback function to be called before or after an element has been
 * successfully extracted.
 *
 * Note that if the token belongs to a composed token the callbacks of the
 * components won't be called unless the composed token is successfully
 * extracted.
 *
 * tvbparse_data: the private data of the parser
 * wanted_data: the private data of the wanted element
 * elem: the extracted element
 */
typedef void (*tvbparse_action_t)(void* tvbparse_data, const void* wanted_data, struct _tvbparse_elem_t* elem);
 
typedef int (*tvbparse_condition_t)
(tvbparse_t*, const int,
 const tvbparse_wanted_t*,
 tvbparse_elem_t**);
 
 
typedef enum {
    TP_UNTIL_INCLUDE, 
    TP_UNTIL_SPEND,   
    TP_UNTIL_LEAVE    
} until_mode_t;
 
 
struct _tvbparse_wanted_t {
    int id; 
    tvbparse_condition_t condition; 
    union {
        const char* str; 
        struct _tvbparse_wanted_t** handle; 
        struct {
            union {
                int64_t i;     
                uint64_t u;    
                double f;      
            } value;
        } number; 
        enum ftenum ftenum; 
        struct {
            until_mode_t mode; 
            const tvbparse_wanted_t* subelem; 
        } until;
        struct {
            wmem_map_t* table; 
            struct _tvbparse_wanted_t* key; 
            struct _tvbparse_wanted_t* other; 
        } hash;
        GPtrArray* elems; 
        const tvbparse_wanted_t* subelem; 
        void* p; 
    } control;
 
    int len; 
    unsigned min; 
    unsigned max; 
    const void* data; 
    tvbparse_action_t before; 
    tvbparse_action_t after;  
};
 
struct _tvbparse_t {
    wmem_allocator_t* scope;              
    tvbuff_t* tvb;                        
    int offset;                           
    int end_offset;                       
    void* data;                           
    const tvbparse_wanted_t* ignore;      
    int recursion_depth;                  
};
 
 
struct _tvbparse_elem_t {
    int                       id;     
    tvbparse_t*               parser; 
    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; 
};
 
 
/*
 * definition of wanted token types
 *
 * the following functions define the tokens we will be able to look for in a tvb
 * common parameters are:
 *
 * id: an arbitrary id that will be copied to the eventual token (don't use 0)
 * private_data: persistent data to be passed to the callback action (wanted_data)
 * before_cb: an callback function to be called before those of the subelements
 * after_cb: an callback function to be called after those of the subelements
 */
 
 
WS_DLL_PUBLIC
tvbparse_wanted_t *tvbparse_char(const int id,
                                 const char *needles,
                                 const void *private_data,
                                 tvbparse_action_t before_cb,
                                 tvbparse_action_t after_cb);
 
 
WS_DLL_PUBLIC
tvbparse_wanted_t *tvbparse_not_char(const int id,
                                     const char *needle,
                                     const void *private_data,
                                     tvbparse_action_t before_cb,
                                     tvbparse_action_t after_cb);
 
WS_DLL_PUBLIC
tvbparse_wanted_t *tvbparse_chars(const int id,
                                  const unsigned min_len,
                                  const unsigned max_len,
                                  const char *needles,
                                  const void *private_data,
                                  tvbparse_action_t before_cb,
                                  tvbparse_action_t after_cb);
 
WS_DLL_PUBLIC
tvbparse_wanted_t *tvbparse_not_chars(const int id,
                                      const unsigned min_len,
                                      const unsigned max_len,
                                      const char *needles,
                                      const void *private_data,
                                      tvbparse_action_t before_cb,
                                      tvbparse_action_t after_cb);
 
WS_DLL_PUBLIC
tvbparse_wanted_t *tvbparse_string(const int id,
                                   const char *string,
                                   const void *private_data,
                                   tvbparse_action_t before_cb,
                                   tvbparse_action_t after_cb);
 
WS_DLL_PUBLIC
tvbparse_wanted_t *tvbparse_casestring(const int id,
                                       const char *str,
                                       const void *data,
                                       tvbparse_action_t before_cb,
                                       tvbparse_action_t after_cb);
 
WS_DLL_PUBLIC
tvbparse_wanted_t *tvbparse_until(const int id,
                                  const void *private_data,
                                  tvbparse_action_t before_cb,
                                  tvbparse_action_t after_cb,
                                  const tvbparse_wanted_t *ending,
                                  until_mode_t until_mode);
 
WS_DLL_PUBLIC
tvbparse_wanted_t *tvbparse_set_oneof(const int id,
                                      const void *private_data,
                                      tvbparse_action_t before_cb,
                                      tvbparse_action_t after_cb,
                                      ...);
 
WS_DLL_PUBLIC
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,
                                   ...);
 
WS_DLL_PUBLIC
void tvbparse_hashed_add(tvbparse_wanted_t *w, ...);
 
WS_DLL_PUBLIC
tvbparse_wanted_t *tvbparse_set_seq(const int id,
                                    const void *private_data,
                                    tvbparse_action_t before_cb,
                                    tvbparse_action_t after_cb,
                                    ...);
 
WS_DLL_PUBLIC
tvbparse_wanted_t* tvbparse_some(const int id,
                                 const unsigned min,
                                 const unsigned max,
                                 const void* data,
                                 tvbparse_action_t before_cb,
                                 tvbparse_action_t after_cb,
                                 const tvbparse_wanted_t* wanted);
 
#define tvbparse_one_or_more(id, private_data, before_cb, after_cb, wanted)\
    tvbparse_some(id, 1, INT_MAX, private_data, before_cb, after_cb, wanted)
 
 
WS_DLL_PUBLIC
tvbparse_wanted_t* tvbparse_handle(tvbparse_wanted_t** handle);
 
WS_DLL_PUBLIC
tvbparse_wanted_t* tvbparse_quoted(const int id,
                                   const void* data,
                                   tvbparse_action_t before_cb,
                                   tvbparse_action_t after_cb,
                                   const char quote,
                                   const char escape);
 
/*
 * a helper callback for quoted strings that will shrink the token to contain
 * only the string and not the quotes
 */
WS_DLL_PUBLIC
void tvbparse_shrink_token_cb(void* tvbparse_data,
                              const void* wanted_data,
                              tvbparse_elem_t* tok);
 
 
 
 
WS_DLL_PUBLIC
tvbparse_t* tvbparse_init(wmem_allocator_t *scope,
                          tvbuff_t* tvb,
                          const int offset,
                          int len,
                          void* private_data,
                          const tvbparse_wanted_t* ignore);
 
WS_DLL_PUBLIC
bool tvbparse_reset(tvbparse_t* tt, const unsigned offset, unsigned len);
 
WS_DLL_PUBLIC
unsigned tvbparse_curr_offset(tvbparse_t* tt);
 
unsigned tvbparse_len_left(tvbparse_t* tt);
 
WS_DLL_PUBLIC
bool tvbparse_peek(tvbparse_t* tt,
                       const tvbparse_wanted_t* wanted);
 
WS_DLL_PUBLIC
tvbparse_elem_t* tvbparse_get(tvbparse_t* tt,
                              const tvbparse_wanted_t* wanted);
 
WS_DLL_PUBLIC
tvbparse_elem_t* tvbparse_find(tvbparse_t* tt,
                               const tvbparse_wanted_t* wanted);
 
WS_DLL_PUBLIC
void tvbparse_tree_add_elem(proto_tree* tree, tvbparse_elem_t* curr);