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