wiretap/merge.h

   1 /* merge.h
   2  * Definitions for routines for merging files.
   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 __MERGE_H__
  24 #define __MERGE_H__
  25
  26 #include "wiretap/wtap.h"
  27
  28 #ifdef __cplusplus
  29 extern "C" {
  30 #endif /* __cplusplus */
  31
  32 typedef enum {
  33     PACKET_PRESENT,
  34     PACKET_NOT_PRESENT,
  35     AT_EOF,
  36     GOT_ERROR
  37 } in_file_state_e;
  38
  39 /**
  40  * Structures to manage our input files.
  41  */
  42 typedef struct merge_in_file_s {
  43     const char     *filename;
  44     wtap           *wth;
  45     gint64          data_offset;
  46     in_file_state_e state;
  47     guint32         packet_num;     /* current packet number */
  48     gint64          size;           /* file size */
  49     GArray         *idb_index_map;  /* used for mapping the old phdr interface_id values to new during merge */
  50 } merge_in_file_t;
  51
  52 /** Return values from merge_files(). */
  53 typedef enum {
  54     MERGE_OK,
  55     MERGE_USER_ABORTED,
  56     /* below here are true errors */
  57     MERGE_ERR_CANT_OPEN_INFILE,
  58     MERGE_ERR_CANT_OPEN_OUTFILE,
  59     MERGE_ERR_CANT_READ_INFILE,
  60     MERGE_ERR_BAD_PHDR_INTERFACE_ID,
  61     MERGE_ERR_CANT_WRITE_OUTFILE,
  62     MERGE_ERR_CANT_CLOSE_OUTFILE
  63 } merge_result;
  64
  65
  66 /** Merge events, used as an arg in the callback function - indicates when the callback was invoked. */
  67 typedef enum {
  68     MERGE_EVENT_INPUT_FILES_OPENED,
  69     MERGE_EVENT_FRAME_TYPE_SELECTED,
  70     MERGE_EVENT_READY_TO_MERGE,
  71     MERGE_EVENT_PACKET_WAS_READ,
  72     MERGE_EVENT_DONE
  73 } merge_event;
  74
  75
  76 /** Merge mode for IDB info. */
  77 typedef enum {
  78     IDB_MERGE_MODE_NONE = 0,    /**< no merging of IDBs is done, all IDBs are copied into merged file */
  79     IDB_MERGE_MODE_ALL_SAME,/**< duplicate IDBs merged only if all the files have the same set of IDBs */
  80     IDB_MERGE_MODE_ANY_SAME, /**< any and all duplicate IDBs are merged into one IDB, even within a file */
  81     IDB_MERGE_MODE_MAX
  82 } idb_merge_mode;
  83
  84
  85 /** Returns the idb_merge_mode for the given string name.
  86  *
  87  * @param name The name of the mode.
  88  * @return The idb_merge_mode, or IDB_MERGE_MODE_MAX on failure.
  89  */
  90 WS_DLL_PUBLIC idb_merge_mode
  91 merge_string_to_idb_merge_mode(const char *name);
  92
  93
  94 /** Returns the string name for the given number.
  95  *
  96  * @param mode The number of the mode, representing the idb_merge_mode enum value.
  97  * @return The string name, or "UNKNOWN" on failure.
  98  */
  99 WS_DLL_PUBLIC const char*
 100 merge_idb_merge_mode_to_string(const int mode);
 101
 102
 103 /** @struct merge_progress_callback_t
 104  *
 105  * @brief Callback information for merging.
 106  *
 107  * @details The merge_files() routine can invoke a callback during its execution,
 108  * to enable verbose printing or progress bar updating, for example. This struct
 109  * provides merge_files() with the callback routine to invoke, and optionally
 110  * private data to pass through to the callback each time it is invoked.
 111  * For the callback_func routine's arguments: the event is when the callback
 112  * was invoked, the num is an int specific to the event, in_files is an array
 113  * of the created merge info, in_file_count is the size of the array, data is
 114  * whatever was passed in the data member of this struct. The callback_func
 115  * routine's return value should be TRUE if merging should be aborted.
 116  */
 117 typedef struct {
 118     gboolean (*callback_func)(merge_event event, int num,
 119                               const merge_in_file_t in_files[], const guint in_file_count,
 120                               void *data);
 121     void *data; /**< private data to use for passing through to the callback function */
 122 } merge_progress_callback_t;
 123
 124
 125 /** Merge the given input files to the output file descriptor.
 126  *
 127  * @param out_fd The already opened output file decriptor
 128  * @param out_filename The output filename, used in error messages
 129  * @param file_type The WTAP_FILE_TYPE_SUBTYPE_XXX output file type
 130  * @param in_filenames An array of input filenames to merge from
 131  * @param in_file_count The number of entries in in_filenames
 132  * @param do_append Whether to append by file order instead of chronological order
 133  * @param mode The IDB_MERGE_MODE_XXX merge mode for interface data
 134  * @param snaplen The snaplen to limit it to, or 0 to leave as it is in the files
 135  * @param app_name The application name performing the merge, used in SHB info
 136  * @param cb The callback information to use during execution
 137  * @param[out] err Set to the internal WTAP_ERR_XXX error code if it failed
 138  * @param[out] err_info Set to a descriptive error string, which must be g_free'd
 139  * @param[out] err_fileno Set to the input file number which failed, if it failed
 140  * @return the frame type
 141  */
 142 WS_DLL_PUBLIC merge_result
 143 merge_files(int out_fd, const gchar* out_filename, const int file_type,
 144             const char *const *in_filenames, const guint in_file_count,
 145             const gboolean do_append, const idb_merge_mode mode,
 146             guint snaplen, const gchar *app_name, merge_progress_callback_t* cb,
 147             int *err, gchar **err_info, guint *err_fileno);
 148
 149 #ifdef __cplusplus
 150 }
 151 #endif /* __cplusplus */
 152
 153 #endif /* __MERGE_H__ */
 154