Distinguish between "failed" and "user stopped it" for "save as" and
[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 #ifdef __cplusplus
38 extern "C" {
39 #endif /* __cplusplus */
40
41 /** Return values from functions that only can succeed or fail. */
42 typedef enum {
43     CF_OK,      /**< operation succeeded */
44     CF_ERROR    /**< operation got an error (function may provide err with details) */
45 } cf_status_t;
46
47 /** Return values from functions that read capture files. */
48 typedef enum {
49     CF_READ_OK,      /**< operation succeeded */
50     CF_READ_ERROR,   /**< operation got an error (function may provide err with details) */
51     CF_READ_ABORTED  /**< operation aborted by user */
52 } cf_read_status_t;
53
54 /** Return values from functions that write out packets. */
55 typedef enum {
56     CF_WRITE_OK,      /**< operation succeeded */
57     CF_WRITE_ERROR,   /**< operation got an error (function may provide err with details) */
58     CF_WRITE_ABORTED, /**< operation aborted by user */
59 } cf_write_status_t;
60
61 /** Return values from functions that print sets of packets. */
62 typedef enum {
63         CF_PRINT_OK,            /**< print operation succeeded */
64         CF_PRINT_OPEN_ERROR,    /**< print operation failed while opening printer */
65         CF_PRINT_WRITE_ERROR    /**< print operation failed while writing to the printer */
66 } cf_print_status_t;
67
68 typedef enum {
69     cf_cb_file_closing,
70     cf_cb_file_closed,
71     cf_cb_file_read_started,
72     cf_cb_file_read_finished,
73     cf_cb_file_reload_started,
74     cf_cb_file_reload_finished,
75     cf_cb_packet_selected,
76     cf_cb_packet_unselected,
77     cf_cb_field_unselected,
78     cf_cb_file_save_started,
79     cf_cb_file_save_finished,
80     cf_cb_file_save_failed,
81     cf_cb_file_save_stopped,
82     cf_cb_file_export_specified_packets_started,
83     cf_cb_file_export_specified_packets_finished,
84     cf_cb_file_export_specified_packets_failed,
85     cf_cb_file_export_specified_packets_stopped
86 } cf_cbs;
87
88 typedef void (*cf_callback_t) (gint event, gpointer data, gpointer user_data);
89
90 typedef struct {
91     const char    *string;
92     size_t         string_len;
93     capture_file  *cf;
94     gboolean       frame_matched;
95     field_info    *finfo;
96 } match_data;
97
98 extern void
99 cf_callback_add(cf_callback_t func, gpointer user_data);
100
101 extern void
102 cf_callback_remove(cf_callback_t func);
103
104 /**
105  * Open a capture file.
106  *
107  * @param cf the capture file to be opened
108  * @param fname the filename to be opened
109  * @param is_tempfile is this a temporary file?
110  * @param err error code
111  * @return one of cf_status_t
112  */
113 cf_status_t cf_open(capture_file *cf, const char *fname, gboolean is_tempfile, int *err);
114
115 /**
116  * Close a capture file.
117  *
118  * @param cf the capture file to be closed
119  */
120 void cf_close(capture_file *cf);
121
122 /**
123  * Reload a capture file.
124  *
125  * @param cf the capture file to be reloaded
126  */
127 void cf_reload(capture_file *cf);
128
129 /**
130  * Read all packets of a capture file into the internal structures.
131  *
132  * @param cf the capture file to be read
133  * @param from_save reread asked from cf_save_packets
134  * @return one of cf_read_status_t
135  */
136 cf_read_status_t cf_read(capture_file *cf, gboolean from_save);
137
138 /**
139  * Read the pseudo-header and raw data for a packet.  It will pop
140  * up an alert box if there's an error.
141  *
142  * @param cf the capture file from which to read the packet
143  * @param fdata the frame_data structure for the packet in question
144  * @param pseudo_header pointer to a wtap_pseudo_header union into
145  * which to read the packet's pseudo-header
146  * @param pd a guin8 array into which to read the packet's raw data
147  * @return TRUE if the read succeeded, FALSE if there was an error
148  */
149 gboolean cf_read_frame_r(capture_file *cf, frame_data *fdata,
150                          union wtap_pseudo_header *pseudo_header, guint8 *pd);
151
152 /**
153  * Read the pseudo-header and raw data for a packet into a
154  * capture_file structure's pseudo_header and pd members.
155  * It will pop up an alert box if there's an error.
156  *
157  * @param cf the capture file from which to read the packet
158  * @param fdata the frame_data structure for the packet in question
159  * @return TRUE if the read succeeded, FALSE if there was an error
160  */
161 gboolean cf_read_frame(capture_file *cf, frame_data *fdata);
162
163 /**
164  * Start reading from the end of a capture file.
165  * This is used in "Update list of packets in Real-Time".
166  *
167  * @param cf the capture file to be read from
168  * @param fname the filename to be read from
169  * @param is_tempfile is this a temporary file?
170  * @param err the error code, if an error had occured
171  * @return one of cf_status_t
172  */
173 cf_status_t cf_start_tail(capture_file *cf, const char *fname, gboolean is_tempfile, int *err);
174
175 /**
176  * Read packets from the "end" of a capture file.
177  *
178  * @param cf the capture file to be read from
179  * @param to_read the number of packets to read
180  * @param err the error code, if an error had occured
181  * @return one of cf_read_status_t
182  */
183 cf_read_status_t cf_continue_tail(capture_file *cf, volatile int to_read, int *err);
184
185 /**
186  * Fake reading packets from the "end" of a capture file.
187  *
188  * @param cf the capture file to be read from
189  */
190 void cf_fake_continue_tail(capture_file *cf);
191
192 /**
193  * Finish reading from "end" of a capture file.
194  *
195  * @param cf the capture file to be read from
196  * @param err the error code, if an error had occured
197  * @return one of cf_read_status_t
198  */
199 cf_read_status_t cf_finish_tail(capture_file *cf, int *err);
200
201 /**
202  * Determine whether this capture file (or a range of it) can be saved
203  * (except by copying the raw file data).
204  *
205  * @param cf the capture file to check
206  * @return TRUE if it can be saved, FALSE if it can't
207  */
208 gboolean cf_can_save_as(capture_file *cf);
209
210 /**
211  * Save all packets in a capture file to a new file, and, if that succeeds,
212  * make that file the current capture file.  If there's already a file with
213  * that name, do a "safe save", writing to a temporary file in the same
214  * directory and, if the write succeeds, renaming the new file on top of the
215  * old file, so that if the write fails, the old file is still intact.
216  *
217  * @param cf the capture file to save to
218  * @param fname the filename to save to
219  * @param save_format the format of the file to save (libpcap, ...)
220  * @param compressed whether to gzip compress the file
221  * @param dont_reopen TRUE if it shouldn't reopen and make that file the
222  * current capture file
223  * @return one of cf_write_status_t
224  */
225 cf_write_status_t cf_save_packets(capture_file * cf, const char *fname,
226                                   guint save_format, gboolean compressed,
227                                   gboolean dont_reopen);
228
229 /**
230  * Export some or all packets from a capture file to a new file.  If there's
231  * already a file with that name, do a "safe save", writing to a temporary
232  * file in the same directory and, if the write succeeds, renaming the new
233  * file on top of the old file, so that if the write fails, the old file is
234  * still intact.
235  *
236  * @param cf the capture file to write to
237  * @param fname the filename to write to
238  * @param range the range of packets to write
239  * @param save_format the format of the file to write (libpcap, ...)
240  * @param compressed whether to gzip compress the file
241  * @return one of cf_write_status_t
242  */
243 cf_write_status_t cf_export_specified_packets(capture_file *cf,
244                                               const char *fname,
245                                               packet_range_t *range,
246                                               guint save_format,
247                                               gboolean compressed);
248
249 /**
250  * Get a displayable name of the capture file.
251  *
252  * @param cf the capture file
253  * @return the displayable name (must be g_free'd)
254  */
255 gchar *cf_get_display_name(capture_file *cf);
256
257 /**
258  * Set the source of the capture data for temporary files, e.g.
259  * "Interface eth0" or "Pipe from Pong"
260  *
261  * @param cf the capture file
262  * @param source the source description. this will be copied internally.
263  */
264 void cf_set_tempfile_source(capture_file *cf, gchar *source);
265
266 /**
267  * Get the source of the capture data for temporary files. Guaranteed to
268  * return a non-null value. The returned value should not be freed.
269  *
270  * @param cf the capture file
271  */
272 const gchar *cf_get_tempfile_source(capture_file *cf);
273
274 /**
275  * Get the number of packets in the capture file.
276  *
277  * @param cf the capture file
278  * @return the number of packets in the capture file
279  */
280 int cf_get_packet_count(capture_file *cf);
281
282 /**
283  * Set the number of packets in the capture file.
284  *
285  * @param cf the capture file
286  * @param packet_count the number of packets in the capture file
287  */
288 void cf_set_packet_count(capture_file *cf, int packet_count);
289
290 /**
291  * Is this capture file a temporary file?
292  *
293  * @param cf the capture file
294  * @return TRUE if it's a temporary file, FALSE otherwise
295  */
296 gboolean cf_is_tempfile(capture_file *cf);
297
298 /**
299  * Set flag, that this file is a tempfile.
300  */
301 void cf_set_tempfile(capture_file *cf, gboolean is_tempfile);
302
303 /**
304  * Set flag, if the number of packet drops while capturing are known or not.
305  *
306  * @param cf the capture file
307  * @param drops_known TRUE if the number of packet drops are known, FALSE otherwise
308  */
309 void cf_set_drops_known(capture_file *cf, gboolean drops_known);
310
311 /**
312  * Set the number of packet drops while capturing.
313  *
314  * @param cf the capture file
315  * @param drops the number of packet drops occured while capturing
316  */
317 void cf_set_drops(capture_file *cf, guint32 drops);
318
319 /**
320  * Get flag state, if the number of packet drops while capturing are known or not.
321  *
322  * @param cf the capture file
323  * @return TRUE if the number of packet drops are known, FALSE otherwise
324  */
325 gboolean cf_get_drops_known(capture_file *cf);
326
327 /**
328  * Get the number of packet drops while capturing.
329  *
330  * @param cf the capture file
331  * @return the number of packet drops occured while capturing
332  */
333 guint32 cf_get_drops(capture_file *cf);
334
335 /**
336  * Set the read filter.
337  * @todo this shouldn't be required, remove it somehow
338  *
339  * @param cf the capture file
340  * @param rfcode the readfilter
341  */
342 void cf_set_rfcode(capture_file *cf, dfilter_t *rfcode);
343
344 /**
345  * "Display Filter" packets in the capture file.
346  *
347  * @param cf the capture file
348  * @param dfilter the display filter
349  * @param force TRUE if do in any case, FALSE only if dfilter changed
350  * @return one of cf_status_t
351  */
352 cf_status_t cf_filter_packets(capture_file *cf, gchar *dfilter, gboolean force);
353
354 /**
355  * At least one "Refence Time" flag has changed, rescan all packets.
356  *
357  * @param cf the capture file
358  */
359 void cf_reftime_packets(capture_file *cf);
360
361 /**
362  * Return the time it took to load the file
363  */
364 gulong cf_get_computed_elapsed(void);
365
366 /**
367  * "Something" has changed, rescan all packets.
368  *
369  * @param cf the capture file
370  */
371 void cf_redissect_packets(capture_file *cf);
372
373 /**
374  * Rescan all packets and just run taps - don't reconstruct the display.
375  *
376  * @param cf the capture file
377  * @return one of cf_read_status_t
378  */
379 cf_read_status_t cf_retap_packets(capture_file *cf);
380
381 /**
382  * Adjust timestamp precision if auto is selected.
383  *
384  * @param cf the capture file
385  */
386 void cf_timestamp_auto_precision(capture_file *cf);
387
388 /**
389  * Print the capture file.
390  *
391  * @param cf the capture file
392  * @param print_args the arguments what and how to print
393  * @return one of cf_print_status_t
394  */
395 cf_print_status_t cf_print_packets(capture_file *cf, print_args_t *print_args);
396
397 /**
398  * Print (export) the capture file into PDML format.
399  *
400  * @param cf the capture file
401  * @param print_args the arguments what and how to export
402  * @return one of cf_print_status_t
403  */
404 cf_print_status_t cf_write_pdml_packets(capture_file *cf, print_args_t *print_args);
405
406 /**
407  * Print (export) the capture file into PSML format.
408  *
409  * @param cf the capture file
410  * @param print_args the arguments what and how to export
411  * @return one of cf_print_status_t
412  */
413 cf_print_status_t cf_write_psml_packets(capture_file *cf, print_args_t *print_args);
414
415 /**
416  * Print (export) the capture file into CSV format.
417  *
418  * @param cf the capture file
419  * @param print_args the arguments what and how to export
420  * @return one of cf_print_status_t
421  */
422 cf_print_status_t cf_write_csv_packets(capture_file *cf, print_args_t *print_args);
423
424 /**
425  * Print (export) the capture file into C Arrays format.
426  *
427  * @param cf the capture file
428  * @param print_args the arguments what and how to export
429  * @return one of cf_print_status_t
430  */
431 cf_print_status_t cf_write_carrays_packets(capture_file *cf, print_args_t *print_args);
432
433 /**
434  * Find packet with a protocol tree item that contains a specified text string.
435  *
436  * @param cf the capture file
437  * @param string the string to find
438  * @param dir direction in which to search
439  * @return TRUE if a packet was found, FALSE otherwise
440  */
441 gboolean cf_find_packet_protocol_tree(capture_file *cf, const char *string,
442                                       search_direction dir);
443
444 /**
445  * Find field with a label that contains text string cfile->sfilter.
446  *
447  * @param cf the capture file
448  * @param tree the protocol tree
449  * @param mdata the first field (mdata->finfo) that matched the string
450  * @return TRUE if a packet was found, FALSE otherwise
451  */
452 extern gboolean cf_find_string_protocol_tree(capture_file *cf, proto_tree *tree,
453                                              match_data *mdata);
454
455 /**
456  * Find packet whose summary line contains a specified text string.
457  *
458  * @param cf the capture file
459  * @param string the string to find
460  * @param dir direction in which to search
461  * @return TRUE if a packet was found, FALSE otherwise
462  */
463 gboolean cf_find_packet_summary_line(capture_file *cf, const char *string,
464                                      search_direction dir);
465
466 /**
467  * Find packet whose data contains a specified byte string.
468  *
469  * @param cf the capture file
470  * @param string the string to find
471  * @param string_size the size of the string to find
472  * @param dir direction in which to search
473  * @return TRUE if a packet was found, FALSE otherwise
474  */
475 gboolean cf_find_packet_data(capture_file *cf, const guint8 *string,
476                              size_t string_size, search_direction dir);
477
478 /**
479  * Find packet that matches a compiled display filter.
480  *
481  * @param cf the capture file
482  * @param sfcode the display filter to match
483  * @param dir direction in which to search
484  * @return TRUE if a packet was found, FALSE otherwise
485  */
486 gboolean cf_find_packet_dfilter(capture_file *cf, dfilter_t *sfcode,
487                                 search_direction dir);
488
489 /**
490  * Find packet that matches a display filter given as a text string.
491  *
492  * @param cf the capture file
493  * @param filter the display filter to match
494  * @param dir direction in which to search
495  * @return TRUE if a packet was found, FALSE otherwise
496  */
497 gboolean
498 cf_find_packet_dfilter_string(capture_file *cf, const char *filter,
499                               search_direction dir);
500
501 /**
502  * Find marked packet.
503  *
504  * @param cf the capture file
505  * @param dir direction in which to search
506  * @return TRUE if a packet was found, FALSE otherwise
507  */
508 gboolean cf_find_packet_marked(capture_file *cf, search_direction dir);
509
510 /**
511  * Find time-reference packet.
512  *
513  * @param cf the capture file
514  * @param dir direction in which to search
515  * @return TRUE if a packet was found, FALSE otherwise
516  */
517 gboolean cf_find_packet_time_reference(capture_file *cf, search_direction dir);
518
519 /**
520  * GoTo Packet in first row.
521  *
522  * @return TRUE if the first row exists, FALSE otherwise
523  */
524 gboolean cf_goto_top_frame(void);
525
526 /**
527  * GoTo Packet in last row.
528  *
529  * @return TRUE if last row exists, FALSE otherwise
530  */
531 gboolean cf_goto_bottom_frame(void);
532
533 /**
534  * GoTo Packet with the given row.
535  *
536  * @param cf the capture file
537  * @param row the row to go to
538  * @return TRUE if this row exists, FALSE otherwise
539  */
540 gboolean cf_goto_frame(capture_file *cf, guint row);
541
542 /**
543  * Go to frame specified by currently selected protocol tree field.
544  * (Go To Corresponding Packet)
545  * @todo this is ugly and should be improved!
546  *
547  * @param cf the capture file
548  * @return TRUE if this packet exists, FALSE otherwise
549  */
550 gboolean cf_goto_framenum(capture_file *cf);
551
552 /**
553  * Select the packet in the given row.
554  *
555  * @param cf the capture file
556  * @param row the row to select
557  */
558 void cf_select_packet(capture_file *cf, int row);
559
560 /**
561  * Unselect all packets, if any.
562  *
563  * @param cf the capture file
564  */
565 void cf_unselect_packet(capture_file *cf);
566
567 /**
568  * Unselect all protocol tree fields, if any.
569  *
570  * @param cf the capture file
571  */
572 void cf_unselect_field(capture_file *cf);
573
574 /**
575  * Mark a particular frame in a particular capture.
576  *
577  * @param cf the capture file
578  * @param frame the frame to be marked
579  */
580 void cf_mark_frame(capture_file *cf, frame_data *frame);
581
582 /**
583  * Unmark a particular frame in a particular capture.
584  *
585  * @param cf the capture file
586  * @param frame the frame to be unmarked
587  */
588 void cf_unmark_frame(capture_file *cf, frame_data *frame);
589
590 /**
591  * Ignore a particular frame in a particular capture.
592  *
593  * @param cf the capture file
594  * @param frame the frame to be ignored
595  */
596 void cf_ignore_frame(capture_file *cf, frame_data *frame);
597
598 /**
599  * Unignore a particular frame in a particular capture.
600  *
601  * @param cf the capture file
602  * @param frame the frame to be unignored
603  */
604 void cf_unignore_frame(capture_file *cf, frame_data *frame);
605
606 /**
607  * Merge two (or more) capture files into one.
608  * @todo is this the right place for this function? It doesn't have to do a lot with capture_file.
609  *
610  * @param out_filename pointer to output filename; if output filename is
611  * NULL, a temporary file name is generated and *out_filename is set
612  * to point to the generated file name
613  * @param in_file_count the number of input files to merge
614  * @param in_filenames array of input filenames
615  * @param file_type the output filetype
616  * @param do_append FALSE to merge chronologically, TRUE simply append
617  * @return one of cf_status_t
618  */
619 cf_status_t
620 cf_merge_files(char **out_filename, int in_file_count,
621                char *const *in_filenames, int file_type, gboolean do_append);
622
623
624 /**
625  * Get the comment on a capture from the SHB data block
626  *
627  * @param cf the capture file
628  */
629 const gchar* cf_read_shb_comment(capture_file *cf);
630
631 /**
632  * Update(replace) the comment on a capture from the SHB data block
633  *
634  * @param cf the capture file
635  * @param comment the string replacing the old comment
636  */
637 void cf_update_capture_comment(capture_file *cf, gchar *comment);
638
639
640 #if defined(HAVE_HEIMDAL_KERBEROS) || defined(HAVE_MIT_KERBEROS)
641 void read_keytab_file(const char *);
642 #endif
643
644 #ifdef __cplusplus
645 }
646 #endif /* __cplusplus */
647
648 #endif /* file.h */