forked from osmocom/wireshark
389 lines
13 KiB
C
389 lines
13 KiB
C
/* ftap.h
|
|
*
|
|
* Filetap Library
|
|
* Copyright (c) 1998 by Gilbert Ramirez <gram@alumni.rice.edu>
|
|
*
|
|
* This program is free software; you can redistribute it and/or
|
|
* modify it under the terms of the GNU General Public License
|
|
* as published by the Free Software Foundation; either version 2
|
|
* of the License, or (at your option) any later version.
|
|
*
|
|
* This program is distributed in the hope that it will be useful,
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
* GNU General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU General Public License
|
|
* along with this program; if not, write to the Free Software
|
|
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
|
|
*/
|
|
|
|
#ifndef __FTAP_H__
|
|
#define __FTAP_H__
|
|
|
|
#ifdef HAVE_SYS_TIME_H
|
|
#include <sys/time.h>
|
|
#endif
|
|
|
|
#include <glib.h>
|
|
#include <time.h>
|
|
#include <filetap/buffer.h>
|
|
#include <wsutil/nstime.h>
|
|
#include "ws_symbol_export.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif /* __cplusplus */
|
|
|
|
/* Encapsulation types. Choose names that truly reflect
|
|
* what is contained in the packet trace file.
|
|
*
|
|
* FTAP_ENCAP_PER_RECORD is a value passed to "ftap_dump_open()" or
|
|
* "ftap_dump_fd_open()" to indicate that there is no single encapsulation
|
|
* type for all records in the file; this may cause those routines to
|
|
* fail if the file format being written can't support that.
|
|
* It's also returned by "ftap_file_encap()" for capture files that
|
|
* don't have a single encapsulation type for all packets in the file.
|
|
*
|
|
* FTAP_ENCAP_UNKNOWN is returned by "ftap_pcap_encap_to_ftap_encap()"
|
|
* if it's handed an unknown encapsulation.
|
|
*
|
|
*/
|
|
#define FTAP_ENCAP_PER_RECORD -1
|
|
#define FTAP_ENCAP_UNKNOWN 0
|
|
|
|
/* After adding new item here, please also add new item to encap_table_base array */
|
|
|
|
#define FTAP_NUM_ENCAP_TYPES ftap_get_num_encap_types()
|
|
|
|
/* File types/subtypes that can be read by filetap. */
|
|
#define FTAP_FILE_TYPE_SUBTYPE_UNKNOWN 0
|
|
|
|
#define FTAP_NUM_FILE_TYPES_SUBTYPES ftap_get_num_file_types_subtypes()
|
|
|
|
/*
|
|
* Maximum record size we'll support.
|
|
* 65535 is the largest snapshot length that libpcap supports, so we
|
|
* use that.
|
|
*/
|
|
#define FTAP_MAX_RECORD_SIZE 65535
|
|
|
|
typedef struct ftap ftap;
|
|
typedef struct ftap_dumper ftap_dumper;
|
|
|
|
typedef struct ftap_reader *FILE_F;
|
|
|
|
/*
|
|
* For registering extensions used for capture file formats.
|
|
*
|
|
* These items are used in dialogs for opening files, so that
|
|
* the user can ask to see all capture files (as identified
|
|
* by file extension) or particular types of capture files.
|
|
*
|
|
* Each file type has a description and a list of extensions the file
|
|
* might have. Some file types aren't real file types, they're
|
|
* just generic types, such as "text file" or "XML file", that can
|
|
* be used for, among other things, captures we can read, or for
|
|
* extensions such as ".cap" that were unimaginatively chosen by
|
|
* several different sniffers for their file formats.
|
|
*/
|
|
struct filetap_extension_info {
|
|
/* the file type name */
|
|
const char *name;
|
|
|
|
/* a semicolon-separated list of file extensions used for this type */
|
|
const char *extensions;
|
|
};
|
|
|
|
/*
|
|
* For registering file types that we can open.
|
|
*
|
|
* Each file type has an open routine and an optional list of extensions
|
|
* the file might have.
|
|
*
|
|
* The open routine should return:
|
|
*
|
|
* -1 on an I/O error;
|
|
*
|
|
* 1 if the file it's reading is one of the types it handles;
|
|
*
|
|
* 0 if the file it's reading isn't the type it handles.
|
|
*
|
|
* If the routine handles this type of file, it should set the "file_type"
|
|
* field in the "struct ftap" to the type of the file.
|
|
*
|
|
* Note that the routine does not have to free the private data pointer on
|
|
* error. The caller takes care of that by calling ftap_close on error.
|
|
* (See https://bugs.wireshark.org/bugzilla/show_bug.cgi?id=8518)
|
|
*
|
|
* However, the caller does have to free the private data pointer when
|
|
* returning 0, since the next file type will be called and will likely
|
|
* just overwrite the pointer.
|
|
*/
|
|
|
|
/*
|
|
* Some file formats have defined magic numbers at fixed offsets from
|
|
* the beginning of the file; those routines should return 1 if and
|
|
* only if the file has the magic number at that offset. (pcap-ng
|
|
* is a bit of a special case, as it has both the Section Header Block
|
|
* type field and its byte-order magic field; it checks for both.)
|
|
* Those file formats do not require a file name extension in order
|
|
* to recognize them or to avoid recognizing other file types as that
|
|
* type, and have no extensions specified for them.
|
|
*/
|
|
typedef int (*ftap_open_routine_t)(struct ftap*, int *, char **);
|
|
|
|
/*
|
|
* Some file formats don't have defined magic numbers at fixed offsets,
|
|
* so a heuristic is required. If that file format has any file name
|
|
* extensions used for it, a list of those extensions should be
|
|
* specified, so that, if the name of the file being opened has an
|
|
* extension, the file formats that use that extension are tried before
|
|
* the ones that don't, to handle the case where a file of one type
|
|
* might be recognized by the heuristics for a different file type.
|
|
*/
|
|
struct ftap_heuristic_open_info {
|
|
ftap_open_routine_t open_routine;
|
|
const char *extensions;
|
|
gchar **extensions_set; /* populated using extensions member during initialization */
|
|
};
|
|
|
|
struct ftap_file_type_subtype_info {
|
|
/* the file type name */
|
|
/* should be NULL for all "pseudo" types that are only internally used and not read/writeable */
|
|
const char *name;
|
|
|
|
/* the file type short name, used as a shortcut for the command line tools */
|
|
/* should be NULL for all "pseudo" types that are only internally used and not read/writeable */
|
|
const char *short_name;
|
|
|
|
/* the default file extension, used to save this type */
|
|
/* should be NULL if no default extension is known */
|
|
const char *default_file_extension;
|
|
|
|
/* a semicolon-separated list of additional file extensions */
|
|
/* used for this type */
|
|
/* should be NULL if no extensions, or no extensions other */
|
|
/* than the default extension, are known */
|
|
const char *additional_file_extensions;
|
|
};
|
|
|
|
|
|
/** On failure, "ftap_open_offline()" returns NULL, and puts into the
|
|
* "int" pointed to by its second argument:
|
|
*
|
|
* @param filename Name of the file to open
|
|
* @param err a positive "errno" value if the capture file can't be opened;
|
|
* a negative number, indicating the type of error, on other failures.
|
|
* @param err_info for some errors, a string giving more details of
|
|
* the error
|
|
* @param do_random TRUE if random access to the file will be done,
|
|
* FALSE if not
|
|
*/
|
|
WS_DLL_PUBLIC
|
|
struct ftap* ftap_open_offline(const char *filename, int *err,
|
|
gchar **err_info, gboolean do_random);
|
|
|
|
/**
|
|
* If we were compiled with zlib and we're at EOF, unset EOF so that
|
|
* ftap_read/gzread has a chance to succeed. This is necessary if
|
|
* we're tailing a file.
|
|
*/
|
|
WS_DLL_PUBLIC
|
|
void ftap_cleareof(ftap *fth);
|
|
|
|
/** Returns TRUE if read was successful. FALSE if failure. data_offset is
|
|
* set to the offset in the file where the data for the read packet is
|
|
* located. */
|
|
WS_DLL_PUBLIC
|
|
gboolean ftap_read(ftap *fth, int *err, gchar **err_info,
|
|
gint64 *data_offset);
|
|
|
|
WS_DLL_PUBLIC
|
|
gboolean ftap_seek_read (ftap *fth, gint64 seek_off,
|
|
Buffer *buf, int len,
|
|
int *err, gchar **err_info);
|
|
|
|
/*** get various information snippets about the current file ***/
|
|
|
|
/** Return an approximation of the amount of data we've read sequentially
|
|
* from the file so far. */
|
|
WS_DLL_PUBLIC
|
|
gint64 ftap_read_so_far(ftap *fth);
|
|
WS_DLL_PUBLIC
|
|
gint64 ftap_file_size(ftap *fth, int *err);
|
|
WS_DLL_PUBLIC
|
|
gboolean ftap_iscompressed(ftap *fth);
|
|
WS_DLL_PUBLIC
|
|
guint ftap_snapshot_length(ftap *fth); /* per file */
|
|
WS_DLL_PUBLIC
|
|
int ftap_file_type_subtype(ftap *fth);
|
|
WS_DLL_PUBLIC
|
|
int ftap_file_encap(ftap *fth);
|
|
|
|
/*** close the file descriptors for the current file ***/
|
|
WS_DLL_PUBLIC
|
|
void ftap_fdclose(ftap *fth);
|
|
|
|
/*** reopen the random file descriptor for the current file ***/
|
|
WS_DLL_PUBLIC
|
|
gboolean ftap_fdreopen(ftap *fth, const char *filename, int *err);
|
|
|
|
/*** close the current file ***/
|
|
WS_DLL_PUBLIC
|
|
void ftap_sequential_close(ftap *fth);
|
|
WS_DLL_PUBLIC
|
|
void ftap_close(ftap *fth);
|
|
|
|
/*** various string converter functions ***/
|
|
WS_DLL_PUBLIC
|
|
const char *ftap_file_type_subtype_string(int file_type_subtype);
|
|
WS_DLL_PUBLIC
|
|
const char *ftap_file_type_subtype_short_string(int file_type_subtype);
|
|
WS_DLL_PUBLIC
|
|
int ftap_short_string_to_file_type_subtype(const char *short_name);
|
|
|
|
/*** various file extension functions ***/
|
|
WS_DLL_PUBLIC
|
|
GSList *ftap_get_all_file_extensions_list(void);
|
|
WS_DLL_PUBLIC
|
|
const char *ftap_default_file_extension(int filetype);
|
|
WS_DLL_PUBLIC
|
|
GSList *ftap_get_file_extensions_list(int filetype, gboolean include_compressed);
|
|
WS_DLL_PUBLIC
|
|
void ftap_free_extensions_list(GSList *extensions);
|
|
|
|
WS_DLL_PUBLIC
|
|
const char *ftap_encap_string(int encap);
|
|
WS_DLL_PUBLIC
|
|
const char *ftap_encap_short_string(int encap);
|
|
WS_DLL_PUBLIC
|
|
int ftap_short_string_to_encap(const char *short_name);
|
|
|
|
WS_DLL_PUBLIC
|
|
const char *ftap_strerror(int err);
|
|
|
|
/*** get available number of file types and encapsulations ***/
|
|
WS_DLL_PUBLIC
|
|
int ftap_get_num_file_type_extensions(void);
|
|
WS_DLL_PUBLIC
|
|
int ftap_get_num_encap_types(void);
|
|
WS_DLL_PUBLIC
|
|
int ftap_get_num_file_types_subtypes(void);
|
|
|
|
/*** get information for file type extension ***/
|
|
WS_DLL_PUBLIC
|
|
const char *ftap_get_file_extension_type_name(int extension_type);
|
|
WS_DLL_PUBLIC
|
|
GSList *ftap_get_file_extension_type_extensions(guint extension_type);
|
|
|
|
/*** dynamically register new file types and encapsulations ***/
|
|
WS_DLL_PUBLIC
|
|
void ftap_register_plugin_types(void);
|
|
WS_DLL_PUBLIC
|
|
void register_all_filetap_modules(void);
|
|
WS_DLL_PUBLIC
|
|
void ftap_register_file_type_extension(const struct filetap_extension_info *ei);
|
|
WS_DLL_PUBLIC
|
|
void ftap_register_magic_number_open_routine(ftap_open_routine_t open_routine);
|
|
WS_DLL_PUBLIC
|
|
void ftap_register_heuristic_open_info(struct ftap_heuristic_open_info *oi);
|
|
WS_DLL_PUBLIC
|
|
int ftap_register_file_type_subtypes(const struct ftap_file_type_subtype_info* fi);
|
|
WS_DLL_PUBLIC
|
|
int ftap_register_encap_type(const char* name, const char* short_name);
|
|
|
|
|
|
/**
|
|
* Filetap error codes.
|
|
*/
|
|
#define FTAP_ERR_NOT_REGULAR_FILE -1
|
|
/** The file being opened for reading isn't a plain file (or pipe) */
|
|
|
|
#define FTAP_ERR_RANDOM_OPEN_PIPE -2
|
|
/** The file is being opened for random access and it's a pipe */
|
|
|
|
#define FTAP_ERR_FILE_UNKNOWN_FORMAT -3
|
|
/** The file being opened is not a capture file in a known format */
|
|
|
|
#define FTAP_ERR_UNSUPPORTED -4
|
|
/** Supported file type, but there's something in the file we
|
|
can't support */
|
|
|
|
#define FTAP_ERR_CANT_WRITE_TO_PIPE -5
|
|
/** Filetap can't save to a pipe in the specified format */
|
|
|
|
#define FTAP_ERR_CANT_OPEN -6
|
|
/** The file couldn't be opened, reason unknown */
|
|
|
|
#define FTAP_ERR_UNSUPPORTED_FILE_TYPE -7
|
|
/** Filetap can't save files in the specified format */
|
|
|
|
#define FTAP_ERR_UNSUPPORTED_ENCAP -8
|
|
/** Filetap can't read or save files in the specified format with the
|
|
specified encapsulation */
|
|
|
|
#define FTAP_ERR_ENCAP_PER_RECORD_UNSUPPORTED -9
|
|
/** The specified format doesn't support per-packet encapsulations */
|
|
|
|
#define FTAP_ERR_CANT_CLOSE -10
|
|
/** The file couldn't be closed, reason unknown */
|
|
|
|
#define FTAP_ERR_CANT_READ -11
|
|
/** An attempt to read failed, reason unknown */
|
|
|
|
#define FTAP_ERR_SHORT_READ -12
|
|
/** An attempt to read read less data than it should have */
|
|
|
|
#define FTAP_ERR_BAD_FILE -13
|
|
/** The file appears to be damaged or corrupted or otherwise bogus */
|
|
|
|
#define FTAP_ERR_SHORT_WRITE -14
|
|
/** An attempt to write wrote less data than it should have */
|
|
|
|
#define FTAP_ERR_UNC_TRUNCATED -15
|
|
/** Compressed data was oddly truncated */
|
|
|
|
#define FTAP_ERR_UNC_OVERFLOW -16
|
|
/** Uncompressing data would overflow buffer */
|
|
|
|
#define FTAP_ERR_UNC_BAD_OFFSET -17
|
|
/** LZ77 compressed data has bad offset to string */
|
|
|
|
#define FTAP_ERR_RANDOM_OPEN_STDIN -18
|
|
/** We're trying to open the standard input for random access */
|
|
|
|
#define FTAP_ERR_COMPRESSION_NOT_SUPPORTED -19
|
|
/* The filetype doesn't support output compression */
|
|
|
|
#define FTAP_ERR_CANT_SEEK -20
|
|
/** An attempt to seek failed, reason unknown */
|
|
|
|
#define FTAP_ERR_CANT_SEEK_COMPRESSED -21
|
|
/** An attempt to seek on a compressed stream */
|
|
|
|
#define FTAP_ERR_DECOMPRESS -22
|
|
/** Error decompressing */
|
|
|
|
#define FTAP_ERR_INTERNAL -23
|
|
/** "Shouldn't happen" internal errors */
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif /* __cplusplus */
|
|
|
|
#endif /* __FTAP_H__ */
|
|
|
|
/*
|
|
* Editor modelines - http://www.wireshark.org/tools/modelines.html
|
|
*
|
|
* Local variables:
|
|
* c-basic-offset: 4
|
|
* tab-width: 8
|
|
* indent-tabs-mode: nil
|
|
* End:
|
|
*
|
|
* vi: set shiftwidth=4 tabstop=8 expandtab:
|
|
* :indentSize=4:tabSize=8:noTabs=true:
|
|
*/
|