Navit SVN
Classes | Functions | Variables

/work/compile/navit/src/navit/map.c File Reference

Contains code that makes navit able to load maps. More...

#include <glib.h>
#include <string.h>
#include "debug.h"
#include "coord.h"
#include "projection.h"
#include "item.h"
#include "map.h"
#include "maptype.h"
#include "transform.h"
#include "plugin.h"
#include "callback.h"
#include "country.h"
#include "xmlconfig.h"

Classes

struct  map
 Holds information about a map. More...
struct  map_rect
 Describes a rectangular extract of a map. More...
struct  map_search
 Holds information about a search on a map. More...

Functions

struct mapmap_new (struct attr *parent, struct attr **attrs)
 Opens a new map.
struct mapmap_ref (struct map *m)
int map_get_attr (struct map *this_, enum attr_type type, struct attr *attr, struct attr_iter *iter)
 Gets an attribute from a map.
int map_set_attr (struct map *this_, struct attr *attr)
 Sets an attribute of a map.
void map_add_callback (struct map *this_, struct callback *cb)
 Registers a new callback for attribute-change.
void map_remove_callback (struct map *this_, struct callback *cb)
 Removes a callback from the list of attribute-change callbacks.
int map_requires_conversion (struct map *this_)
 Checks if strings from a map have to be converted.
char * map_convert_string (struct map *this_, char *str)
 Converts a string from a map.
void map_convert_free (char *str)
 Frees the memory allocated for a converted string.
enum projection map_projection (struct map *this_)
 Returns the projection of a map.
void map_set_projection (struct map *this_, enum projection pro)
 Sets the projection of a map.
void map_destroy (struct map *m)
 Destroys an opened map.
void map_unref (struct map *m)
struct map_rectmap_rect_new (struct map *m, struct map_selection *sel)
 Creates a new map rect.
struct itemmap_rect_get_item (struct map_rect *mr)
 Gets the next item from a map rect.
struct itemmap_rect_get_item_byid (struct map_rect *mr, int id_hi, int id_lo)
 Returns the item specified by the ID.
void map_rect_destroy (struct map_rect *mr)
 Destroys a map rect.
struct map_searchmap_search_new (struct map *m, struct item *item, struct attr *search_attr, int partial)
 Starts a search on a map.
struct itemmap_search_get_item (struct map_search *this_)
 Returns an item from a map search.
void map_search_destroy (struct map_search *this_)
 Destroys a map search struct.
struct map_selectionmap_selection_rect_new (struct pcoord *center, int distance, int order)
 Creates a new rectangular map selection.
struct map_selectionmap_selection_dup_pro (struct map_selection *sel, enum projection from, enum projection to)
 Duplicates a map selection, transforming coordinates.
struct map_selectionmap_selection_dup (struct map_selection *sel)
 Duplicates a map selection.
void map_selection_destroy (struct map_selection *sel)
 Destroys a map selection.
int map_selection_contains_item_rect (struct map_selection *sel, struct item *item)
 Checks if a selection contains a rectangle containing an item.
int map_selection_contains_item_range (struct map_selection *sel, int follow, struct item_range *range, int count)
 Checks if a selection contains a item range.
int map_selection_contains_item (struct map_selection *sel, int follow, enum item_type type)
 Checks if a selection contains a item.
int map_priv_is (struct map *map, struct map_priv *priv)
 Checks if a pointer points to the private data of a map.
void map_dump_filedesc (struct map *map, FILE *out)
void map_dump_file (struct map *map, const char *file)
void map_dump (struct map *map)
struct itemmap_rect_create_item (struct map_rect *mr, enum item_type type_)

Variables

struct object_func map_func

Detailed Description

Contains code that makes navit able to load maps.

Navit, a modular navigation system. Copyright (C) 2005-2008 Navit Team

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 2 as published by the Free Software Foundation.

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.

This file contains the code that makes navit able to load maps. Because navit is able to open maps in different formats, this code does not handle any map format itself. This is done by map plugins which register to this code by calling plugin_register_map_type().

When opening a new map, the map plugin will return a pointer to a map_priv struct, which can be defined by the map plugin and contains whatever private data the map plugin needs to access the map. This pointer will also be used as a "handle" to access the map opened.

A common task is to create a "map rect". A map rect is a rectangular part of the map, that one can for example retrieve items from. It is not possible to retrieve items directly from the complete map. Creating a map rect returns a pointer to a map_rect_priv, which contains private data for the map rect and will be used as "handle" for this map rect.


Function Documentation

void map_add_callback ( struct map this_,
struct callback cb 
)

Registers a new callback for attribute-change.

This function registers a new callback function that should be called if the attributes of the map change.

Parameters:
this_The map to associate the callback with
cbThe callback to add

References map::attr_cbl.

void map_convert_free ( char *  str)

Frees the memory allocated for a converted string.

Parameters:
strThe string to be freed
char* map_convert_string ( struct map this_,
char *  str 
)

Converts a string from a map.

