match declaration of cf_continue_tail() with implementation
[metze/wireshark/wip.git] / file.h
1 /* file.h
2  * Definitions for file structures and routines
3  *
4  * $Id$
5  *
6  * Wireshark - Network traffic analyzer
7  * By Gerald Combs <gerald@wireshark.org>
8  * Copyright 1998 Gerald Combs
9  *
10  * This program is free software; you can redistribute it and/or
11  * modify it under the terms of the GNU General Public License
12  * as published by the Free Software Foundation; either version 2
13  * of the License, or (at your option) any later version.
14  *
15  * This program is distributed in the hope that it will be useful,
16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
18  * GNU General Public License for more details.
19  *
20  * You should have received a copy of the GNU General Public License
21  * along with this program; if not, write to the Free Software
22  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
23  */
24
25 #ifndef __FILE_H__
26 #define __FILE_H__
27
28 #include "packet-range.h"
29 #include "wiretap/wtap.h"
30 #include <epan/dfilter/dfilter.h>
31 #include "print.h"
32 #include <errno.h>
33 #include <epan/epan.h>
34
35 #include "cfile.h"
36
37
38 /** Return values from functions that only can succeed or fail. */
39 typedef enum {
40         CF_OK,                      /**< operation succeeded */
41         CF_ERROR        /**< operation got an error (function may provide err with details) */
42 } cf_status_t;
43
44 /** Return values from functions that read capture files. */
45 typedef enum {
46         CF_READ_OK,             /**< operation succeeded */
47         CF_READ_ERROR,          /**< operation got an error (function may provide err with details) */
48         CF_READ_ABORTED         /**< operation aborted by user */
49 } cf_read_status_t;
50
51 /** Return values from functions that print sets of packets. */
52 typedef enum {
53         CF_PRINT_OK,                /**< print operation succeeded */
54         CF_PRINT_OPEN_ERROR,    /**< print operation failed while opening printer */
55         CF_PRINT_WRITE_ERROR    /**< print operation failed while writing to the printer */
56 } cf_print_status_t;
57
58 typedef enum {
59     cf_cb_file_closing,
60     cf_cb_file_closed,
61     cf_cb_file_read_start,
62     cf_cb_file_read_finished,
63 #ifdef HAVE_LIBPCAP
64     cf_cb_live_capture_prepared,
65     cf_cb_live_capture_update_started,
66     cf_cb_live_capture_update_continue,
67     cf_cb_live_capture_update_finished,
68     cf_cb_live_capture_fixed_started,
69     cf_cb_live_capture_fixed_continue,
70     cf_cb_live_capture_fixed_finished,
71         cf_cb_live_capture_stopping,
72 #endif
73     cf_cb_packet_selected,
74     cf_cb_packet_unselected,
75     cf_cb_field_unselected,
76     cf_cb_file_safe_started,
77     cf_cb_file_safe_finished,
78     cf_cb_file_safe_reload_finished,
79     cf_cb_file_safe_failed
80 } cf_cbs;
81
82 typedef void (*cf_callback_t) (gint event, gpointer data, gpointer user_data);
83
84 extern void
85 cf_callback_invoke(int event, gpointer data);
86
87 extern void
88 cf_callback_add(cf_callback_t func, gpointer user_data);
89
90 extern void
91 cf_callback_remove(cf_callback_t func);
92
93 /**
94  * Open a capture file.
95  *
96  * @param cf the capture file to be opened
97  * @param fname the filename to be opened
98  * @param is_tempfile is this a temporary file?
99  * @return one of cf_status_t
100  */
101 cf_status_t cf_open(capture_file *cf, const char *fname, gboolean is_tempfile, int *err);
102
103 /**
104  * Close a capture file.
105  *
106  * @param cf the capture file to be closed
107  */
108 void cf_close(capture_file *cf);
109
110 /**
111  * Reload a capture file.
112  *
113  * @param cf the capture file to be reloaded
114  */
115 void cf_reload(capture_file *cf);
116
117 /**
118  * Read all packets of a capture file into the internal structures.
119  * 
120  * @param cf the capture file to be read
121  * @return one of cf_read_status_t
122  */
123 cf_read_status_t cf_read(capture_file *cf);
124
125 /**
126  * Start reading from the end of a capture file.
127  * This is used in "Update list of packets in Real-Time".
128  * 
129  * @param cf the capture file to be read from
130  * @param fname the filename to be read from
131  * @param is_tempfile is this a temporary file?
132  * @param err the error code, if an error had occured
133  * @return one of cf_status_t
134  */
135 cf_status_t cf_start_tail(capture_file *cf, const char *fname, gboolean is_tempfile, int *err);
136
137 /**
138  * Read packets from the "end" of a capture file.
139  * 
140  * @param cf the capture file to be read from
141  * @param to_read the number of packets to read
142  * @param err the error code, if an error had occured
143  * @return one of cf_read_status_t
144  */
145 cf_read_status_t cf_continue_tail(capture_file *cf, volatile int to_read, int *err);
146
147 /**
148  * Finish reading from "end" of a capture file.
149  * 
150  * @param cf the capture file to be read from
151  * @param err the error code, if an error had occured
152  * @return one of cf_read_status_t
153  */
154 cf_read_status_t cf_finish_tail(capture_file *cf, int *err);
155
156 /**
157  * Determine whether this capture file (or a range of it) can be saved
158  * (except by copying the raw file data).
159  * 
160  * @param cf the capture file to check
161  * @return TRUE if it can be saved, FALSE if it can't
162  */
163 gboolean cf_can_save_as(capture_file *cf);
164
165 /**
166  * Save a capture file (or a range of it).
167  * 
168  * @param cf the capture file to save to
169  * @param fname the filename to save to
170  * @param range the range of packets to save
171  * @param save_format the format of the file to save (libpcap, ...)
172  * @param compressed wether to gzip compress the file
173  * @return one of cf_status_t
174  */
175 cf_status_t cf_save(capture_file * cf, const char *fname, packet_range_t *range, guint save_format, gboolean compressed);
176
177 /**
178  * Get a displayable name of the capture file.
179  * 
180  * @param cf the capture file
181  * @return the displayable name (don't have to be g_free'd)
182  */
183 const gchar *cf_get_display_name(capture_file *cf);
184
185 /**
186  * Get the number of packets in the capture file.
187  * 
188  * @param cf the capture file
189  * @return the number of packets in the capture file
190  */
191 int cf_get_packet_count(capture_file *cf);
192
193 /**
194  * Set the number of packets in the capture file.
195  * 
196  * @param cf the capture file
197  * @param the number of packets in the capture file
198  */
199 void cf_set_packet_count(capture_file *cf, int packet_count);
200
201 /**
202  * Is this capture file a temporary file?
203  * 
204  * @param cf the capture file
205  * @return TRUE if it's a temporary file, FALSE otherwise
206  */
207 gboolean cf_is_tempfile(capture_file *cf);
208
209 /**
210  * Set flag, that this file is a tempfile.
211  */
212 void cf_set_tempfile(capture_file *cf, gboolean is_tempfile);
213
214 /**
215  * Set flag, if the number of packet drops while capturing are known or not.
216  * 
217  * @param cf the capture file
218  * @param drops_known TRUE if the number of packet drops are known, FALSE otherwise
219  */
220 void cf_set_drops_known(capture_file *cf, gboolean drops_known);
221
222 /**
223  * Set the number of packet drops while capturing.
224  * 
225  * @param cf the capture file
226  * @param drops the number of packet drops occured while capturing
227  */
228 void cf_set_drops(capture_file *cf, guint32 drops);
229
230 /**
231  * Get flag state, if the number of packet drops while capturing are known or not.
232  * 
233  * @param cf the capture file
234  * @return TRUE if the number of packet drops are known, FALSE otherwise
235  */
236 gboolean cf_get_drops_known(capture_file *cf);
237
238 /**
239  * Get the number of packet drops while capturing.
240  * 
241  * @param cf the capture file
242  * @return the number of packet drops occured while capturing
243  */
244 guint32 cf_get_drops(capture_file *cf);
245
246 /**
247  * Set the read filter.
248  * @todo this shouldn't be required, remove it somehow
249  * 
250  * @param cf the capture file
251  * @param rfcode the readfilter
252  */
253 void cf_set_rfcode(capture_file *cf, dfilter_t *rfcode);
254
255 /**
256  * "Display Filter" packets in the capture file.
257  * 
258  * @param cf the capture file
259  * @param dfilter the display filter
260  * @param force TRUE if do in any case, FALSE only if dfilter changed
261  * @return one of cf_status_t
262  */
263 cf_status_t cf_filter_packets(capture_file *cf, gchar *dfilter, gboolean force);
264
265 /**
266  * At least one "Refence Time" flag has changed, rescan all packets.
267  * 
268  * @param cf the capture file
269  */
270 void cf_reftime_packets(capture_file *cf);
271
272 /**
273  * At least one "Refence Time" flag has changed, rescan all packets.
274  * 
275  * @param cf the capture file
276  */
277 void cf_colorize_packets(capture_file *cf);
278
279 /**
280  * "Something" has changed, rescan all packets.
281  * 
282  * @param cf the capture file
283  */
284 void cf_redissect_packets(capture_file *cf);
285
286 /**
287  * Rescan all packets and just run taps - don't reconstruct the display.
288  * 
289  * @param cf the capture file
290  * @param do_columns TRUE if columns are to be generated, FALSE otherwise
291  * @return one of cf_read_status_t
292  */
293 cf_read_status_t cf_retap_packets(capture_file *cf, gboolean do_columns);
294
295 /**
296  * The time format has changed, rescan all packets.
297  * 
298  * @param cf the capture file
299  */
300 void cf_change_time_formats(capture_file *cf);
301
302 /**
303  * Print the capture file.
304  * 
305  * @param cf the capture file
306  * @param print_args the arguments what and how to print
307  * @return one of cf_print_status_t
308  */
309 cf_print_status_t cf_print_packets(capture_file *cf, print_args_t *print_args);
310
311 /**
312  * Print (export) the capture file into PDML format.
313  * 
314  * @param cf the capture file
315  * @param print_args the arguments what and how to export
316  * @return one of cf_print_status_t
317  */
318 cf_print_status_t cf_write_pdml_packets(capture_file *cf, print_args_t *print_args);
319
320 /**
321  * Print (export) the capture file into PSML format.
322  * 
323  * @param cf the capture file
324  * @param print_args the arguments what and how to export
325  * @return one of cf_print_status_t
326  */
327 cf_print_status_t cf_write_psml_packets(capture_file *cf, print_args_t *print_args);
328
329 /**
330  * Print (export) the capture file into CSV format.
331  *
332  * @param cf the capture file
333  * @param print_args the arguments what and how to export
334  * @return one of cf_print_status_t
335  */
336 cf_print_status_t cf_write_csv_packets(capture_file *cf, print_args_t *print_args);
337
338 /**
339  * Find Packet in protocol tree.
340  * 
341  * @param cf the capture file
342  * @param string the string to find
343  * @return TRUE if a packet was found, FALSE otherwise
344  */
345 gboolean cf_find_packet_protocol_tree(capture_file *cf, const char *string);
346
347 /**
348  * Find Packet in summary line.
349  * 
350  * @param cf the capture file
351  * @param string the string to find
352  * @return TRUE if a packet was found, FALSE otherwise
353  */
354 gboolean cf_find_packet_summary_line(capture_file *cf, const char *string);
355
356 /**
357  * Find Packet in packet data.
358  * 
359  * @param cf the capture file
360  * @param string the string to find
361  * @param string_size the size of the string to find
362  * @return TRUE if a packet was found, FALSE otherwise
363  */
364 gboolean cf_find_packet_data(capture_file *cf, const guint8 *string,
365                           size_t string_size);
366
367 /**
368  * Find Packet by display filter.
369  * 
370  * @param cf the capture file
371  * @param sfcode the display filter to find a packet for
372  * @return TRUE if a packet was found, FALSE otherwise
373  */
374 gboolean cf_find_packet_dfilter(capture_file *cf, dfilter_t *sfcode);
375
376 /**
377  * GoTo Packet in first row.
378  * 
379  * @param cf the capture file
380  * @return TRUE if the first row exists, FALSE otherwise
381  */
382 gboolean cf_goto_top_frame(capture_file *cf);
383
384 /**
385  * GoTo Packet in last row.
386  * 
387  * @param cf the capture file
388  * @return TRUE if last row exists, FALSE otherwise
389  */
390 gboolean cf_goto_bottom_frame(capture_file *cf);
391
392 /**
393  * GoTo Packet with the given row.
394  * 
395  * @param cf the capture file
396  * @param row the row to go to
397  * @return TRUE if this row exists, FALSE otherwise
398  */
399 gboolean cf_goto_frame(capture_file *cf, guint row);
400
401 /**
402  * Go to frame specified by currently selected protocol tree field.
403  * (Go To Corresponding Packet)
404  * @todo this is ugly and should be improved!
405  *
406  * @param cf the capture file
407  * @return TRUE if this packet exists, FALSE otherwise
408  */
409 gboolean cf_goto_framenum(capture_file *cf);
410
411 /**
412  * Select the packet in the given row.
413  *
414  * @param cf the capture file
415  * @param row the row to select
416  */
417 void cf_select_packet(capture_file *cf, int row);
418
419 /**
420  * Unselect all packets, if any.
421  *
422  * @param cf the capture file
423  * @param row the row to select
424  */
425 void cf_unselect_packet(capture_file *cf);
426
427 /**
428  * Unselect all protocol tree fields, if any.
429  *
430  * @param cf the capture file
431  * @param row the row to select
432  */
433 void cf_unselect_field(capture_file *cf);
434
435 /**
436  * Mark a particular frame in a particular capture.
437  *
438  * @param cf the capture file
439  * @param frame the frame to be marked
440  */
441 void cf_mark_frame(capture_file *cf, frame_data *frame);
442
443 /**
444  * Unmark a particular frame in a particular capture.
445  *
446  * @param cf the capture file
447  * @param frame the frame to be unmarked
448  */
449 void cf_unmark_frame(capture_file *cf, frame_data *frame);
450
451 /**
452  * Convert error number and info to a complete message.
453  *
454  * @param err the error number
455  * @param err_info the additional info about this error (e.g. filename)
456  * @return statically allocated error message
457  */
458 char *cf_read_error_message(int err, const gchar *err_info);
459
460 /**
461  * Merge two (or more) capture files into one.
462  * @todo is this the right place for this function? It doesn't have to do a lot with capture_file.
463  *
464  * @param out_filename pointer to output filename; if output filename is
465  * NULL, a temporary file name is generated and *out_filename is set
466  * to point to the generated file name
467  * @param in_file_count the number of input files to merge
468  * @param in_filnames array of input filenames
469  * @param file_type the output filetype
470  * @param do_append FALSE to merge chronologically, TRUE simply append
471  * @return one of cf_status_t
472  */
473 cf_status_t
474 cf_merge_files(char **out_filename, int in_file_count,
475                char *const *in_filenames, int file_type, gboolean do_append);
476
477 #endif /* file.h */