From fa4f8c46a8bedacc6d48f19e72d31116a371ba28 Mon Sep 17 00:00:00 2001 From: sleske Date: Sun, 29 Jan 2012 19:19:48 +0000 Subject: [PATCH] Fix:core:Add comments and some #defines for constants git-svn-id: https://navit.svn.sourceforge.net/svnroot/navit/trunk@4917 ffa7fe5e-494d-0410-b361-a75ebd5db220 --- navit/navit/bookmarks.c | 12 ++--- navit/navit/linguistics.c | 10 ++++ navit/navit/map/binfile/binfile.c | 85 ++++++++++++++++++++++++++++----- navit/navit/search.c | 24 ++++++++++ navit/navit/zipfile.h | 99 +++++++++++++++++++++++++-------------- 5 files changed, 176 insertions(+), 54 deletions(-) diff --git a/navit/navit/bookmarks.c b/navit/navit/bookmarks.c index d74280d..96c6c67 100644 --- a/navit/navit/bookmarks.c +++ b/navit/navit/bookmarks.c @@ -371,14 +371,12 @@ bookmarks_store_bookmarks_to_file(struct bookmarks *this_, int limit,int replac return result; } -/* - * bookmarks_get_destination_file - * - * returns the name of the file used to store destinations with its - * full path - * - * arg: gboolean create: create the directory where the file is stored +/** + * @param create: create the directory where the file is stored * if it does not exist + * @return The name of the file used to store destinations with its + * full path. Should be freed using g_free. + * */ char* bookmarks_get_destination_file(gboolean create) diff --git a/navit/navit/linguistics.c b/navit/navit/linguistics.c index 2ceedeb..c79b820 100644 --- a/navit/navit/linguistics.c +++ b/navit/navit/linguistics.c @@ -230,6 +230,16 @@ static const char *special[][3]={ {"þ","t","th"}, }; +/** + * @brief Replace special characters in string (e.g. umlauts) with plain letters. + * This is useful e.g. to canonicalize a string for comparison. + * + * @param str string to process + * @param mode Replacement mode. 0=do nothing, 1=replace with single + * ASCII letter, 2=replace with multiple letters if the commonly used + * ASCII replacement has multitple letter (e.g. a-umlaut -> ae) + * @returns copy of string, with characters replaced + */ char * linguistics_expand_special(char *str, int mode) { diff --git a/navit/navit/map/binfile/binfile.c b/navit/navit/map/binfile/binfile.c index 5bccb07..26158e5 100644 --- a/navit/navit/map/binfile/binfile.c +++ b/navit/navit/map/binfile/binfile.c @@ -41,20 +41,49 @@ static int map_id; + +/** + * @brief A map tile, a rectangular region of the world. + * + * Represents a "map tile", a rectangular region of the world. The + * binfile format divides the world into tiles of different sizes for + * easy handling. + * A binfile is a ZIP archive; each member file (with the exception of + * index files) represents one tile. The data from a tile file is read + * into memory and used directly as the tile data of this struct. + *

+ * See the Navit wiki for details on the binfile format: + * + * http://wiki.navit-project.org/index.php/Navit%27s_binary_map_driver + *