Parameters:
this_The map the string to be converted is from
strThe string to be converted
Returns:
The converted string. It has to be map_convert_free()d after use.

References map_methods::charset, and map::meth.

void map_destroy ( struct map m)

Destroys an opened map.

Parameters:
mThe map to be destroyed

References map::attr_cbl, map::attrs, map_methods::map_destroy, map::meth, and map::priv.

Referenced by map_new().

int map_get_attr ( struct map this_,
enum attr_type  type,
struct attr attr,
struct attr_iter iter 
)

Gets an attribute from a map.

Parameters:
this_The map the attribute should be read from
typeThe type of the attribute to be read
attrPointer to an attrib-structure where the attribute should be written to
iter(NOT IMPLEMENTED) Used to iterate through all attributes of a type. Set this to NULL to get the first attribute, set this to an attr_iter to get the next attribute
Returns:
True if the attribute type was found, false if not

References map::attrs, map::meth, and map::priv.

Referenced by mapset_get_map_by_name(), mapset_next(), and mapset_search_get_item().

struct map* map_new ( struct attr parent,
struct attr **  attrs 
) [read]

Opens a new map.

This function opens a new map based on the attributes passed. This function takes the attribute "attr_type" to determine which type of map to open and passes all attributes to the map plugin's function that was specified in the plugin_register_new_map_type()-call.

Note that every plugin should accept an attribute of type "attr_data" to be passed with the filename of the map to be opened as value.

Parameters:
attrsAttributes specifying which map to open, see description
Returns:
The opened map or NULL on failure

References map::attr_cbl, map::attrs, map::func, map_destroy(), map::meth, map::priv, and map::refcount.

int map_priv_is ( struct map map,
struct map_priv priv 
)

Checks if a pointer points to the private data of a map.

Parameters:
mapThe map whose private data should be checked.
privThe private data that should be checked.
Returns:
True if priv is the private data of map

References map::priv.

enum projection map_projection ( struct map this_)

Returns the projection of a map.

Parameters:
this_The map to return the projection of
Returns:
The projection of the map

References map::meth, and map_methods::pro.

void map_rect_destroy ( struct map_rect mr)

Destroys a map rect.

Parameters:
mrThe map rect to be destroyed

References map_rect::m, map_methods::map_rect_destroy, map::meth, and map_rect::priv.

Referenced by route_get_destination_description().

struct item* map_rect_get_item ( struct map_rect mr) [read]

Gets the next item from a map rect.

Returns an item from a map rect and advances the "item pointer" one step further, so that at the next call the next item is returned. Returns NULL if there are no more items.

Parameters:
mrThe map rect to return an item from
Returns:
An item from the map rect

References map_rect::m, map_methods::map_rect_get_item, map::meth, and map_rect::priv.

struct item* map_rect_get_item_byid ( struct map_rect mr,
int  id_hi,
int  id_lo 
) [read]

Returns the item specified by the ID.

Parameters:
mrThe map rect to search for the item
id_hiHigh part of the ID to be found
id_loLow part of the ID to be found
Returns:
The item with the specified ID or NULL if not found

References map_rect::m, map_methods::map_rect_get_item_byid, map::meth, and map_rect::priv.

Referenced by route_get_destination_description().

struct map_rect* map_rect_new ( struct map m,
struct map_selection sel 
) [read]

Creates a new map rect.

This creates a new map rect, which can be used to retrieve items from a map. If sel is a linked-list of selections, all of them will be used. If you pass NULL as sel, this means "get me the whole map".

Parameters:
mThe map to build the rect on
selMap selection to choose the rectangle - may be NULL, see description
Returns:
A new map rect

References map_rect::m, map_methods::map_rect_new, map::meth, map::priv, and map_rect::priv.

Referenced by route_get_destination_description().

void map_remove_callback ( struct map this_,
struct callback cb 
)

Removes a callback from the list of attribute-change callbacks.

This function removes one callback from the list of callbacks functions that should be called when attributes of the map change.

Parameters:
this_The map to remove the callback from
cbThe callback to remove

References map::attr_cbl.

int map_requires_conversion ( struct map this_)

Checks if strings from a map have to be converted.

Parameters:
this_Map to be checked for the need to convert strings
Returns:
True if strings from the map have to be converted, false otherwise

References map_methods::charset, and map::meth.

void map_search_destroy ( struct map_search this_)

Destroys a map search struct.

Parameters:
this_The map search struct to be destroyed

References map_methods::charset, map_methods::map_search_destroy, and map::meth.

Referenced by mapset_search_destroy(), and mapset_search_get_item().

struct item* map_search_get_item ( struct map_search this_) [read]

Returns an item from a map search.

This returns an item of the result of a search on a map and advances the "item pointer" one step, so that at the next call the next item will be returned. If there are no more items in the result NULL is returned.

Parameters:
this_Map search struct of the search
Returns:
One item of the result

References map_methods::map_search_get_item, and map::meth.

Referenced by mapset_search_get_item().

