090528654b143cc7f0e7dd590958274579e54cbd
[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 compressed whether to gzip compress the file
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, gboolean compressed,
247                                   gboolean discard_comments,
248                                   gboolean dont_reopen);
249
250 /**
251  * Export some or all packets from a capture file to a new file.  If there's
252  * already a file with that name, do a "safe save", writing to a temporary
253  * file in the same directory and, if the write succeeds, renaming the new
254  * file on top of the old file, so that if the write fails, the old file is
255  * still intact.
256  *
257  * @param cf the capture file to write to
258  * @param fname the filename to write to
259  * @param range the range of packets to write
260  * @param save_format the format of the file to write (libpcap, ...)
261  * @param compressed whether to gzip compress the file
262  * @return one of cf_write_status_t
263  */
264 cf_write_status_t cf_export_specified_packets(capture_file *cf,
265                                               const char *fname,
266                                               packet_range_t *range,
267                                               guint save_format,
268                                               gboolean compressed);
269
270 /**
271  * Get a displayable name of the capture file.
272  *
273  * @param cf the capture file
274  * @return the displayable name (must be g_free'd)
275  */
276 gchar *cf_get_display_name(capture_file *cf);
277
278 /**
279  * Get a name that can be used to generate a file name from the
280  * capture file name.  It's based on the displayable name, so it's
281  * UTF-8; if it ends with a suffix that's used by a file type libwiretap
282  * can read, we strip that suffix off.
283  *
284  * @param cf the capture file
285  * @return the base name (must be g_free'd)
286  */
287 gchar *cf_get_basename(capture_file *cf);
288
289 /**
290  * Set the source of the capture data for temporary files, e.g.
291  * "Interface eth0" or "Pipe from Pong"
292  *
293  * @param cf the capture file
294  * @param source the source description. this will be copied internally.
295  */
296 void cf_set_tempfile_source(capture_file *cf, gchar *source);
297
298 /**
299  * Get the source of the capture data for temporary files. Guaranteed to
300  * return a non-null value. The returned value should not be freed.
301  *
302  * @param cf the capture file
303  */
304 const gchar *cf_get_tempfile_source(capture_file *cf);
305
306 /**
307  * Get the number of packets in the capture file.
308  *
309  * @param cf the capture file
310  * @return the number of packets in the capture file
311  */
312 int cf_get_packet_count(capture_file *cf);
313
314 /**
315  * Is this capture file a temporary file?
316  *
317  * @param cf the capture file
318  * @return TRUE if it's a temporary file, FALSE otherwise
319  */
320 gboolean cf_is_tempfile(capture_file *cf);
321
322 /**
323  * Set flag, that this file is a tempfile.
324  */
325 void cf_set_tempfile(capture_file *cf, gboolean is_tempfile);
326
327 /**
328  * Set flag, if the number of packet drops while capturing are known or not.
329  *
330  * @param cf the capture file
331  * @param drops_known TRUE if the number of packet drops are known, FALSE otherwise
332  */
333 void cf_set_drops_known(capture_file *cf, gboolean drops_known);
334
335 /**
336  * Set the number of packet drops while capturing.
337  *
338  * @param cf the capture file
339  * @param drops the number of packet drops occurred while capturing
340  */
341 void cf_set_drops(capture_file *cf, guint32 drops);
342
343 /**
344  * Get flag state, if the number of packet drops while capturing are known or not.
345  *
346  * @param cf the capture file
347  * @return TRUE if the number of packet drops are known, FALSE otherwise
348  */
349 gboolean cf_get_drops_known(capture_file *cf);
350
351 /**
352  * Get the number of packet drops while capturing.
353  *
354  * @param cf the capture file
355  * @return the number of packet drops occurred while capturing
356  */
357 guint32 cf_get_drops(capture_file *cf);
358
359 /**
360  * Set the read filter.
361  * @todo this shouldn't be required, remove it somehow
362  *
363  * @param cf the capture file
364  * @param rfcode the readfilter
365  */
366 void cf_set_rfcode(capture_file *cf, dfilter_t *rfcode);
367
368 /**
369  * "Display Filter" packets in the capture file.
370  *
371  * @param cf the capture file
372  * @param dfilter the display filter
373  * @param force TRUE if do in any case, FALSE only if dfilter changed
374  * @return one of cf_status_t
375  */
376 cf_status_t cf_filter_packets(capture_file *cf, gchar *dfilter, gboolean force);
377
378 /**
379  * At least one "Refence Time" flag has changed, rescan all packets.
380  *
381  * @param cf the capture file
382  */
383 void cf_reftime_packets(capture_file *cf);
384
385 /**
386  * Return the time it took to load the file (in msec).
387  */
388 gulong cf_get_computed_elapsed(capture_file *cf);
389
390 /**
391  * "Something" has changed, rescan all packets.
392  *
393  * @param cf the capture file
394  */
395 void cf_redissect_packets(capture_file *cf);
396
397 /**
398  * Rescan all packets and just run taps - don't reconstruct the display.
399  *
400  * @param cf the capture file
401  * @return one of cf_read_status_t
402  */
403 cf_read_status_t cf_retap_packets(capture_file *cf);
404
405 /**
406  * Adjust timestamp precision if auto is selected.
407  *
408  * @param cf the capture file
409  */
410 void cf_timestamp_auto_precision(capture_file *cf);
411
412 /* print_range, enum which frames should be printed */
413 typedef enum {
414     print_range_selected_only,    /* selected frame(s) only (currently only one) */
415     print_range_marked_only,      /* marked frames only */
416     print_range_all_displayed,    /* all frames currently displayed */
417     print_range_all_captured      /* all frames in capture */
418 } print_range_e;
419
420 typedef struct {
421     print_stream_t *stream;       /* the stream to which we're printing */
422     print_format_e format;        /* plain text or PostScript */
423     gboolean to_file;             /* TRUE if we're printing to a file */
424     char *file;                   /* file output pathname */
425     char *cmd;                    /* print command string (not win32) */
426     packet_range_t range;
427
428     gboolean print_summary;       /* TRUE if we should print summary line. */
429     gboolean print_col_headings;  /* TRUE if we should print column headings */
430     print_dissections_e print_dissections;
431     gboolean print_hex;           /* TRUE if we should print hex data;
432                                    * FALSE if we should print only if not dissected. */
433     gboolean print_formfeed;      /* TRUE if a formfeed should be printed before
434                                    * each new packet */
435 } print_args_t;
436
437 /**
438  * Print the capture file.
439  *
440  * @param cf the capture file
441  * @param print_args the arguments what and how to print
442  * @param show_progress_bar TRUE if a progress bar is to be shown
443  * @return one of cf_print_status_t
444  */
445 cf_print_status_t cf_print_packets(capture_file *cf, print_args_t *print_args,
446                                    gboolean show_progress_bar);
447
448 /**
449  * Print (export) the capture file into PDML format.
450  *
451  * @param cf the capture file
452  * @param print_args the arguments what and how to export
453  * @return one of cf_print_status_t
454  */
455 cf_print_status_t cf_write_pdml_packets(capture_file *cf, print_args_t *print_args);
456
457 /**
458  * Print (export) the capture file into PSML format.
459  *
460  * @param cf the capture file
461  * @param print_args the arguments what and how to export
462  * @return one of cf_print_status_t
463  */
464 cf_print_status_t cf_write_psml_packets(capture_file *cf, print_args_t *print_args);
465
466 /**
467  * Print (export) the capture file into CSV format.
468  *
469  * @param cf the capture file
470  * @param print_args the arguments what and how to export
471  * @return one of cf_print_status_t
472  */
473 cf_print_status_t cf_write_csv_packets(capture_file *cf, print_args_t *print_args);
474
475 /**
476  * Print (export) the capture file into C Arrays format.
477  *
478  * @param cf the capture file
479  * @param print_args the arguments what and how to export
480  * @return one of cf_print_status_t
481  */
482 cf_print_status_t cf_write_carrays_packets(capture_file *cf, print_args_t *print_args);
483
484 /**
485  * Print (export) the capture file into JSON format.
486  *
487  * @param cf the capture file
488  * @param print_args the arguments what and how to export
489  * @return one of cf_print_status_t
490  */
491 cf_print_status_t cf_write_json_packets(capture_file *cf, print_args_t *print_args);
492
493 /**
494  * Find packet with a protocol tree item that contains a specified text string.
495  *
496  * @param cf the capture file
497  * @param string the string to find
498  * @param dir direction in which to search
499  * @return TRUE if a packet was found, FALSE otherwise
500  */
501 gboolean cf_find_packet_protocol_tree(capture_file *cf, const char *string,
502                                       search_direction dir);
503
504 /**
505  * Find field with a label that contains text string cfile->sfilter.
506  *
507  * @param cf the capture file
508  * @param tree the protocol tree
509  * @param mdata the first field (mdata->finfo) that matched the string
510  * @return TRUE if a packet was found, FALSE otherwise
511  */
512 extern gboolean cf_find_string_protocol_tree(capture_file *cf, proto_tree *tree,
513                                              match_data *mdata);
514
515 /**
516  * Find packet whose summary line contains a specified text string.
517  *
518  * @param cf the capture file
519  * @param string the string to find
520  * @param dir direction in which to search
521  * @return TRUE if a packet was found, FALSE otherwise
522  */
523 gboolean cf_find_packet_summary_line(capture_file *cf, const char *string,
524                                      search_direction dir);
525
526 /**
527  * Find packet whose data contains a specified byte string.
528  *
529  * @param cf the capture file
530  * @param string the string to find
531  * @param string_size the size of the string to find
532  * @param dir direction in which to search
533  * @return TRUE if a packet was found, FALSE otherwise
534  */
535 gboolean cf_find_packet_data(capture_file *cf, const guint8 *string,
536                              size_t string_size, search_direction dir);
537
538 /**
539  * Find packet that matches a compiled display filter.
540  *
541  * @param cf the capture file
542  * @param sfcode the display filter to match
543  * @param dir direction in which to search
544  * @return TRUE if a packet was found, FALSE otherwise
545  */
546 gboolean cf_find_packet_dfilter(capture_file *cf, dfilter_t *sfcode,
547                                 search_direction dir);
548
549 /**
550  * Find packet that matches a display filter given as a text string.
551  *
552  * @param cf the capture file
553  * @param filter the display filter to match
554  * @param dir direction in which to search
555  * @return TRUE if a packet was found, FALSE otherwise
556  */
557 gboolean
558 cf_find_packet_dfilter_string(capture_file *cf, const char *filter,
559                               search_direction dir);
560
561 /**
562  * Find marked packet.
563  *
564  * @param cf the capture file
565  * @param dir direction in which to search
566  * @return TRUE if a packet was found, FALSE otherwise
567  */
568 gboolean cf_find_packet_marked(capture_file *cf, search_direction dir);
569
570 /**
571  * Find time-reference packet.
572  *
573  * @param cf the capture file
574  * @param dir direction in which to search
575  * @return TRUE if a packet was found, FALSE otherwise
576  */
577 gboolean cf_find_packet_time_reference(capture_file *cf, search_direction dir);
578
579 /**
580  * GoTo Packet with the given row.
581  *
582  * @param cf the capture file
583  * @param row the row to go to
584  * @return TRUE if this row exists, FALSE otherwise
585  */
586 gboolean cf_goto_frame(capture_file *cf, guint row);
587
588 /**
589  * Go to frame specified by currently selected protocol tree field.
590  * (Go To Corresponding Packet)
591  * @todo this is ugly and should be improved!
592  *
593  * @param cf the capture file
594  * @return TRUE if this packet exists, FALSE otherwise
595  */
596 gboolean cf_goto_framenum(capture_file *cf);
597
598 /**
599  * Select the packet in the given row.
600  *
601  * @param cf the capture file
602  * @param row the row to select
603  */
604 void cf_select_packet(capture_file *cf, int row);
605
606 /**
607  * Unselect all packets, if any.
608  *
609  * @param cf the capture file
610  */
611 void cf_unselect_packet(capture_file *cf);
612
613 /**
614  * Mark a particular frame in a particular capture.
615  *
616  * @param cf the capture file
617  * @param frame the frame to be marked
618  */
619 void cf_mark_frame(capture_file *cf, frame_data *frame);
620
621 /**
622  * Unmark a particular frame in a particular capture.
623  *
624  * @param cf the capture file
625  * @param frame the frame to be unmarked
626  */
627 void cf_unmark_frame(capture_file *cf, frame_data *frame);
628
629 /**
630  * Ignore a particular frame in a particular capture.
631  *
632  * @param cf the capture file
633  * @param frame the frame to be ignored
634  */
635 void cf_ignore_frame(capture_file *cf, frame_data *frame);
636
637 /**
638  * Unignore a particular frame in a particular capture.
639  *
640  * @param cf the capture file
641  * @param frame the frame to be unignored
642  */
643 void cf_unignore_frame(capture_file *cf, frame_data *frame);
644
645 /**
646  * Merge two or more capture files into a temporary file.
647  * @todo is this the right place for this function? It doesn't have to do a lot with capture_file.
648  *
649  * @param pd_window Window pointer suitable for use by delayed_create_progress_dlg.
650  * @param out_filenamep Points to a pointer that's set to point to the
651  *        pathname of the temporary file; it's allocated with g_malloc()
652  * @param in_file_count the number of input files to merge
653  * @param in_filenames array of input filenames
654  * @param file_type the output filetype
655  * @param do_append FALSE to merge chronologically, TRUE simply append
656  * @return one of cf_status_t
657  */
658 cf_status_t
659 cf_merge_files_to_tempfile(gpointer pd_window, char **out_filenamep,
660                            int in_file_count, char *const *in_filenames,
661                            int file_type, gboolean do_append);
662
663
664 /**
665  * Get the comment on a capture from the SHB data block
666  * XXX - should support multiple sections.
667  *
668  * @param cf the capture file
669  */
670 const gchar* cf_read_section_comment(capture_file *cf);
671
672 /**
673  * Update(replace) the comment on a capture from the SHB data block
674  * XXX - should support multiple sections.
675  *
676  * @param cf the capture file
677  * @param comment the string replacing the old comment
678  */
679 void cf_update_section_comment(capture_file *cf, gchar *comment);
680
681 /*
682  * Get the comment on a packet (record).
683  * If the comment has been edited, it returns the result of the edit,
684  * otherwise it returns the comment from the file.
685  *
686  * @param cf the capture file
687  * @param fd the frame_data structure for the frame
688  */
689 char *cf_get_packet_comment(capture_file *cf, const frame_data *fd);
690
691 /**
692  * Update(replace) the comment on a capture from a frame
693  *
694  * @param cf the capture file
695  * @param fd the frame_data structure for the frame
696  * @param new_comment the string replacing the old comment
697  */
698 gboolean cf_set_user_packet_comment(capture_file *cf, frame_data *fd, const gchar *new_comment);
699
700 /**
701  * What types of comments does this file have?
702  *
703  * @param cf the capture file
704  * @return bitset of WTAP_COMMENT_ values
705  */
706 guint32 cf_comment_types(capture_file *cf);
707
708 /**
709  * Add a resolved address to this file's list of resolved addresses.
710  *
711  * @param cf the capture file
712  * @param addr a string representing an IPv4 or IPv6 address
713  * @param name a string containing a name corresponding to that address
714  * @return TRUE if it succeeds, FALSE if not
715  */
716 gboolean cf_add_ip_name_from_string(capture_file *cf, const char *addr, const char *name);
717
718 #ifdef __cplusplus
719 }
720 #endif /* __cplusplus */
721
722 #endif /* file.h */
723
724 /*
725  * Editor modelines  -  http://www.wireshark.org/tools/modelines.html
726  *
727  * Local variables:
728  * c-basic-offset: 4
729  * tab-width: 8
730  * indent-tabs-mode: nil
731  * End:
732  *
733  * vi: set shiftwidth=4 tabstop=8 expandtab:
734  * :indentSize=4:tabSize=8:noTabs=true:
735  */