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