struct map_search* map_search_new ( struct map m,
struct item item,
struct attr search_attr,
int  partial 
) [read]

Starts a search on a map.

This function starts a search on a map. What attributes one can search for depends on the map plugin.

The OSM/binfile plugin currently supports: attr_town_name, attr_street_name The MG plugin currently supports: ttr_town_postal, attr_town_name, attr_street_name

If you enable partial matches bear in mind that the search matches only the begin of the strings - a search for a street named "street" would match to "streetfoo", but not to "somestreet". Search is case insensitive.

The item passed to this function specifies a "superior item" to "search within" - e.g. a town in which we want to search for a street, or a country in which to search for a town.

Please also note that the search for countries is not handled by map plugins but by navit internally - have a look into country.c for details. Because of that every map plugin has to accept a country item to be passed as "superior item".

Note: If you change something here, please make sure to also update the documentation of mapset_search_new() in mapset.c!

Parameters:
mThe map that should be searched
itemSpecifies a superior item to "search within" (see description)
search_attrAttribute specifying what to search for. See description.
partialSet this to true to also have partial matches. See description.
Returns:
A new map search struct for this search

References map_methods::charset, map_methods::map_search_new, map::meth, and map::priv.

Referenced by mapset_search_get_item(), and mapset_search_new().

int map_selection_contains_item ( struct map_selection sel,
int  follow,
enum item_type  type 
)

Checks if a selection contains a item.

This function checks if a selection contains a item type

Parameters:
selThe selection to be checked
followWhether the next pointer of the selection should be followed
itemThe item type to be checked
Returns:
True if there is a match, false otherwise

References map_selection::next, and map_selection::range.

int map_selection_contains_item_range ( struct map_selection sel,
int  follow,
struct item_range range,
int  count 
)

Checks if a selection contains a item range.

This function checks if a selection contains at least one of the items in range

Parameters:
selThe selection to be checked
followWhether the next pointer of the selection should be followed
rangesThe item ranges to be checked the number of elements in ranges
Returns:
True if there is a match, false otherwise

References map_selection::next, and map_selection::range.

int map_selection_contains_item_rect ( struct map_selection sel,
struct item item 
)

Checks if a selection contains a rectangle containing an item.

This function checks if a selection contains a rectangle which exactly contains an item. The rectangle is automatically built around the given item.

Parameters:
selThe selection to be checked
itemThe item that the rectangle should be built around
Returns:
True if the rectangle is within the selection, false otherwise
void map_selection_destroy ( struct map_selection sel)

Destroys a map selection.

Parameters:
selThe map selection to be destroyed

References map_selection::next.

struct map_selection* map_selection_dup ( struct map_selection sel) [read]

Duplicates a map selection.

Parameters:
selThe map selection to duplicate
Returns:
The duplicated map selection

References map_selection_dup_pro().

struct map_selection* map_selection_dup_pro ( struct map_selection sel,
enum projection  from,
enum projection  to 
) [read]

Duplicates a map selection, transforming coordinates.

This duplicates a map selection and at the same time transforms the internal coordinates of the selection from one projection to another.

Parameters:
selThe map selection to be duplicated
fromThe projection used for the selection at the moment
toThe projection that should be used for the duplicated selection
Returns:
A duplicated, transformed map selection

References map_selection::c_rect, and map_selection::next.

Referenced by map_selection_dup().

struct map_selection* map_selection_rect_new ( struct pcoord center,
int  distance,
int  order 
) [read]

Creates a new rectangular map selection.

Parameters:
centerCoordinates of the center of the new rectangle
distanceDistance of the rectangle's borders from the center
orderDesired order of the new selection
Returns:
The new map selection

References map_selection::c_rect, map_selection::order, map_selection::range, pcoord::x, coord::x, pcoord::y, and coord::y.

int map_set_attr ( struct map this_,
struct attr attr 
)

Sets an attribute of a map.

This sets an attribute of a map, overwriting an attribute of the same type if it already exists. This function also calls all the callbacks that are registred to be called when attributes change.

Parameters:
this_The map to set the attribute of
attrThe attribute to set
Returns:
True if the attr could be set, false otherwise

References map::attr_cbl, map::attrs, map::meth, and map::priv.

void map_set_projection ( struct map this_,
enum projection  pro 
)

Sets the projection of a map.

Parameters:
this_The map to set the projection of
proThe projection to be set

References map::meth, and map_methods::pro.


Variable Documentation

struct object_func map_func
Initial value:
 {
        attr_map,
        (object_func_new)map_new,
        (object_func_get_attr)map_get_attr,
        (object_func_iter_new)NULL,
        (object_func_iter_destroy)NULL,
        (object_func_set_attr)map_set_attr,
        (object_func_add_attr)NULL,
        (object_func_remove_attr)NULL,
        (object_func_init)NULL,
        (object_func_destroy)map_destroy,
        (object_func_dup)NULL,
        (object_func_ref)map_ref,
        (object_func_unref)map_unref,
}