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