epan/conversation_filter.h

   1 /* conversation_filter.h
   2  * Routines for dissector-generated conversation filters for use as
   3  * display and color filters
   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 __DISSECTOR_FILTERS_H__
  13 #define __DISSECTOR_FILTERS_H__
  14
  15 #include <glib.h>
  16
  17 #include "ws_symbol_export.h"
  18
  19 #ifdef __cplusplus
  20 extern "C" {
  21 #endif /* __cplusplus */
  22
  23 /** @file
  24  */
  25
  26 /** Initialize internal structures */
  27 extern void conversation_filters_init(void);
  28
  29 /**
  30  * Callback function which checks for filter availability.
  31  *
  32  * @param pinfo packet_info pointer for the current packet.
  33  * @param user_data User data provided to register_conversation_filter or register_log_conversation_filter.
  34  * @return true if the packet has a valid conversation filter, false otherwise.
  35  */
  36 typedef bool (*is_filter_valid_func)(struct _packet_info *pinfo, void *user_data);
  37
  38 /** callback function definition: return the available filter for this packet or NULL if no filter is available,
  39     Filter needs to be freed after use */
  40 /**
  41  * Callback function which creates a conversation filter.
  42  *
  43  * @param pinfo packet_info pointer for the current packet.
  44  * @param user_data User data provided to register_conversation_filter or register_log_conversation_filter.
  45  * @return A filter for the conversation on success, NULL on failure. The filter must be gfreed.
  46  */
  47 typedef char* (*build_filter_string_func)(struct _packet_info *pinfo, void *user_data);
  48
  49 /**
  50  * Register a new packet conversation filter.
  51  *
  52  * @param proto_name The protocol name.
  53  * @param display_name A friendly name for the filter.
  54  * @param is_filter_valid A callback function conforming to is_filter_valid_func.
  55  * @param build_filter_string A callback function conforming to build_filter_string_func.
  56  * @param user_data User-defined data which is passed to the callback functions. Can be NULL.
  57  */
  58 WS_DLL_PUBLIC void register_conversation_filter(const char *proto_name, const char *display_name,
  59                                                       is_filter_valid_func is_filter_valid, build_filter_string_func build_filter_string, void *user_data);
  60
  61 /**
  62  * Register a new log conversation filter.
  63  *
  64  * @param proto_name The protocol name.
  65  * @param display_name A friendly name for the filter.
  66  * @param is_filter_valid A callback function conforming to is_filter_valid_func.
  67  * @param build_filter_string A callback function conforming to build_filter_string_func.
  68  * @param user_data User-defined data which is passed to the callback functions. Can be NULL.
  69  */
  70 WS_DLL_PUBLIC void register_log_conversation_filter(const char *proto_name, const char *display_name,
  71                                                       is_filter_valid_func is_filter_valid, build_filter_string_func build_filter_string, void *user_data);
  72 /**
  73  * Prepend a protocol to the list of filterable protocols.
  74  * @param proto_name A valid protocol name.
  75  */
  76 WS_DLL_PUBLIC void add_conversation_filter_protocol(const char *proto_name);
  77
  78 /** Cleanup internal structures */
  79 extern void conversation_filters_cleanup(void);
  80
  81 /**
  82  * Tries to build a suitable display filter for the conversation in the current
  83  * packet. More specific matches are tried first (like TCP ports) followed by
  84  * less specific ones (IP addresses). NULL is returned when no filter is found.
  85  *
  86  * @param pinfo Packet info
  87  * @return A display filter for the conversation. Should be freed with g_free.
  88  */
  89 WS_DLL_PUBLIC char *conversation_filter_from_packet(struct _packet_info *pinfo);
  90
  91 /**
  92  * Tries to build a suitable display filter for the conversation in the current
  93  * log entry. More specific matches are tried first (like TCP ports) followed by
  94  * less specific ones (IP addresses). NULL is returned when no filter is found.
  95  *
  96  * @param pinfo Packet info
  97  * @return A display filter for the conversation. Should be freed with g_free.
  98  */
  99 WS_DLL_PUBLIC char *conversation_filter_from_log(struct _packet_info *pinfo);
 100
 101 /*** THE FOLLOWING SHOULD NOT BE USED BY ANY DISSECTORS!!! ***/
 102
 103 typedef struct conversation_filter_s {
 104     const char *              proto_name;
 105     const char *              display_name;
 106     is_filter_valid_func      is_filter_valid;
 107     build_filter_string_func  build_filter_string;
 108     void *                    user_data;
 109 } conversation_filter_t;
 110
 111 WS_DLL_PUBLIC GList *packet_conv_filter_list;
 112 WS_DLL_PUBLIC GList *log_conv_filter_list;
 113
 114 #ifdef __cplusplus
 115 }
 116 #endif /* __cplusplus */
 117
 118 #endif /* conversation_filter.h */