file.h

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