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  * SPDX-License-Identifier: GPL-2.0-or-later
   9  */
  10
  11 #ifndef __MERGE_H__
  12 #define __MERGE_H__
  13
  14 #include "wiretap/wtap.h"
  15
  16 #ifdef __cplusplus
  17 extern "C" {
  18 #endif /* __cplusplus */
  19
  20 typedef enum {
  21     RECORD_PRESENT,
  22     RECORD_NOT_PRESENT,
  23     AT_EOF,
  24     GOT_ERROR
  25 } in_file_state_e;
  26
  27 /**
  28  * Structures to manage our input files.
  29  */
  30 typedef struct merge_in_file_s {
  31     const char     *filename;
  32     wtap           *wth;
  33     in_file_state_e state;
  34     guint32         packet_num;     /* current packet number */
  35     gint64          size;           /* file size */
  36     GArray         *idb_index_map;  /* used for mapping the old phdr interface_id values to new during merge */
  37     guint           dsbs_seen;      /* number of elements processed so far from wth->dsbs */
  38 } merge_in_file_t;
  39
  40 /** Return values from merge_files(). */
  41 typedef enum {
  42     MERGE_OK,
  43     MERGE_USER_ABORTED,
  44     /* below here are true errors */
  45     MERGE_ERR_CANT_OPEN_INFILE,
  46     MERGE_ERR_CANT_OPEN_OUTFILE,
  47     MERGE_ERR_CANT_READ_INFILE,
  48     MERGE_ERR_BAD_PHDR_INTERFACE_ID,
  49     MERGE_ERR_CANT_WRITE_OUTFILE,
  50     MERGE_ERR_CANT_CLOSE_OUTFILE,
  51     MERGE_ERR_INVALID_OPTION
  52 } merge_result;
  53
  54
  55 /** Merge events, used as an arg in the callback function - indicates when the callback was invoked. */
  56 typedef enum {
  57     MERGE_EVENT_INPUT_FILES_OPENED,
  58     MERGE_EVENT_FRAME_TYPE_SELECTED,
  59     MERGE_EVENT_READY_TO_MERGE,
  60     MERGE_EVENT_RECORD_WAS_READ,
  61     MERGE_EVENT_DONE
  62 } merge_event;
  63
  64
  65 /** Merge mode for IDB info. */
  66 typedef enum {
  67     IDB_MERGE_MODE_NONE = 0,    /**< no merging of IDBs is done, all IDBs are copied into merged file */
  68     IDB_MERGE_MODE_ALL_SAME,/**< duplicate IDBs merged only if all the files have the same set of IDBs */
  69     IDB_MERGE_MODE_ANY_SAME, /**< any and all duplicate IDBs are merged into one IDB, even within a file */
  70     IDB_MERGE_MODE_MAX
  71 } idb_merge_mode;
  72
  73
  74 /** Returns the idb_merge_mode for the given string name.
  75  *
  76  * @param name The name of the mode.
  77  * @return The idb_merge_mode, or IDB_MERGE_MODE_MAX on failure.
  78  */
  79 WS_DLL_PUBLIC idb_merge_mode
  80 merge_string_to_idb_merge_mode(const char *name);
  81
  82
  83 /** Returns the string name for the given number.
  84  *
  85  * @param mode The number of the mode, representing the idb_merge_mode enum value.
  86  * @return The string name, or "UNKNOWN" on failure.
  87  */
  88 WS_DLL_PUBLIC const char*
  89 merge_idb_merge_mode_to_string(const int mode);
  90
  91
  92 /** @struct merge_progress_callback_t
  93  *
  94  * @brief Callback information for merging.
  95  *
  96  * @details The merge_files() routine can invoke a callback during its execution,
  97  * to enable verbose printing or progress bar updating, for example. This struct
  98  * provides merge_files() with the callback routine to invoke, and optionally
  99  * private data to pass through to the callback each time it is invoked.
 100  * For the callback_func routine's arguments: the event is when the callback
 101  * was invoked, the num is an int specific to the event, in_files is an array
 102  * of the created merge info, in_file_count is the size of the array, data is
 103  * whatever was passed in the data member of this struct. The callback_func
 104  * routine's return value should be TRUE if merging should be aborted.
 105  */
 106 typedef struct {
 107     gboolean (*callback_func)(merge_event event, int num,
 108                               const merge_in_file_t in_files[], const guint in_file_count,
 109                               void *data);
 110     void *data; /**< private data to use for passing through to the callback function */
 111 } merge_progress_callback_t;
 112
 113
 114 /** Merge the given input files to a file with the given filename
 115  *
 116  * @param out_filename The output filename
 117  * @param file_type The WTAP_FILE_TYPE_SUBTYPE_XXX output file type
 118  * @param in_filenames An array of input filenames to merge from
 119  * @param in_file_count The number of entries in in_filenames
 120  * @param do_append Whether to append by file order instead of chronological order
 121  * @param mode The IDB_MERGE_MODE_XXX merge mode for interface data
 122  * @param snaplen The snaplen to limit it to, or 0 to leave as it is in the files
 123  * @param app_name The application name performing the merge, used in SHB info
 124  * @param cb The callback information to use during execution
 125  * @param[out] err Set to the internal WTAP_ERR_XXX error code if it failed
 126  *   with MERGE_ERR_CANT_OPEN_INFILE, MERGE_ERR_CANT_OPEN_OUTFILE,
 127  *   MERGE_ERR_CANT_READ_INFILE, MERGE_ERR_CANT_WRITE_OUTFILE, or
 128  *   MERGE_ERR_CANT_CLOSE_OUTFILE
 129  * @param[out] err_info Additional information for some WTAP_ERR_XXX codes
 130  * @param[out] err_fileno Set to the input file number which failed, if it
 131  *   failed
 132  * @param[out] err_framenum Set to the input frame number if it failed
 133  * @return the frame type
 134  */
 135 WS_DLL_PUBLIC merge_result
 136 merge_files(const gchar* out_filename, const int file_type,
 137             const char *const *in_filenames, const guint in_file_count,
 138             const gboolean do_append, const idb_merge_mode mode,
 139             guint snaplen, const gchar *app_name, merge_progress_callback_t* cb,
 140             int *err, gchar **err_info, guint *err_fileno,
 141             guint32 *err_framenum);
 142
 143 /** Merge the given input files to a temporary file
 144  *
 145  * @param out_filenamep Points to a pointer that's set to point to the
 146  *        pathname of the temporary file; it's allocated with g_malloc()
 147  * @param pfx A string to be used as the prefix for the temporary file name
 148  * @param file_type The WTAP_FILE_TYPE_SUBTYPE_XXX output file type
 149  * @param in_filenames An array of input filenames to merge from
 150  * @param in_file_count The number of entries in in_filenames
 151  * @param do_append Whether to append by file order instead of chronological order
 152  * @param mode The IDB_MERGE_MODE_XXX merge mode for interface data
 153  * @param snaplen The snaplen to limit it to, or 0 to leave as it is in the files
 154  * @param app_name The application name performing the merge, used in SHB info
 155  * @param cb The callback information to use during execution
 156  * @param[out] err Set to the internal WTAP_ERR_XXX error code if it failed
 157  *   with MERGE_ERR_CANT_OPEN_INFILE, MERGE_ERR_CANT_OPEN_OUTFILE,
 158  *   MERGE_ERR_CANT_READ_INFILE, MERGE_ERR_CANT_WRITE_OUTFILE, or
 159  *   MERGE_ERR_CANT_CLOSE_OUTFILE
 160  * @param[out] err_info Additional information for some WTAP_ERR_XXX codes
 161  * @param[out] err_fileno Set to the input file number which failed, if it
 162  *   failed
 163  * @param[out] err_framenum Set to the input frame number if it failed
 164  * @return the frame type
 165  */
 166 WS_DLL_PUBLIC merge_result
 167 merge_files_to_tempfile(gchar **out_filenamep, const char *pfx,
 168                         const int file_type, const char *const *in_filenames,
 169                         const guint in_file_count, const gboolean do_append,
 170                         const idb_merge_mode mode, guint snaplen,
 171                         const gchar *app_name, merge_progress_callback_t* cb,
 172                         int *err, gchar **err_info, guint *err_fileno,
 173                         guint32 *err_framenum);
 174
 175 /** Merge the given input files to the standard output
 176  *
 177  * @param file_type The WTAP_FILE_TYPE_SUBTYPE_XXX output file type
 178  * @param in_filenames An array of input filenames to merge from
 179  * @param in_file_count The number of entries in in_filenames
 180  * @param do_append Whether to append by file order instead of chronological order
 181  * @param mode The IDB_MERGE_MODE_XXX merge mode for interface data
 182  * @param snaplen The snaplen to limit it to, or 0 to leave as it is in the files
 183  * @param app_name The application name performing the merge, used in SHB info
 184  * @param cb The callback information to use during execution
 185  * @param[out] err Set to the internal WTAP_ERR_XXX error code if it failed
 186  *   with MERGE_ERR_CANT_OPEN_INFILE, MERGE_ERR_CANT_OPEN_OUTFILE,
 187  *   MERGE_ERR_CANT_READ_INFILE, MERGE_ERR_CANT_WRITE_OUTFILE, or
 188  *   MERGE_ERR_CANT_CLOSE_OUTFILE
 189  * @param[out] err_info Additional information for some WTAP_ERR_XXX codes
 190  * @param[out] err_fileno Set to the input file number which failed, if it
 191  *   failed
 192  * @param[out] err_framenum Set to the input frame number if it failed
 193  * @return the frame type
 194  */
 195 WS_DLL_PUBLIC merge_result
 196 merge_files_to_stdout(const int file_type, const char *const *in_filenames,
 197                       const guint in_file_count, const gboolean do_append,
 198                       const idb_merge_mode mode, guint snaplen,
 199                       const gchar *app_name, merge_progress_callback_t* cb,
 200                       int *err, gchar **err_info, guint *err_fileno,
 201                       guint32 *err_framenum);
 202
 203 #ifdef __cplusplus
 204 }
 205 #endif /* __cplusplus */
 206
 207 #endif /* __MERGE_H__ */
 208