epan/dissectors/packet-xmpp-utils.h

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