wiretap/merge.h

   1 /** @file
   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     wtap_rec        rec;
  34     Buffer          frame_buffer;
  35     in_file_state_e state;
  36     uint32_t        packet_num;     /* current packet number */
  37     int64_t         size;           /* file size */
  38     GArray         *idb_index_map;  /* used for mapping the old phdr interface_id values to new during merge */
  39     unsigned        nrbs_seen;      /* number of elements processed so far from wth->nrbs */
  40     unsigned        dsbs_seen;      /* number of elements processed so far from wth->dsbs */
  41 } merge_in_file_t;
  42
  43 /** Merge events, used as an arg in the callback function - indicates when the callback was invoked. */
  44 typedef enum {
  45     MERGE_EVENT_INPUT_FILES_OPENED,
  46     MERGE_EVENT_FRAME_TYPE_SELECTED,
  47     MERGE_EVENT_READY_TO_MERGE,
  48     MERGE_EVENT_RECORD_WAS_READ,
  49     MERGE_EVENT_DONE
  50 } merge_event;
  51
  52
  53 /** Merge mode for IDB info. */
  54 typedef enum {
  55     IDB_MERGE_MODE_NONE = 0,    /**< no merging of IDBs is done, all IDBs are copied into merged file */
  56     IDB_MERGE_MODE_ALL_SAME,/**< duplicate IDBs merged only if all the files have the same set of IDBs */
  57     IDB_MERGE_MODE_ANY_SAME, /**< any and all duplicate IDBs are merged into one IDB, even within a file */
  58     IDB_MERGE_MODE_MAX
  59 } idb_merge_mode;
  60
  61
  62 /** Returns the idb_merge_mode for the given string name.
  63  *
  64  * @param name The name of the mode.
  65  * @return The idb_merge_mode, or IDB_MERGE_MODE_MAX on failure.
  66  */
  67 WS_DLL_PUBLIC idb_merge_mode
  68 merge_string_to_idb_merge_mode(const char *name);
  69
  70
  71 /** Returns the string name for the given number.
  72  *
  73  * @param mode The number of the mode, representing the idb_merge_mode enum value.
  74  * @return The string name, or "UNKNOWN" on failure.
  75  */
  76 WS_DLL_PUBLIC const char*
  77 merge_idb_merge_mode_to_string(const int mode);
  78
  79
  80 /** @struct merge_progress_callback_t
  81  *
  82  * @brief Callback information for merging.
  83  *
  84  * @details The merge_files() routine can invoke a callback during its execution,
  85  * to enable verbose printing or progress bar updating, for example. This struct
  86  * provides merge_files() with the callback routine to invoke, and optionally
  87  * private data to pass through to the callback each time it is invoked.
  88  * For the callback_func routine's arguments: the event is when the callback
  89  * was invoked, the num is an int specific to the event, in_files is an array
  90  * of the created merge info, in_file_count is the size of the array, data is
  91  * whatever was passed in the data member of this struct. The callback_func
  92  * routine's return value should be true if merging should be aborted.
  93  */
  94 typedef struct {
  95     bool (*callback_func)(merge_event event, int num,
  96                               const merge_in_file_t in_files[], const unsigned in_file_count,
  97                               void *data);
  98     void *data; /**< private data to use for passing through to the callback function */
  99 } merge_progress_callback_t;
 100
 101
 102 /** Merge the given input files to a file with the given filename
 103  *
 104  * @param out_filename The output filename
 105  * @param file_type The WTAP_FILE_TYPE_SUBTYPE_XXX output file type
 106  * @param in_filenames An array of input filenames to merge from
 107  * @param in_file_count The number of entries in in_filenames
 108  * @param do_append Whether to append by file order instead of chronological order
 109  * @param mode The IDB_MERGE_MODE_XXX merge mode for interface data
 110  * @param snaplen The snaplen to limit it to, or 0 to leave as it is in the files
 111  * @param app_name The application name performing the merge, used in SHB info
 112  * @param cb The callback information to use during execution
 113  * @param compression_type The compresion type to use for the output
 114  * @return true on success, false on failure
 115  */
 116 WS_DLL_PUBLIC bool
 117 merge_files(const char* out_filename, const int file_type,
 118             const char *const *in_filenames, const unsigned in_file_count,
 119             const bool do_append, const idb_merge_mode mode,
 120             unsigned snaplen, const char *app_name, merge_progress_callback_t* cb,
 121             wtap_compression_type compression_type);
 122
 123 /** Merge the given input files to a temporary file
 124  *
 125  * @param tmpdir Points to the directory in which to write the temporary file
 126  * @param out_filenamep Points to a pointer that's set to point to the
 127  *        pathname of the temporary file; it's allocated with g_malloc()
 128  * @param pfx A string to be used as the prefix for the temporary file name
 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  * @return true on success, false on failure
 138  */
 139 WS_DLL_PUBLIC bool
 140 merge_files_to_tempfile(const char *tmpdir, char **out_filenamep, const char *pfx,
 141                         const int file_type, const char *const *in_filenames,
 142                         const unsigned in_file_count, const bool do_append,
 143                         const idb_merge_mode mode, unsigned snaplen,
 144                         const char *app_name, merge_progress_callback_t* cb);
 145
 146 /** Merge the given input files to the standard output
 147  *
 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  * @return true on success, false on failure
 157  */
 158 WS_DLL_PUBLIC bool
 159 merge_files_to_stdout(const int file_type, const char *const *in_filenames,
 160                       const unsigned in_file_count, const bool do_append,
 161                       const idb_merge_mode mode, unsigned snaplen,
 162                       const char *app_name, merge_progress_callback_t* cb,
 163                       wtap_compression_type compression_type);
 164
 165 #ifdef __cplusplus
 166 }
 167 #endif /* __cplusplus */
 168
 169 #endif /* __MERGE_H__ */
 170