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