epan/dissectors/packet-xmpp-utils.h

   1 /* xmpp-utils.h
   2  *
   3  * Copyright 2011, Mariusz Okroj <okrojmariusz[]gmail.com>
   4  *
   5  * Wireshark - Network traffic analyzer
   6  * By Gerald Combs <gerald@wireshark.org>
   7  * Copyright 1998 Gerald Combs
   8  *
   9  * SPDX-License-Identifier: GPL-2.0-or-later
  10  */
  11
  12 #ifndef XMPP_UTILS_H
  13 #define XMPP_UTILS_H
  14
  15 #include "ws_symbol_export.h"
  16 #include "tvbuff.h"
  17 #include "dissectors/packet-xml.h"
  18 #include <epan/wmem_scopes.h>
  19
  20 #define xmpp_elem_cdata(elem) \
  21 elem->data?elem->data->value:""
  22
  23 typedef struct _xmpp_array_t
  24 {
  25     void *data;
  26     int length;
  27 } xmpp_array_t;
  28
  29 typedef struct _xmpp_attr_t{
  30     const char *value;
  31     const char *name;
  32     int offset;
  33     int length;
  34
  35     bool was_read;
  36 } xmpp_attr_t;
  37
  38 typedef struct _xmpp_data_t{
  39     char *value;
  40
  41     int offset;
  42     int length;
  43 } xmpp_data_t;
  44
  45 typedef struct _xmpp_element_t{
  46     char* name;
  47
  48     /*abbreviation that apprears before tag name (<nos:x .../>)
  49      if abbrev doesn't appear then NULL*/
  50     char* default_ns_abbrev;
  51     /*pair of namespace abbrev and namespace*/
  52     GHashTable *namespaces;
  53
  54     GHashTable *attrs;
  55     GList *elements;
  56     xmpp_data_t *data;
  57
  58     int offset;
  59     int length;
  60
  61     bool was_read;
  62 } xmpp_element_t;
  63
  64 /*informations about attributes that are displayed in proto tree*/
  65 typedef struct _xmpp_attr_info{
  66     const char *name;
  67     const int *phf;
  68     bool is_required;
  69     bool in_short_list;
  70
  71     /*function validates this attribute
  72     it may impose other restrictions (e.g. validating attribute's name, ...)*/
  73     void (*val_func)(packet_info *pinfo, proto_item *item, const char *name, const char *value, const void *data);
  74     void *data;
  75 } xmpp_attr_info;
  76
  77 typedef struct _xmpp_attr_info_ext{
  78     const char* ns;
  79     xmpp_attr_info info;
  80 } xmpp_attr_info_ext;
  81
  82 typedef enum _xmpp_elem_info_type{
  83     NAME,
  84     ATTR,
  85     NAME_AND_ATTR,
  86     NAMES
  87 } xmpp_elem_info_type;
  88
  89 typedef enum _xmpp_elem_info_occurrence
  90 {
  91     ONE,MANY
  92 } xmpp_elem_info_occurrence;
  93
  94 /*informations about elements that are displayed in proto tree*/
  95 typedef struct _xmpp_elem_info{
  96     xmpp_elem_info_type type;
  97     const void *data;
  98     /*function that displays element in tree*/
  99     void (*elem_func)(proto_tree* tree, tvbuff_t* tvb, packet_info* pinfo, xmpp_element_t* element);
 100     xmpp_elem_info_occurrence occurrence;
 101 } xmpp_elem_info;
 102
 103 typedef struct _xmpp_conv_info_t {
 104     wmem_tree_t *req_resp;
 105     wmem_tree_t *jingle_sessions;
 106     wmem_tree_t *ibb_sessions;
 107     wmem_tree_t *gtalk_sessions;
 108     uint32_t     ssl_start;
 109 } xmpp_conv_info_t;
 110
 111 /** Struct conatins frame numbers (request frame(IQ set/get) and
 112  * response frame(IQ result/error)).
 113  */
 114 typedef struct _xmpp_reqresp_transaction_t {
 115     uint32_t req_frame;
 116     uint32_t resp_frame;
 117 } xmpp_transaction_t;
 118
 119 /** Function that is responsibe for request/response tracking in IQ packets.
 120  * Each IQ set/get packet should have the response in other IQ result/error packet.
 121  * Both packet should have the same id attribute. Function saves in wmem_tree pairs of
 122  * packet id and struct xmpp_transaction_t.
 123  */
 124 extern void xmpp_iq_reqresp_track(packet_info *pinfo, xmpp_element_t *packet, xmpp_conv_info_t *xmpp_info);
 125
 126 /** Function that is responsibe for jingle session tracking in IQ packets.
 127  * Function saves in wmem_tree pairs of packet's id and Jingle session's id.
 128  */
 129 extern void xmpp_jingle_session_track(packet_info *pinfo, xmpp_element_t *packet, xmpp_conv_info_t *xmpp_info);
 130
 131 /** Function that is responsibe for ibb(in band bytestreams) session tracking in IQ packets.
 132  * Function saves in wmem_tree pairs of packet's id and In-Band Bytestreams session's id.
 133  */
 134 extern void xmpp_ibb_session_track(packet_info *pinfo, xmpp_element_t *packet, xmpp_conv_info_t *xmpp_info);
 135
 136 /** Function that is responsibe for GTalk session(voice/video) tracking in IQ packets.
 137  * Function saves in wmem_tree pairs of packet's id and GTalk session's id.
 138  */
 139 extern void xmpp_gtalk_session_track(packet_info *pinfo, xmpp_element_t *packet, xmpp_conv_info_t *xmpp_info);
 140
 141 /** Function detects unrecognized elements and displays them in tree.
 142  * It uses ett_unknown to display packets. ett_unknown has const size described by
 143  * ETT_UNKNOWN_LEN in packet-xmpp.h
 144  */
 145 extern void xmpp_unknown(proto_tree *tree, tvbuff_t *tvb, packet_info *pinfo, xmpp_element_t *element);
 146
 147 /** Displays CDATA from element in tree. You can use your own header field hf or
 148  * pass -1. If you pass -1 then CDATA will be display as text:
 149  * ELEMENT_NAME: CDATA
 150  * ELEMENT_NAME = element->name, if element is empty CDATA = "(empty)"
 151  */
 152 extern void xmpp_cdata(proto_tree *tree, tvbuff_t *tvb, xmpp_element_t *element, int hf);
 153
 154 /** Function is similar to xmpp_cdata. But it display items only as a text and it is
 155  * compatibile with function display_elems
 156  */
 157 extern void xmpp_simple_cdata_elem(proto_tree *tree, tvbuff_t *tvb, packet_info *pinfo, xmpp_element_t *element);
 158
 159 /** Converts xml_frame_t struct to xmpp_element_t. Should be call with parent==NULL.
 160  */
 161 extern xmpp_element_t* xmpp_xml_frame_to_element_t(packet_info *pinfo, xml_frame_t *xml_frame, xmpp_element_t *parent, tvbuff_t *tvb);
 162
 163 /** Frees all GLib structs in xmpp_element_t struct. Should be call only for root element.
 164  * It works recursively.
 165  */
 166 extern void xmpp_element_t_tree_free(xmpp_element_t *root);
 167
 168 /** Allocs ephemeral memory for xmpp_array_t struct.*/
 169 extern xmpp_array_t* xmpp_ep_init_array_t(wmem_allocator_t *pool, const char** array, int len);
 170
 171 /*Allocs ephemeral memory for xmpp_attr_t struct*/
 172 extern xmpp_attr_t* xmpp_ep_init_attr_t(wmem_allocator_t *pool, const char *value, int offset, int length);
 173
 174 /** steal_*
 175  * Functions searches and marks as read found elements.
 176  * If element is set as read, it is invisible for these functions.*/
 177
 178 extern xmpp_element_t* xmpp_steal_element_by_name(xmpp_element_t *packet, const char *name);
 179 extern xmpp_element_t* xmpp_steal_element_by_names(xmpp_element_t *packet, const char **names, int names_len);
 180 extern xmpp_element_t* xmpp_steal_element_by_attr(xmpp_element_t *packet, const char *attr_name, const char *attr_value);
 181 extern xmpp_element_t* xmpp_steal_element_by_name_and_attr(xmpp_element_t *packet, const char *name, const char *attr_name, const char *attr_value);
 182
 183 /*Returns first child in element*/
 184 extern xmpp_element_t* xmpp_get_first_element(xmpp_element_t *packet);
 185
 186 /*Converts element to string. Returns memory allocated from the given pool.*/
 187 extern char* xmpp_element_to_string(wmem_allocator_t *pool, tvbuff_t *tvb, xmpp_element_t *element);
 188
 189 /* Returns attribute by name and set as read. If attrib is set as read, it may be found
 190  * one more time, but it is invisible for function xmpp_unknown_attrib*/
 191 extern xmpp_attr_t* xmpp_get_attr(xmpp_element_t *element, const char* attr_name);
 192
 193 /*Function hides first element in tree.*/
 194 extern void xmpp_proto_tree_hide_first_child(proto_tree *tree);
 195
 196 /*Function shows first element in tree.*/
 197 extern void xmpp_proto_tree_show_first_child(proto_tree *tree);
 198
 199 /*Function returns item as text. Memory is allocated from the given pool.*/
 200 extern char* proto_item_get_text(wmem_allocator_t *pool, proto_item *item);
 201
 202 /*Function returns struct that contains 3 strings. It is used to build xmpp_attr_info struct.*/
 203 extern void *xmpp_name_attr_struct(wmem_allocator_t *pool, const char *name, const char *attr_name, const char *attr_value);
 204
 205 /** Function displays attributes from element in way described in attrs.
 206  * Elements that doesn't exist in attrs are displayed as text.
 207  * In XMPP_ATTR_INFO struct you can define several things:
 208  * - is_in_short_list - attribute should be displayed in short list e.g. ELEMENT_NAME [ATTR1='value' ATTR2='value']
 209  * - is_required - attribute is required. If attribute doesn't appear then EXPERT INFO will be displayed
 210  * - val_func - validate function
 211  * - data - data passes to the val_func
 212  */
 213 extern void xmpp_display_attrs(proto_tree *tree, xmpp_element_t *element, packet_info *pinfo, tvbuff_t *tvb, const xmpp_attr_info *attrs, unsigned n);
 214
 215 /** Function does the same as shown above. It takes attrs(XMPP_ATTR_INFO_EXT) argument
 216  * that contains XMPP_ATTR_INFO struct and string with namespace. It is used when packet
 217  * contains several namespaces and each attribute belongs to particular namespace.
 218  * E.g.
 219  * @code
 220  * <auth xmlns='urn:ietf:params:xml:ns:xmpp-sasl'
 221  *  mechanism='PLAIN'
 222  *  xmlns:ga='http://www.google.com/talk/protocol/auth'
 223  *  ga:client-uses-full-bind-result='true'>
 224  * </auth>
 225  * @endcode
 226  */
 227 extern void xmpp_display_attrs_ext(proto_tree *tree, xmpp_element_t *element, packet_info *pinfo, tvbuff_t *tvb, const xmpp_attr_info_ext *attrs, unsigned n);
 228
 229 /** Displays elements from parent element in a way described in elems(XMPP_ELEM_INFO).
 230  * XMPP_ELEM_INFO describes how to find particular element and what action should be done
 231  * for this element.
 232  * Function calls xmpp_unknown.
 233  */
 234 extern void xmpp_display_elems(proto_tree *tree, xmpp_element_t *parent, packet_info *pinfo, tvbuff_t *tvb, xmpp_elem_info *elems, unsigned n);
 235
 236 /* Validates attribute value. Takes string array(char**) in parameter data.
 237  * Is used in XMPP_ATTR_INFO struct.
 238  */
 239 extern void xmpp_val_enum_list(packet_info *pinfo, proto_item *item, const char *name, const char *value, const void *data);
 240
 241 /** Function changes element to attribute. It searches element by name in parent element,
 242  * next it create attribute using transform_func and inserts it to parent attributes hash table
 243  * using attr_name as key.
 244  */
 245 extern void xmpp_change_elem_to_attrib(wmem_allocator_t *pool, const char *elem_name, const char *attr_name, xmpp_element_t *parent, xmpp_attr_t* (*transform_func)(wmem_allocator_t *pool, xmpp_element_t *element));
 246
 247 /** transform_func that creates attribute with element's cdata as value
 248  */
 249 extern xmpp_attr_t* xmpp_transform_func_cdata(wmem_allocator_t *pool, xmpp_element_t *elem);
 250
 251 #endif /* XMPP_UTILS_H */