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