diff --git a/wiretap/file_access.c b/wiretap/file_access.c index 795a1ba77e..827aa78f92 100644 --- a/wiretap/file_access.c +++ b/wiretap/file_access.c @@ -133,6 +133,9 @@ add_extensions(GSList *extensions, const gchar *extension, * *not* be placed here; if there's nothing to put in the last field * of the structure, don't put an entry here, not even one with an * empty string for the extensions list. + * + * All added file types, regardless of extension or lack thereof, + * must also be added open_info_base[] below. */ static const struct file_extension_info file_type_extensions_base[] = { { "Wireshark/tcpdump/... - pcap", TRUE, "pcap;cap;dmp" }, @@ -244,10 +247,11 @@ add_extensions_for_file_extensions_type(int extension_type, GSList *extensions, } /* Return a list of file extensions that are used by the specified file - extension type. - - All strings in the list are allocated with g_malloc() and must be freed - with g_free(). */ + * extension type. + * + * All strings in the list are allocated with g_malloc() and must be freed + * with g_free(). + */ GSList * wtap_get_file_extension_type_extensions(guint extension_type) { @@ -276,21 +280,22 @@ wtap_get_file_extension_type_extensions(guint extension_type) } /* Return a list of all extensions that are used by all capture file - types, including compressed extensions, e.g. not just "pcap" but - also "pcap.gz" if we can read gzipped files. - - "Capture files" means "include file types that correspond to - collections of network packets, but not file types that - store data that just happens to be transported over protocols - such as HTTP but that aren't collections of network packets", - so that it could be used for "All Capture Files" without picking - up JPEG files or files such as that - those aren't capture files, - and we *do* have them listed in the long list of individual file - types, so omitting them from "All Capture Files" is the right - thing to do. - - All strings in the list are allocated with g_malloc() and must be freed - with g_free(). */ + * types, including compressed extensions, e.g. not just "pcap" but + * also "pcap.gz" if we can read gzipped files. + * + * "Capture files" means "include file types that correspond to + * collections of network packets, but not file types that + * store data that just happens to be transported over protocols + * such as HTTP but that aren't collections of network packets", + * so that it could be used for "All Capture Files" without picking + * up JPEG files or files such as that - those aren't capture files, + * and we *do* have them listed in the long list of individual file + * types, so omitting them from "All Capture Files" is the right + * thing to do. + * + * All strings in the list are allocated with g_malloc() and must be freed + * with g_free(). + */ GSList * wtap_get_all_capture_file_extensions_list(void) { @@ -327,24 +332,26 @@ wtap_get_all_capture_file_extensions_list(void) } /* - * The open_file_* routines should return: + * The open_file_* routines must return: * - * -1 on an I/O error; + * WTAP_OPEN_ERROR on an I/O error; * - * 1 if the file they're reading is one of the types it handles; + * WTAP_OPEN_MINE if the file they're reading is one of the types + * it handles; * - * 0 if the file they're reading isn't the type they're checking for. + * WTAP_OPEN_NOT_MINE if the file they're reading isn't the type + * they're checking for. * - * If the routine handles this type of file, it should set the "file_type" + * If the routine handles this type of file, it must set the "file_type" * field in the "struct wtap" to the type of the file. * - * Note that the routine does not have to free the private data pointer on + * Note that the routine does *not* have to free the private data pointer on * error. The caller takes care of that by calling wtap_close on error. * (See https://gitlab.com/wireshark/wireshark/-/issues/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. + * However, the caller *does* have to free the private data pointer when + * returning WTAP_OPEN_NOT_MINE, since the next file type will be called + * and will likely just overwrite the pointer. * * The names are used in file open dialogs to select, for files that * don't have magic numbers and that could potentially be files of @@ -549,7 +556,7 @@ wtap_register_open_info(struct open_info *oi, const gboolean first_routine) set_heuristic_routine(); } -/* De-registers a file reader by removign it from the GArray based on its name. +/* De-registers a file reader by removing it from the GArray based on its name. * This function must NOT be called during wtap_open_offline(), since it changes the array. * Note: this function will error if it doesn't find the given name; if you want to handle * that condition more gracefully, call wtap_has_open_info() first. @@ -632,9 +639,10 @@ wtap_uses_lua_filehandler(const wtap* wth) #endif /* returns the 'type' number to use for wtap_open_offline based on the - passed-in name (the name in the open_info struct). It returns WTAP_TYPE_AUTO - on failure, which is the number 0. The 'type' number is the entry's index+1, - because that's what wtap_open_offline() expects it to be. */ + * passed-in name (the name in the open_info struct). It returns WTAP_TYPE_AUTO + * on failure, which is the number 0. The 'type' number is the entry's index+1, + * because that's what wtap_open_offline() expects it to be. + */ unsigned int open_info_name_to_type(const char *name) { @@ -779,12 +787,13 @@ heuristic_uses_extension(unsigned int i, const char *extension) } /* Opens a file and prepares a wtap struct. - If "do_random" is TRUE, it opens the file twice; the second open - allows the application to do random-access I/O without moving - the seek offset for sequential I/O, which is used by Wireshark - so that it can do sequential I/O to a capture file that's being - written to as new packets arrive independently of random I/O done - to display protocol trees for packets when they're selected. */ + * If "do_random" is TRUE, it opens the file twice; the second open + * allows the application to do random-access I/O without moving + * the seek offset for sequential I/O, which is used by Wireshark + * so that it can do sequential I/O to a capture file that's being + * written to as new packets arrive independently of random I/O done + * to display protocol trees for packets when they're selected. + */ wtap * wtap_open_offline(const char *filename, unsigned int type, int *err, char **err_info, gboolean do_random) @@ -976,12 +985,13 @@ wtap_open_offline(const char *filename, unsigned int type, int *err, char **err_ /* Try all file types that support magic numbers */ for (i = 0; i < heuristic_open_routine_idx; i++) { /* Seek back to the beginning of the file; the open routine - for the previous file type may have left the file - position somewhere other than the beginning, and the - open routine for this file type will probably want - to start reading at the beginning. - - Initialize the data offset while we're at it. */ + * for the previous file type may have left the file + * position somewhere other than the beginning, and the + * open routine for this file type will probably want + * to start reading at the beginning. + * + * Initialize the data offset while we're at it. + */ if (file_seek(wth->fh, 0, SEEK_SET, err) == -1) { /* Error - give up */ wtap_close(wth); @@ -1569,7 +1579,7 @@ wtap_dump_can_write_format(int ft, const GArray *file_encaps, return TRUE; } -/** +/* * Return TRUE if we can write a file with the given GArray of * encapsulation types and the given bitmask of comment types. */ @@ -1619,7 +1629,7 @@ compare_file_type_subtypes_by_description(gconstpointer a, gconstpointer b) wtap_file_type_subtype_description(file_type_subtype_b)); } -/** +/* * Get a GArray of file type/subtype values for file types/subtypes * that can be used to save a file of a given type/subtype with a given * GArray of encapsulation types and the given bitmask of comment types. @@ -1733,7 +1743,7 @@ wtap_get_savable_file_types_subtypes_for_file(int file_type_subtype, return savable_file_types_subtypes; } -/** +/* * Get a GArray of all writable file type/subtype values. */ GArray * @@ -1797,7 +1807,9 @@ wtap_get_writable_file_types_subtypes(ft_sort_order sort_order) return writable_file_types_subtypes; } -/* String describing the file type/subtype. */ +/* + * String describing the file type/subtype. + */ const char * wtap_file_type_subtype_description(int file_type_subtype) { @@ -1808,7 +1820,9 @@ wtap_file_type_subtype_description(int file_type_subtype) return file_type_subtype_table[file_type_subtype].description; } -/* Name to use in, say, a command-line flag specifying the type/subtype. */ +/* + * Name to use in, say, a command-line flag specifying the type/subtype. + */ const char * wtap_file_type_subtype_name(int file_type_subtype) { @@ -1830,7 +1844,9 @@ wtap_register_compatibility_file_subtype_name(const char *old_name, g_strdup(new_name)); } -/* Translate a name to a capture file type/subtype. */ +/* + * Translate a name to a capture file type/subtype. + */ int wtap_name_to_file_type_subtype(const char *name) { @@ -1902,6 +1918,9 @@ wtap_pcapng_file_type_subtype(void) return pcapng_file_type_subtype; } +/* + * Determine if a file type/subtype can write a block of the given type. + */ block_support_t wtap_file_type_subtype_supports_block(int file_type_subtype, wtap_block_type_t type) @@ -1933,6 +1952,10 @@ wtap_file_type_subtype_supports_block(int file_type_subtype, return BLOCK_NOT_SUPPORTED; } +/* + * Determine if a file type/subtype, when writing a block of the given type, + * can support adding the given option to the block. + */ option_support_t wtap_file_type_subtype_supports_option(int file_type_subtype, wtap_block_type_t type, guint option) @@ -2053,13 +2076,14 @@ add_extensions_for_file_type_subtype(int file_type_subtype, GSList *extensions, } /* Return a list of file extensions that are used by the specified file type. - - If include_compressed is TRUE, the list will include compressed - extensions, e.g. not just "pcap" but also "pcap.gz" if we can read - gzipped files. - - All strings in the list are allocated with g_malloc() and must be freed - with g_free(). */ + * + * If include_compressed is TRUE, the list will include compressed + * extensions, e.g. not just "pcap" but also "pcap.gz" if we can read + * gzipped files. + * + * All strings in the list are allocated with g_malloc() and must be freed + * with g_free(). + */ GSList * wtap_get_file_extensions_list(int file_type_subtype, gboolean include_compressed) { @@ -2098,16 +2122,17 @@ wtap_get_file_extensions_list(int file_type_subtype, gboolean include_compressed } /* Return a list of all extensions that are used by all file types that - we can read, including compressed extensions, e.g. not just "pcap" but - also "pcap.gz" if we can read gzipped files. - - "File type" means "include file types that correspond to collections - of network packets, as well as file types that store data that just - happens to be transported over protocols such as HTTP but that aren't - collections of network packets, and plain text files". - - All strings in the list are allocated with g_malloc() and must be freed - with g_free(). */ + * we can read, including compressed extensions, e.g. not just "pcap" but + * also "pcap.gz" if we can read gzipped files. + * + * "File type" means "include file types that correspond to collections + * of network packets, as well as file types that store data that just + * happens to be transported over protocols such as HTTP but that aren't + * collections of network packets, and plain text files". + * + * All strings in the list are allocated with g_malloc() and must be freed + * with g_free(). + */ GSList * wtap_get_all_file_extensions_list(void) { @@ -2147,8 +2172,10 @@ wtap_free_extensions_list(GSList *extensions) g_slist_free(extensions); } -/* Return the default file extension to use with the specified file type; - that's just the extension, without any ".". */ +/* + * Return the default file extension to use with the specified file type; + * that's just the extension, without any ".". + */ const char * wtap_default_file_extension(int file_type_subtype) { @@ -2159,6 +2186,9 @@ wtap_default_file_extension(int file_type_subtype) return file_type_subtype_table[file_type_subtype].default_file_extension; } +/* + * Return whether we know how to write the specified file type. + */ gboolean wtap_dump_can_open(int file_type_subtype) { @@ -2170,6 +2200,10 @@ wtap_dump_can_open(int file_type_subtype) return TRUE; } +/* + * Return whether we know how to write a compressed file of the specified + * file type. + */ #ifdef HAVE_ZLIB gboolean wtap_dump_can_compress(int file_type_subtype) @@ -2215,7 +2249,8 @@ wtap_dump_init_dumper(int file_type_subtype, wtap_compression_type compression_t * This will fail if file_type_subtype isn't a valid * file type/subtype value, so, if it doesn't fail, * we know file_type_subtype is within the bounds of - * the table of file types/subtypes. */ + * the table of file types/subtypes. + */ if (!wtap_dump_can_open(file_type_subtype)) { /* Invalid type, or type we don't know how to write. */ *err = WTAP_ERR_UNWRITABLE_FILE_TYPE; @@ -2223,7 +2258,8 @@ wtap_dump_init_dumper(int file_type_subtype, wtap_compression_type compression_t } /* OK, we know how to write that file type/subtype; can we write - the specified encapsulation type in that file type/subtype? */ + * the specified encapsulation type in that file type/subtype? + */ *err = (*file_type_subtype_table[file_type_subtype].can_write_encap)(params->encap); /* if the err said to check wslua's can_write_encap, try that */ if (*err == WTAP_ERR_CHECK_WSLUA @@ -2239,16 +2275,17 @@ wtap_dump_init_dumper(int file_type_subtype, wtap_compression_type compression_t } /* Check whether we can open a capture file with that file type - and that encapsulation, and, if the compression type isn't - "uncompressed", whether we can write a *compressed* file - of that file type. */ - /* If we're doing compression, can this file type/subtype be + * and that encapsulation, and, if the compression type isn't + * "uncompressed", whether we can write a *compressed* file + * of that file type. + * If we're doing compression, can this file type/subtype be written in compressed form? - - (The particular type doesn't matter - if the file can't - be written 100% sequentially, we can't compress it, - because we can't go back and overwrite something we've - already written. */ + * + * (The particular type doesn't matter - if the file can't + * be written 100% sequentially, we can't compress it, + * because we can't go back and overwrite something we've + * already written. + */ if (compression_type != WTAP_UNCOMPRESSED && !wtap_dump_can_compress(file_type_subtype)) { *err = WTAP_ERR_COMPRESSION_NOT_SUPPORTED; @@ -2294,16 +2331,17 @@ wtap_dump_init_dumper(int file_type_subtype, wtap_compression_type compression_t } else if (params->encap != WTAP_ENCAP_NONE) { int snaplen; - // Generate a fake IDB if we don't have one, unless the - // file encapsulation is none. (WTAP_ENCAP_NONE either - // means that there are no interfaces, or they will be - // provided later when reading the file in single-pass mode.) - // - // XXX File types should provide their own IDBs (possibly - // fake ones generated by wtap_add_generated_idb()), in - // order to support being used as inputs for mergecap where - // pcapng is the output. This doesn't work for files with - // WTAP_ENCAP_PER_PACKET. + /* Generate a fake IDB if we don't have one, unless the + * file encapsulation is none. (WTAP_ENCAP_NONE either + * means that there are no interfaces, or they will be + * provided later when reading the file in single-pass mode.) + * + * XXX File types should provide their own IDBs (possibly + * fake ones generated by wtap_add_generated_idb()), in + * order to support being used as inputs for mergecap where + * pcapng is the output. This doesn't work for files with + * WTAP_ENCAP_PER_PACKET. + */ descr = wtap_block_create(WTAP_BLOCK_IF_ID_AND_INFO); descr_mand = (wtapng_if_descr_mandatory_t*)wtap_block_get_mandatory_data(descr); descr_mand->wtap_encap = params->encap;