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