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