+ * Note that this tile struct also maintains pointers to several current positions + * inside the tile. These are not part of the actual tile data, but are + * used for working with the data. + */ struct tile { - int *start; - int *end; - int *pos; - int *pos_coord_start; - int *pos_coord; - int *pos_attr_start; - int *pos_attr; - int *pos_next; - struct file *fi; + int *start; //!< Memory address of the buffer containing the tile data (the actual map data). + int *end; //!< First memory address not belonging to the tile data. + /**< Thus tile->end - tile->start represents the size of the tile data + * in multiples of 4 Bytes. + */ + int *pos; //!< Pointer to current position (start of current item) inside the tile data. + int *pos_coord_start; //!< Pointer to the first element inside the current item that is a coordinate. + /**< That is the first position after the header of an + * item. The header holds 3 entries each 32bit wide integers: + * header[0] holds the size of the whole item (excluding this size field) + * header[1] holds the type of the item + * header[2] holds the size of the coordinates in the tile + */ + int *pos_coord; //!< Current position in the coordinates region of the current item. + int *pos_attr_start; //!< Pointer to the first attr data structure of the current item. + int *pos_attr; //!< Current position in the attr region of the current item. + int *pos_next; //!< Pointer to the next item (the item which follows the "current item" as indicated by *pos). + struct file *fi; //!< The file from which this tile was loaded. int zipfile_num; int mode; }; + struct map_download { int state; struct map_priv *m; @@ -68,9 +97,13 @@ struct map_download { struct zip_cd *cd_copy,*cd; }; +/** + * @brief Represents the map from a single binfile. + * + */ struct map_priv { int id; - char *filename; + char *filename; //!< Filename of the binfile. char *cachedir; struct file *fi,*http; struct file **fis; @@ -120,6 +153,11 @@ struct map_rect_priv { #endif }; +/** + * @brief Represents a search on a map. + * This struct represents a search on a map; it is created + * when starting a search, and is used for retrieving results. + */ struct map_search_priv { struct map_priv *map; struct map_rect_priv *mr; @@ -263,20 +301,32 @@ binfile_read_cd(struct map_priv *m, int offset, int len) return cd; } +/** + * @brief Get the ZIP64 extra field data corresponding to a zip central + * directory header. + * + * @param cd pointer to zip central directory structure + * @return pointer to ZIP64 extra field, or NULL if not available + */ static struct zip_cd_ext * binfile_cd_ext(struct zip_cd *cd) { struct zip_cd_ext *ext; - if (cd->zipofst != 0xffffffff) + if (cd->zipofst != zip_size_64bit_placeholder) return NULL; if (cd->zipcxtl != sizeof(*ext)) return NULL; ext=(struct zip_cd_ext *)((unsigned char *)cd+sizeof(*cd)+cd->zipcfnl); - if (ext->tag != 0x0001 || ext->size != 8) + if (ext->tag != zip_extra_header_id_zip64 || ext->size != 8) return NULL; return ext; } +/** + * @param cd pointer to zip central directory structure + * @return Offset of local file header in zip file. + * Will use ZIP64 data if present. + */ static long long binfile_cd_offset(struct zip_cd *cd) { @@ -431,6 +481,11 @@ binfile_coord_get(void *priv_data, struct coord *c, int count) return ret; } +/** + * @brief + * @param + * @return + */ static void binfile_attr_rewind(void *priv_data) { @@ -2036,6 +2091,12 @@ duplicate_equal(gconstpointer a, gconstpointer b) return (da->c.x == db->c.x && da->c.y == da->c.y && g_str_equal(da->str,db->str)); } +/** + * @brief + * @param msp pointer to private map search data + * @param item item to check + * @param attr_type + */ static int duplicate(struct map_search_priv *msp, struct item *item, enum attr_type attr_type) { diff --git a/navit/navit/search.c b/navit/navit/search.c index b73b423..1a26dab 100644 --- a/navit/navit/search.c +++ b/navit/navit/search.c @@ -82,6 +82,12 @@ search_item_hash_equal(gconstpointer a, gconstpointer b) return FALSE; } +/** + * @brief Create new instance of search_list to run a search. + * + * @param ms mapset that is to be searched + * @returns new search_list + */ struct search_list * search_list_new(struct mapset *ms) { @@ -95,6 +101,11 @@ search_list_new(struct mapset *ms) static void search_list_search_free(struct search_list *sl, int level); +/** + * @brief Determine search list level for given attr_type. + * @param attr_type attribute value + * @return corresponding search list level (country=0, town=1, ...) + */ static int search_list_level(enum attr_type attr_type) { @@ -134,6 +145,13 @@ interpolation_clear(struct interpolation *inter) inter->first=inter->last=inter->curr=NULL; } +/** + * @brief Start a search. + * + * @param this search_list to use for the search + * @param search_attr attributes to use for the search + * @param partial do partial search? (1=yes,0=no) + */ void search_list_search(struct search_list *this_, struct attr *search_attr, int partial) { @@ -669,6 +687,12 @@ search_add_result(struct search_list_level *le, struct search_list_common *slc) return 0; } +/** + * @brief Get (next) result from a search. + * + * @param this_ search_list representing the search + * @return next result + */ struct search_list_result * search_list_get_result(struct search_list *this_) { diff --git a/navit/navit/zipfile.h b/navit/navit/zipfile.h index 11be798..bb3ed1c 100644 --- a/navit/navit/zipfile.h +++ b/navit/navit/zipfile.h @@ -41,51 +41,76 @@ struct zip_split { #define zip_lfh_sig 0x04034b50 #define zip_lfh_sig_rev 0x504b0304 + +//! ZIP local file header structure. + +//! See the documentation of the ZIP format for the meaning +//! of these fields. struct zip_lfh { - int ziplocsig; - short zipver; // 4 - short zipgenfld; // 6 - short zipmthd; // 8 - short ziptime; // 10 - short zipdate; // 12 - int zipcrc; // 14 - unsigned int zipsize; // 18 - unsigned int zipuncmp; // 22 - unsigned short zipfnln; // 26 - unsigned short zipxtraln; // 30 - char zipname[0]; // 34 + int ziplocsig; //!< local file header signature + short zipver; //!< minimum zip spec version needed to extract + short zipgenfld; //!< general purpose flags + short zipmthd; //!< compression method + short ziptime; //!< file modification time + short zipdate; //!< file modification date + int zipcrc; //!< CRC-32 checksum + unsigned int zipsize; //!< file size (after compression) + unsigned int zipuncmp; //!< file size (uncompressed) + unsigned short zipfnln; //!< file name length + unsigned short zipxtraln; //!< extra filed length (unused?) + char zipname[0]; //!< file name (length as given above) } ATTRIBUTE_PACKED; #define zip_cd_sig 0x02014b50 #define zip_cd_sig_rev 0x504b0102 +//! ZIP central directory structure. + +//! See the documentation of the ZIP format for the meaning +//! of these fields. struct zip_cd { - int zipcensig; - char zipcver; - char zipcos; - char zipcvxt; - char zipcexos; - short zipcflg; - short zipcmthd; - short ziptim; - short zipdat; - int zipccrc; - unsigned int zipcsiz; - unsigned int zipcunc; - unsigned short zipcfnl; - unsigned short zipcxtl; - unsigned short zipccml; - unsigned short zipdsk; - unsigned short zipint; - unsigned int zipext; - unsigned int zipofst; - char zipcfn[0]; + int zipcensig; //!< central directory signature + char zipcver; //!< zip spec version of creating software + char zipcos; //!< os compatibility of the file attribute information + char zipcvxt; //!< minimum zip spec version needed to extract + char zipcexos; //!< unused (?) + short zipcflg; //!< general purpose flag + short zipcmthd; //!< compression method + short ziptim; //!< file modification time + short zipdat; //!< file modification date + int zipccrc; //!< CRC-32 checksum + unsigned int zipcsiz; //!< file size (after compression) + unsigned int zipcunc; //!< file size (uncompressed) + unsigned short zipcfnl; //!< file name length + unsigned short zipcxtl; //!< extra field length + unsigned short zipccml; //!< comment length + unsigned short zipdsk; //!< disk number of file + unsigned short zipint; //!< internal attributes + unsigned int zipext; //!< external attributes + unsigned int zipofst; //!< offset to start of local file header + char zipcfn[0]; //!< file name (length as given above) } ATTRIBUTE_PACKED; +/** +* @brief Placeholder value for size field in the central directory if +* the size is 64bit. See the documentation for the Zip64 Extended +* Information Extra Field. +*/ +#define zip_size_64bit_placeholder 0xffffffff + +/** +* @brief Header ID for extra field "ZIP64". +*/ +#define zip_extra_header_id_zip64 0x0001 + +//! ZIP extra field structure. + +//! See the documentation of the ZIP format for the meaning +//! of these fields. struct zip_cd_ext { - short tag; - short size; - unsigned long long zipofst; + short tag; //!< extra field header ID + short size; //!< extra field data size + unsigned long long zipofst; //!< offset to start of local file header (only valid if the struct is for a ZIP64 extra field) } ATTRIBUTE_PACKED; struct zip_enc { @@ -100,6 +125,10 @@ struct zip_enc { #define zip_eoc_sig 0x6054b50 #define zip_eoc_sig_rev 0x504b0506 +//! ZIP end of central directory structure. + +//! See the documentation of the ZIP format for the meaning +//! of these fields. struct zip_eoc { int zipesig; /* end of central dir signature */ unsigned short zipedsk; /* number of this disk */ -- 2.7.4