capchild/capture_sync.h

   1 /* capture_sync.h
   2  * Synchronisation between Wireshark capture parent and child instances
   3  *
   4  * Wireshark - Network traffic analyzer
   5  * By Gerald Combs <gerald@wireshark.org>
   6  * Copyright 1998 Gerald Combs
   7  *
   8  * SPDX-License-Identifier: GPL-2.0-or-later
   9  */
  10
  11
  12 /** @file
  13  *
  14  *  Sync mode capture (internal interface).
  15  *
  16  *  Will start a new Wireshark child instance which will do the actual capture
  17  *  work.
  18  */
  19
  20 #ifndef __CAPTURE_SYNC_H__
  21 #define __CAPTURE_SYNC_H__
  22
  23 #ifdef __cplusplus
  24 extern "C" {
  25 #endif /* __cplusplus */
  26
  27 struct _info_data;
  28
  29 /**
  30  * Start a new capture session.
  31  *  Create a capture child which is doing the real capture work.
  32  *  The various capture_input_... functions will be called, if something had
  33  *  happened.
  34  *
  35  *  Most of the parameters are passed through the global capture_opts.
  36  *
  37  *  @param capture_opts the options
  38  *  @param cap_session a handle for the capture session
  39  *  @param cap_data a struct with capture info data
  40  *  @param update_cb update screen
  41  *  @return             TRUE if a capture could be started, FALSE if not
  42  */
  43 extern gboolean
  44 sync_pipe_start(capture_options *capture_opts, capture_session *cap_session, struct _info_data* cap_data, void(*update_cb)(void));
  45
  46 /** User wants to stop capturing, gracefully close the capture child */
  47 extern void
  48 sync_pipe_stop(capture_session *cap_session);
  49
  50 /** User wants to stop the program, just kill the child as soon as possible */
  51 extern void
  52 sync_pipe_kill(ws_process_id fork_child);
  53
  54 /**
  55  * Set wireless channel using dumpcap
  56  *  On success, *data points to a buffer containing the dumpcap output,
  57  *  *primary_msg and *secondary_msg are NULL, and 0 is returned.  *data
  58  *  must be freed with g_free().
  59  *
  60  *  On failure, *data is NULL, *primary_msg points to an error message,
  61  *  *secondary_msg either points to an additional error message or is
  62  *  NULL, and -1 or errno value is returned; *primary_msg, and
  63  *  *secondary_msg if not NULL must be freed with g_free().
  64  *
  65  *  @param iface (monitor) network interface name
  66  *  @param freq channel control frequency string (in MHz)
  67  *  @param type channel type string (or NULL if not used)
  68  *  @param center_freq1 VHT channel center frequency (or NULL if not used)
  69  *  @param center_freq2 VHT channel center frequency 2 (or NULL if not used)
  70  *  @param data On success, *data points to a buffer containing the dumpcap output, On failure *data is NULL
  71  *  @param primary_msg On success NULL, On failure points to an error message
  72  *  @param secondary_msg On success NULL, On failure either points to an additional error message or is NULL
  73  *  @param update_cb
  74  *  @return 0 on success
  75  */
  76 extern int
  77 sync_interface_set_80211_chan(const gchar *iface, const char *freq, const gchar *type,
  78                               const gchar *center_freq1, const gchar *center_freq2,
  79                               gchar **data, gchar **primary_msg,
  80                               gchar **secondary_msg, void (*update_cb)(void));
  81
  82 /** Get an interface list using dumpcap */
  83 extern int
  84 sync_interface_list_open(gchar **data, gchar **primary_msg,
  85                          gchar **secondary_msg, void (*update_cb)(void));
  86
  87 /** Get interface capabilities using dumpcap */
  88 extern int
  89 sync_if_capabilities_open(const gchar *ifname, gboolean monitor_mode, const gchar* auth,
  90                           gchar **data, gchar **primary_msg,
  91                           gchar **secondary_msg, void (*update_cb)(void));
  92
  93 /** Start getting interface statistics using dumpcap. */
  94 extern int
  95 sync_interface_stats_open(int *read_fd, ws_process_id *fork_child, gchar **msg, void (*update_cb)(void));
  96
  97 /** Stop gathering statistics. */
  98 extern int
  99 sync_interface_stats_close(int *read_fd, ws_process_id *fork_child, gchar **msg);
 100
 101 /** Read a line from a pipe, similar to fgets.  Non-blocking. */
 102 extern int
 103 sync_pipe_gets_nonblock(int pipe_fd, char *bytes, int max);
 104
 105 /*
 106  * Routines supplied by our caller; we call them back to notify them
 107  * of various events.
 108  *
 109  * XXX - this is *really* ugly.  We should do this better.
 110  */
 111
 112 /**
 113  * Capture child told us we have a new (or the first) capture file.
 114  */
 115 extern gboolean
 116 capture_input_new_file(capture_session *cap_session, gchar *new_file);
 117
 118 /**
 119  * Capture child told us we have new packets to read.
 120  */
 121 extern void
 122 capture_input_new_packets(capture_session *cap_session, int to_read);
 123
 124 /**
 125  * Capture child told us how many dropped packets it counted.
 126  */
 127 extern void
 128 capture_input_drops(capture_session *cap_session, guint32 dropped, const char* interface_name);
 129
 130 /**
 131  * Capture child told us that an error has occurred while starting the capture.
 132  */
 133 extern void
 134 capture_input_error_message(capture_session *cap_session, char *error_msg,
 135                             char *secondary_error_msg);
 136
 137 /**
 138  * Capture child told us that an error has occurred while parsing a
 139  * capture filter when starting/running the capture.
 140  */
 141 extern void
 142 capture_input_cfilter_error_message(capture_session *cap_session, guint i,
 143                                     const char *error_message);
 144
 145 /**
 146  * Capture child closed its side of the pipe, report any error and
 147  * do the required cleanup.
 148  */
 149 extern void
 150 capture_input_closed(capture_session *cap_session, gchar *msg);
 151
 152 /* set a callback to be called after fork with the pid of the forked child */
 153 extern void capture_sync_set_fetch_dumpcap_pid_cb(void(*cb)(ws_process_id pid));
 154
 155 #ifdef __cplusplus
 156 }
 157 #endif /* __cplusplus */
 158
 159 #endif /* __CAPTURE_SYNC_H__ */