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 "print.h"
  30 #include <errno.h>
  31 #include <epan/epan.h>
  32
  33 #include "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 pd a guin8 array 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, frame_data *fdata,
 152                          struct wtap_pkthdr *phdr, guint8 *pd);
 153
 154 /**
 155  * Read the pseudo-header and raw data for a packet into a
 156  * capture_file structure's pseudo_header and pd 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  * Start reading from the end of a capture file.
 167  * This is used in "Update list of packets in Real-Time".
 168  *
 169  * @param cf the capture file to be read from
 170  * @param fname the filename to be read from
 171  * @param is_tempfile is this a temporary file?
 172  * @param err the error code, if an error had occurred
 173  * @return one of cf_status_t
 174  */
 175 cf_status_t cf_start_tail(capture_file *cf, const char *fname, gboolean is_tempfile, int *err);
 176
 177 /**
 178  * Read packets from the "end" of a capture file.
 179  *
 180  * @param cf the capture file to be read from
 181  * @param to_read the number of packets to read
 182  * @param err the error code, if an error had occurred
 183  * @return one of cf_read_status_t
 184  */
 185 cf_read_status_t cf_continue_tail(capture_file *cf, volatile int to_read, int *err);
 186
 187 /**
 188  * Fake reading packets from the "end" of a capture file.
 189  *
 190  * @param cf the capture file to be read from
 191  */
 192 void cf_fake_continue_tail(capture_file *cf);
 193
 194 /**
 195  * Finish reading from "end" of a capture file.
 196  *
 197  * @param cf the capture file to be read from
 198  * @param err the error code, if an error had occurred
 199  * @return one of cf_read_status_t
 200  */
 201 cf_read_status_t cf_finish_tail(capture_file *cf, int *err);
 202
 203 /**
 204  * Determine whether this capture file (or a range of it) can be written
 205  * in any format using Wiretap rather than by copying the raw data.
 206  *
 207  * @param cf the capture file to check
 208  * @return TRUE if it can be written, FALSE if it can't
 209  */
 210 gboolean cf_can_write_with_wiretap(capture_file *cf);
 211
 212 /**
 213  * Determine whether this capture file can be saved with a "save" operation;
 214  * if there's nothing unsaved, it can't.
 215  *
 216  * @param cf the capture file to check
 217  * @return TRUE if it can be saved, FALSE if it can't
 218  */
 219 gboolean cf_can_save(capture_file *cf);
 220
 221 /**
 222  * Determine whether this capture file can be saved with a "save as" operation.
 223  *
 224  * @param cf the capture file to check
 225  * @return TRUE if it can be saved, FALSE if it can't
 226  */
 227 gboolean cf_can_save_as(capture_file *cf);
 228
 229 /**
 230  * Determine whether this capture file has unsaved data.
 231  *
 232  * @param cf the capture file to check
 233  * @return TRUE if it has unsaved data, FALSE if it doesn't
 234  */
 235 gboolean cf_has_unsaved_data(capture_file *cf);
 236
 237 /**
 238  * Save all packets in a capture file to a new file, and, if that succeeds,
 239  * make that file the current capture file.  If there's already a file with
 240  * that name, do a "safe save", writing to a temporary file in the same
 241  * directory and, if the write succeeds, renaming the new file on top of the
 242  * old file, so that if the write fails, the old file is still intact.
 243  *
 244  * @param cf the capture file to save to
 245  * @param fname the filename to save to
 246  * @param save_format the format of the file to save (libpcap, ...)
 247  * @param compressed whether to gzip compress the file
 248  * @param discard_comments TRUE if we should discard comments if the save
 249  * succeeds (because we saved in a format that doesn't support
 250  * comments)
 251  * @param dont_reopen TRUE if it shouldn't reopen and make that file the
 252  * current capture file
 253  * @return one of cf_write_status_t
 254  */
 255 cf_write_status_t cf_save_packets(capture_file * cf, const char *fname,
 256                                   guint save_format, gboolean compressed,
 257                                   gboolean discard_comments,
 258                                   gboolean dont_reopen);
 259
 260 /**
 261  * Export some or all packets from a capture file to a new file.  If there's
 262  * already a file with that name, do a "safe save", writing to a temporary
 263  * file in the same directory and, if the write succeeds, renaming the new
 264  * file on top of the old file, so that if the write fails, the old file is
 265  * still intact.
 266  *
 267  * @param cf the capture file to write to
 268  * @param fname the filename to write to
 269  * @param range the range of packets to write
 270  * @param save_format the format of the file to write (libpcap, ...)
 271  * @param compressed whether to gzip compress the file
 272  * @return one of cf_write_status_t
 273  */
 274 cf_write_status_t cf_export_specified_packets(capture_file *cf,
 275                                               const char *fname,
 276                                               packet_range_t *range,
 277                                               guint save_format,
 278                                               gboolean compressed);
 279
 280 /**
 281  * Get a displayable name of the capture file.
 282  *
 283  * @param cf the capture file
 284  * @return the displayable name (must be g_free'd)
 285  */
 286 gchar *cf_get_display_name(capture_file *cf);
 287
 288 /**
 289  * Set the source of the capture data for temporary files, e.g.
 290  * "Interface eth0" or "Pipe from Pong"
 291  *
 292  * @param cf the capture file
 293  * @param source the source description. this will be copied internally.
 294  */
 295 void cf_set_tempfile_source(capture_file *cf, gchar *source);
 296
 297 /**
 298  * Get the source of the capture data for temporary files. Guaranteed to
 299  * return a non-null value. The returned value should not be freed.
 300  *
 301  * @param cf the capture file
 302  */
 303 const gchar *cf_get_tempfile_source(capture_file *cf);
 304
 305 /**
 306  * Get the number of packets in the capture file.
 307  *
 308  * @param cf the capture file
 309  * @return the number of packets in the capture file
 310  */
 311 int cf_get_packet_count(capture_file *cf);
 312
 313 /**
 314  * Set the number of packets in the capture file.
 315  *
 316  * @param cf the capture file
 317  * @param packet_count the number of packets in the capture file
 318  */
 319 void cf_set_packet_count(capture_file *cf, int packet_count);
 320
 321 /**
 322  * Is this capture file a temporary file?
 323  *
 324  * @param cf the capture file
 325  * @return TRUE if it's a temporary file, FALSE otherwise
 326  */
 327 gboolean cf_is_tempfile(capture_file *cf);
 328
 329 /**
 330  * Set flag, that this file is a tempfile.
 331  */
 332 void cf_set_tempfile(capture_file *cf, gboolean is_tempfile);
 333
 334 /**
 335  * Set flag, if the number of packet drops while capturing are known or not.
 336  *
 337  * @param cf the capture file
 338  * @param drops_known TRUE if the number of packet drops are known, FALSE otherwise
 339  */
 340 void cf_set_drops_known(capture_file *cf, gboolean drops_known);
 341
 342 /**
 343  * Set the number of packet drops while capturing.
 344  *
 345  * @param cf the capture file
 346  * @param drops the number of packet drops occurred while capturing
 347  */
 348 void cf_set_drops(capture_file *cf, guint32 drops);
 349
 350 /**
 351  * Get flag state, if the number of packet drops while capturing are known or not.
 352  *
 353  * @param cf the capture file
 354  * @return TRUE if the number of packet drops are known, FALSE otherwise
 355  */
 356 gboolean cf_get_drops_known(capture_file *cf);
 357
 358 /**
 359  * Get the number of packet drops while capturing.
 360  *
 361  * @param cf the capture file
 362  * @return the number of packet drops occurred while capturing
 363  */
 364 guint32 cf_get_drops(capture_file *cf);
 365
 366 /**
 367  * Set the read filter.
 368  * @todo this shouldn't be required, remove it somehow
 369  *
 370  * @param cf the capture file
 371  * @param rfcode the readfilter
 372  */
 373 void cf_set_rfcode(capture_file *cf, dfilter_t *rfcode);
 374
 375 /**
 376  * "Display Filter" packets in the capture file.
 377  *
 378  * @param cf the capture file
 379  * @param dfilter the display filter
 380  * @param force TRUE if do in any case, FALSE only if dfilter changed
 381  * @return one of cf_status_t
 382  */
 383 cf_status_t cf_filter_packets(capture_file *cf, gchar *dfilter, gboolean force);
 384
 385 /**
 386  * At least one "Refence Time" flag has changed, rescan all packets.
 387  *
 388  * @param cf the capture file
 389  */
 390 void cf_reftime_packets(capture_file *cf);
 391
 392 /**
 393  * Return the time it took to load the file
 394  */
 395 gulong cf_get_computed_elapsed(void);
 396
 397 /**
 398  * "Something" has changed, rescan all packets.
 399  *
 400  * @param cf the capture file
 401  */
 402 void cf_redissect_packets(capture_file *cf);
 403
 404 /**
 405  * Rescan all packets and just run taps - don't reconstruct the display.
 406  *
 407  * @param cf the capture file
 408  * @return one of cf_read_status_t
 409  */
 410 cf_read_status_t cf_retap_packets(capture_file *cf);
 411
 412 /**
 413  * Adjust timestamp precision if auto is selected.
 414  *
 415  * @param cf the capture file
 416  */
 417 void cf_timestamp_auto_precision(capture_file *cf);
 418
 419 /**
 420  * Print the capture file.
 421  *
 422  * @param cf the capture file
 423  * @param print_args the arguments what and how to print
 424  * @return one of cf_print_status_t
 425  */
 426 cf_print_status_t cf_print_packets(capture_file *cf, print_args_t *print_args);
 427
 428 /**
 429  * Print (export) the capture file into PDML format.
 430  *
 431  * @param cf the capture file
 432  * @param print_args the arguments what and how to export
 433  * @return one of cf_print_status_t
 434  */
 435 cf_print_status_t cf_write_pdml_packets(capture_file *cf, print_args_t *print_args);
 436
 437 /**
 438  * Print (export) the capture file into PSML 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_psml_packets(capture_file *cf, print_args_t *print_args);
 445
 446 /**
 447  * Print (export) the capture file into CSV 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_csv_packets(capture_file *cf, print_args_t *print_args);
 454
 455 /**
 456  * Print (export) the capture file into C Arrays 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_carrays_packets(capture_file *cf, print_args_t *print_args);
 463
 464 /**
 465  * Find packet with a protocol tree item that contains a specified text string.
 466  *
 467  * @param cf the capture file
 468  * @param string the string to find
 469  * @param dir direction in which to search
 470  * @return TRUE if a packet was found, FALSE otherwise
 471  */
 472 gboolean cf_find_packet_protocol_tree(capture_file *cf, const char *string,
 473                                       search_direction dir);
 474
 475 /**
 476  * Find field with a label that contains text string cfile->sfilter.
 477  *
 478  * @param cf the capture file
 479  * @param tree the protocol tree
 480  * @param mdata the first field (mdata->finfo) that matched the string
 481  * @return TRUE if a packet was found, FALSE otherwise
 482  */
 483 extern gboolean cf_find_string_protocol_tree(capture_file *cf, proto_tree *tree,
 484                                              match_data *mdata);
 485
 486 /**
 487  * Find packet whose summary line contains a specified text string.
 488  *
 489  * @param cf the capture file
 490  * @param string 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_summary_line(capture_file *cf, const char *string,
 495                                      search_direction dir);
 496
 497 /**
 498  * Find packet whose data contains a specified byte string.
 499  *
 500  * @param cf the capture file
 501  * @param string the string to find
 502  * @param string_size the size of the string to find
 503  * @param dir direction in which to search
 504  * @return TRUE if a packet was found, FALSE otherwise
 505  */
 506 gboolean cf_find_packet_data(capture_file *cf, const guint8 *string,
 507                              size_t string_size, search_direction dir);
 508
 509 /**
 510  * Find packet that matches a compiled display filter.
 511  *
 512  * @param cf the capture file
 513  * @param sfcode the display filter to match
 514  * @param dir direction in which to search
 515  * @return TRUE if a packet was found, FALSE otherwise
 516  */
 517 gboolean cf_find_packet_dfilter(capture_file *cf, dfilter_t *sfcode,
 518                                 search_direction dir);
 519
 520 /**
 521  * Find packet that matches a display filter given as a text string.
 522  *
 523  * @param cf the capture file
 524  * @param filter the display filter to match
 525  * @param dir direction in which to search
 526  * @return TRUE if a packet was found, FALSE otherwise
 527  */
 528 gboolean
 529 cf_find_packet_dfilter_string(capture_file *cf, const char *filter,
 530                               search_direction dir);
 531
 532 /**
 533  * Find marked packet.
 534  *
 535  * @param cf the capture file
 536  * @param dir direction in which to search
 537  * @return TRUE if a packet was found, FALSE otherwise
 538  */
 539 gboolean cf_find_packet_marked(capture_file *cf, search_direction dir);
 540
 541 /**
 542  * Find time-reference packet.
 543  *
 544  * @param cf the capture file
 545  * @param dir direction in which to search
 546  * @return TRUE if a packet was found, FALSE otherwise
 547  */
 548 gboolean cf_find_packet_time_reference(capture_file *cf, search_direction dir);
 549
 550 /**
 551  * GoTo Packet in first row.
 552  *
 553  * @return TRUE if the first row exists, FALSE otherwise
 554  */
 555 gboolean cf_goto_top_frame(void);
 556
 557 /**
 558  * GoTo Packet in last row.
 559  *
 560  * @return TRUE if last row exists, FALSE otherwise
 561  */
 562 gboolean cf_goto_bottom_frame(void);
 563
 564 /**
 565  * GoTo Packet with the given row.
 566  *
 567  * @param cf the capture file
 568  * @param row the row to go to
 569  * @return TRUE if this row exists, FALSE otherwise
 570  */
 571 gboolean cf_goto_frame(capture_file *cf, guint row);
 572
 573 /**
 574  * Go to frame specified by currently selected protocol tree field.
 575  * (Go To Corresponding Packet)
 576  * @todo this is ugly and should be improved!
 577  *
 578  * @param cf the capture file
 579  * @return TRUE if this packet exists, FALSE otherwise
 580  */
 581 gboolean cf_goto_framenum(capture_file *cf);
 582
 583 /**
 584  * Select the packet in the given row.
 585  *
 586  * @param cf the capture file
 587  * @param row the row to select
 588  */
 589 void cf_select_packet(capture_file *cf, int row);
 590
 591 /**
 592  * Unselect all packets, if any.
 593  *
 594  * @param cf the capture file
 595  */
 596 void cf_unselect_packet(capture_file *cf);
 597
 598 /**
 599  * Unselect all protocol tree fields, if any.
 600  *
 601  * @param cf the capture file
 602  */
 603 void cf_unselect_field(capture_file *cf);
 604
 605 /**
 606  * Mark a particular frame in a particular capture.
 607  *
 608  * @param cf the capture file
 609  * @param frame the frame to be marked
 610  */
 611 void cf_mark_frame(capture_file *cf, frame_data *frame);
 612
 613 /**
 614  * Unmark a particular frame in a particular capture.
 615  *
 616  * @param cf the capture file
 617  * @param frame the frame to be unmarked
 618  */
 619 void cf_unmark_frame(capture_file *cf, frame_data *frame);
 620
 621 /**
 622  * Ignore a particular frame in a particular capture.
 623  *
 624  * @param cf the capture file
 625  * @param frame the frame to be ignored
 626  */
 627 void cf_ignore_frame(capture_file *cf, frame_data *frame);
 628
 629 /**
 630  * Unignore a particular frame in a particular capture.
 631  *
 632  * @param cf the capture file
 633  * @param frame the frame to be unignored
 634  */
 635 void cf_unignore_frame(capture_file *cf, frame_data *frame);
 636
 637 /**
 638  * Merge two (or more) capture files into one.
 639  * @todo is this the right place for this function? It doesn't have to do a lot with capture_file.
 640  *
 641  * @param out_filename pointer to output filename; if output filename is
 642  * NULL, a temporary file name is generated and *out_filename is set
 643  * to point to the generated file name
 644  * @param in_file_count the number of input files to merge
 645  * @param in_filenames array of input filenames
 646  * @param file_type the output filetype
 647  * @param do_append FALSE to merge chronologically, TRUE simply append
 648  * @return one of cf_status_t
 649  */
 650 cf_status_t
 651 cf_merge_files(char **out_filename, int in_file_count,
 652                char *const *in_filenames, int file_type, gboolean do_append);
 653
 654
 655 /**
 656  * Get the comment on a capture from the SHB data block
 657  *
 658  * @param cf the capture file
 659  */
 660 const gchar* cf_read_shb_comment(capture_file *cf);
 661
 662 /**
 663  * Update(replace) the comment on a capture from the SHB data block
 664  *
 665  * @param cf the capture file
 666  * @param comment the string replacing the old comment
 667  */
 668 void cf_update_capture_comment(capture_file *cf, gchar *comment);
 669
 670 /**
 671  * Update(replace) the comment on a capture from a frame
 672  *
 673  * @param cf the capture file
 674  * @param fdata the frame_data structure for the frame
 675  * @param comment the string replacing the old comment
 676  */
 677 void cf_update_packet_comment(capture_file *cf, frame_data *fdata, gchar *comment);
 678
 679 /**
 680  * What types of comments does this file have?
 681  *
 682  * @param cf the capture file
 683  * @return bitset of WTAP_COMMENT_ values
 684  */
 685 guint32 cf_comment_types(capture_file *cf);
 686
 687 #if defined(HAVE_HEIMDAL_KERBEROS) || defined(HAVE_MIT_KERBEROS)
 688 WS_DLL_PUBLIC
 689 void read_keytab_file(const char *);
 690 #endif
 691
 692 #ifdef __cplusplus
 693 }
 694 #endif /* __cplusplus */
 695
 696 #endif /* file.h */