TomTom Navigator SDK and, Installation And Use Manual

Page 1: ...TomTom Navigator SDK Version 3 0 build 193 Copyright 2002 2004 TomTom B V All rights reserved ...

Page 2: ... 3 2 Using itineraries 8 4 Extending the Location sensitive Menu 10 4 1 About external commands 10 4 2 Capabilities files 10 4 2 1 Format of the CAP file 10 4 2 2 Format of the TMT files 12 4 3 External POI files 12 4 4 Format of the requests to external applications 14 5 Communicating with TomTom Navigator from Visual Basic 15 5 1 Introduction 15 5 2 Supported API calls 15 5 2 1 Function GetSdkVe...

Page 3: ...e As String aLongitude As Long aLatitude As Long aNewLongitude As Long aNewLatitude As Long 23 5 2 26 Sub Geocode aCity As String aStreet As String aHouseNr As String 24 5 2 27 Sub GeocodeEx aCity As String aStreet As String aHouseNr As String aPostcode As String 25 5 2 28 Sub GetDataSetInfo 25 5 2 29 Sub GetRouteInfo 25 5 2 30 Sub GetRouteCoordinates aFileName As String 26 5 2 31 Sub UseGFFile aF...

Page 4: ...long aLongitudeW long aLatitudeS long aLongitudeE long aLatitudeN 34 6 2 26 INT ClearAllAvoids 34 6 2 27 INT AddItineraryLocationV01 int aIndex TItineraryLocRecV01 aLoc 34 6 2 28 INT AddItineraryLocationV02 int aIndex LPCTSTR aName long aLongitude long aLatitude int aFlags 35 6 2 29 INT SetItineraryLocationV01 int aIndex TItineraryLocRecV01 aLoc 35 6 2 30 INT SetItineraryLocationV02 int aIndex LPC...

Page 5: ...ecord long aRecordID INT aState 41 6 3 Structures and enumerations from the API 41 6 3 1 TNavVersionInfoV01 structure 41 6 3 2 TFavouriteRecV01 structure 41 6 3 3 EDirectCommands enumeration 41 6 3 4 TTTnLocationV01 structure 42 6 3 5 EGpsStatus enumeration 42 6 3 6 TGeocodeInfoV01 structure 42 6 3 7 TLocationInfoV01 structure 43 6 3 8 EPoiTypeCode enumeration 43 6 3 9 TDataSetInfoV01 structure 44...

Page 6: ...XE program will install the components required for your Pocket PC but for development you need to install additional components on your desktop computer See the section Desktop Computer below If you are upgrading from a previous version of the Navigator SDK your old VB files in the Pocket PC will stop working In that case you need to open the corresponding Visual Basic project files on your deskt...

Page 7: ...e license agreement is subject to Dutch Law and the District Court of Amsterdam is the only competent court for disputes based on the license agreement or the use of the licensed software 1 GRANT OF LICENSE This TomTom License Agreement License permits you to use one of the TomTom computer programs and the digital map data included in the accompanying package acquired with this license SOFTWARE on...

Page 8: ...ge normal wear and tear unauthorised repair or any other cause TomTom cannot be blamed for TomTom or the relevant dealer as appropriate may charge you for the repair or the replacement 3 For any claim arising out of TomTom s limited warranty or for any other claim whatsoever related to the subject matter of these terms TomTom s liability for actual damages regardless of the form of action shall be...

Page 9: ...mentation we hold the right to change or extend the format without notice we do not guarantee that details of future changed or extended formats will be made available we do not guarantee that future changed or extended formats will be compatible with the current format we do not promise that we will allow the same things for future changed or extended formats 3 Finally please note that the POI da...

Page 10: ...e POI databases They are provided with the SDK in the directory sdk poi The first tool MAKEOV2 can be used to convert a simple text file containing the coordinates and names of locations into a ready to use OV2 file The second tool DUMPOV2 can dump the content of POI databases into text format yes text that can be used by the MAKEOV2 tool The use of DUMPOV2 EXE is simple and straightforward DUMPOV...

Page 11: ...ols or documentation we do not guarantee correctness or completeness of the either the format the tools or the documentation we hold the right to change or extend the format without notice we do not guarantee that details of future changed or extended formats will be made available we do not guarantee that future changed or extended formats will be compatible with the current format we do not prom...

Page 12: ...the POI 4 bytes Y latitude coordinate of the POI L 13 bytes Name zero terminated ASCII string specifying the name of the POI EXTENDED POI RECORD 1 byte T type always 3 4 bytes L length of this record in bytes including the T and L fields 4 bytes X longitude coordinate of the POI 4 bytes Y latitude coordinate of the POI P bytes Name zero terminated ASCII string specifying the name of the POI Q byte...

Page 13: ...her Currently the following flags exist 0x00 None 0x01 Itinerary location is enabled 0x02 Itinerary location is a stop over as opposed to a pass by location 0x04 Itinerary location is departure point Should only be set for the first item in the itinerary file Example My Documents TomTom Navigator Settings Itinerary itn Here s an example of an itinerary file representing a small itinerary in France...

Page 14: ...aultDepartureV02 GetItineraryDefaultDepartureV01 GetItineraryDefaultDepartureV02 SaveItinerary LoadItinerary ClearItinerary AbortItineraryLeg GetItineraryState GetNrOfItineraryLocations Refer to the C API documentation for more information on these functions 3 Itinerary files ...

Page 15: ...on must provide a so called capabilities file that describes the application and the additional commands to be present in the location sensitive menu of Navigator and optionally the corresponding external POI file WARNING IN THE CURRENT VERSION OF NAVIGATOR THE TOTAL NUMBER OF EXTERNAL LOCATION SENSITIVE MENU COMMANDS IS LIMITED TO TWO AND THE TOTAL NUMBER OF EXTERNAL TYPES OF POINTS OF INTEREST I...

Page 16: ...name is the name of the external command as stored in requests cmd tmt file is the pathname of the optional TMT file that contains the icon for the external command and dutch title english title etc is the title of the external command in various languages as displayed in the location sensitive menu To locate the executable file for the external application Navigator first tries to find one of the...

Page 17: ...1 Mask for icon size 1 Bitmap for icon size N Mask for icon size N Index It is recommended that the bitmaps are square that is that they have the same width and height This value in pixels or the maximum of the width and the height if the bitmaps are not square is considered the size of the bitmap The format of the index is the following 4 bytes File position of bitmap 1 4 bytes File position of m...

Page 18: ...ndly name and an icon a special record of type 100 must be present at the beginning of the corresponding POI data section This type of record consists of the following fields 1 byte T type always 100 4 bytes L length of this record in bytes including the T and L fields P bytes Name zero terminated ASCII string specifying the name of the POI type L P 5 bytes Icon zero terminated ASCII string specif...

Page 19: ...ique id Where cmd name is the command name as given in the CAP file longitude and latitude are the WGS84 coordinates of an arbitrary location in degrees multiplied by 100 000 and unique id is the unique ID of a point of interest from the external POI file After the request has been created a notification is sent to the external application in the form of a Windows WM_COPYDATA message to the main w...

Page 20: ...s defines a number of functions to enable communication with the TomTom Navigator application You can view these functions using the Object Browser from within the eMbedded Visual Basic development environment All these functions can raise errors at run time that need to be handled using the standard Visual Basic error handling mechanism For example if the name given to the instance of TTNControl ...

Page 21: ...ding or geodecoding The street address will be available in the following read only properties Property LocationType As Long Type of the given location Property LocationStreet As String Street name of the given location Property LocationHouseNr1 As Long First house number close to the given location Property LocationHouseNr2 As Long Second house number close to the given location 5 2 8 Sub Navigat...

Page 22: ...escription of favorite aLongitude As Long longitude of favorite aLatitude As Long latitude of favorite Supported Since TTN 1 42 Sets favorite location information See Also ClearFavorite GetFavoriteName GetFavoriteDescription GetFavoriteLongitude GetFavoriteLatitude NavigateToFavorite 5 2 11 Function GetFavoriteName aFavorite As Long As String Command Parameters aFavorite As Long index of favorite ...

Page 23: ...voriteLongitude SetFavorite NavigateToFavorite 5 2 15 Sub NavigateToFavorite aFavorite As Long Command Parameters aFavorite As Long index of favorite base zero Supported Since TTN 1 42 Navigates to a specific favorite location See Also NavigateToCoordinate ClearFavorite SetFavorite GetFavoriteName GetFavoriteDescription GetFavoriteLongitude GetFavoriteLatitude 5 2 16 Sub ShowCoordinateOnMap aLongi...

Page 24: ...w 4 DayColors Show map in day colors works only when in navigation view 5 ShowMap Show map and instructions while driving works only when in navigation view 6 HideMap Only show instructions while driving works only when in navigation view 7 Recalculate Recalculate a route works only when in navigation view 8 ShowPOI Show points of interest on the map 9 HidePOI Hide points of interest on the map 10...

Page 25: ...degree WGS84 format Property Latitude As Long Latitude in millionths of degree WGS84 format Property Direction As Long Direction in degrees zero is north clockwise Property Speed As Long Speed in kilometers per hour If GetCurrentPosition has never been called GpsStatus will be 1 indicating that these properties don t contain valid GPS information Example The shows how the GetCurrentPosition call c...

Page 26: ...rthouse 9363 Cultural Center 7319 Exhibition Center 7385 Ferry Terminal 7352 Frontier Crossing 7366 Golf Course 9911 Hospital Polyclinic 7321 Hotel Motel 7314 Tourist Attraction 7376 Mountain Pass 9935 Museum 7317 Opera 9365 Place of Worship 7339 Post Office 7324 Rent Car Facility 7312 Rent Car Parking 9930 Restaurant 7315 Shop 9361 Shopping Center 7373 Stadium 7374 Theatre 7318 Tourist Informatio...

Page 27: ... aLatitude As Long latitude specified in WGS84 format in millionths of degree aName As String name of the POI anId As String optional external identifier of the POI Supported Since TTN 1 51 Add a point of interest to the OV2 file specified by the POI category argument The point of interest will have the name and co ordinates given by the corresponding arguments An external identifier string can al...

Page 28: ...ibility As Boolean Command Parameters aFilename As String name of the POI category aVisibility As Boolean whether to show or hide this POI type on the map Supported Since TTN 2 0 Enable or disable displaying a specific user created POI type See Also AddPoi DeleteClosestPoi DeleteAllPoi MoveClosestPoi 5 2 25 Sub MoveClosestPoi aFilename As String aLongitude As Long aLatitude As Long aNewLongitude A...

Page 29: ...ormat Property GeocodeLatitude As Long Latitude in millionths of degree WGS84 format Property GeocodeCity As String Complete city name Property GeocodeStreet As String Complete street name The geocode status property can contain the following flags 8 no location found at all the rest of the geocode properties are invalid 4 the given city name was ambiguous random possibly wrong selection made 2 th...

Page 30: ...e the same as those of Geocode 5 2 28 Sub GetDataSetInfo Supported Since TTN 2 0 Obtains information about the currently selected data set The information is available after this call in the following read only properties of the control Property DataSetName As String name of the data set Property DataSetFlags As Long explained below The data set flags property can contain the following flags 1 ind...

Page 31: ... will be 0 indicating that the rest of these properties don t contain valid information 5 2 30 Sub GetRouteCoordinates aFileName As String Command Parameters aFileName As String name of the file to store in Supported Since TTN 3 0 Store the coordinates of a list of points from the current route in the specified file 5 2 31 Sub UseGFFile aFilename As String Command Parameters aFilename As String fu...

Page 32: ...nicating with TomTom Navigator the library will first start an instance of the application if there isn t one already running Thus it should never be necessary to start TomTom Navigator from an external application explicitly Should it be necessary to close TomTom Navigator from an external application the following code can be used Example The following function will try to exit TomTom Navigator ...

Page 33: ...ation view Useful because various API calls only work in Navigation view 6 2 5 INT TryCloseCurrentOpenedDialogs Returns 0 if successful non zero value otherwise Supported Since TTN 1 42 Tries to close any opened dialogs on top Useful for API calls like navigating to a location which won t work when a dialog is on screen Some dialogs cannot be closed so this operation might fail 6 2 6 INT SwitchMap...

Page 34: ... geodecoding 6 2 9 INT NavigateToCoordinate long aLongitude long aLatitude LPCTSTR aName Command Parameters long aLongitude longitude specified in WGS84 format in millionths of degree long aLatitude latitude specified in WGS84 format in millionths of degree LPCTSTR aName the name of the location being navigated to shown in the route description Returns 0 if successful non zero value otherwise Supp...

Page 35: ...ite information See Also ClearFavorite SetFavoriteV01 NavigateToFavorite 6 2 13 INT NavigateToFavorite INT aIndex Command Parameters INT aIndex index of favorite base zero Returns 0 if successful non zero value otherwise Supported Since TTN 1 42 Navigates to a specific favorite with index aIndex base zero See Also NavigateToCoordinate ClearFavorite SetFavoriteV01 GetFavoriteV01 6 2 14 INT ShowCoor...

Page 36: ...Command command to execute Returns 0 if successful non zero value otherwise Supported Since TTN 1 42 Various commands to change a setting or instruct TomTom Navigator to perform a certain task Example The following example invocation call demonstrates how to switch the map display to night colors INT error CTomTomNavigatorCom SendDirectCommand KCommandNightColors if error AfxMessageBox TEXT Failed...

Page 37: ...ry long aLongitude longitude specified in WGS84 format in millionths of degree long aLatitude latitude specified in WGS84 format in millionths of degree LPCTSTR aName name of the POI LPCTSTR anId optional external identifier of the POI Returns 0 if successful non zero value otherwise Supported Since TTN 1 51 Add a point of interest to the OV2 file specified by the POI category argument The point o...

Page 38: ... after that See Also AddPoi DeleteClosestPoi MakeUserPoiVisible MoveClosestPoi 6 2 22 INT MakeUserPoiVisible LPCTSTR aFilename INT aVisibility Command Parameters LPCTSTR aFilename name of the POI category INT aVisibility whether to show or hide this POI type on the map Returns 0 if successful non zero value otherwise Supported Since TTN 2 0 Enable or disable displaying a specific user created POI ...

Page 39: ...W long aLatitudeS long aLongitudeE long aLatitudeN Command Parameters long aLongitudeW western longitude specified in WGS84 format in millionths of degrees long aLatitudeS southern latitude specified in WGS84 format in millionths of degrees long aLongitudeE eastern longitude specified in WGS84 format in millionths of degrees long aLatitudeN northern latitude specified in WGS84 format in millionths...

Page 40: ...orted Since TTN 3 0 Set the information of a location in the itinerary 6 2 30 INT SetItineraryLocationV02 int aIndex LPCTSTR aName long aLongitude long aLatitude int aFlags Command Parameters int aIndex index in the itinarary LPCTSTR aName Name of this location in the itinerary long aLongitude longitude specified in WGS84 format in millionths of degree long aLatitude latitude specified in WGS84 fo...

Page 41: ...ry 6 2 34 INT EnableItineraryLocation int aIndex INT aState Command Parameters int aIndex index in the itinerary INT aState 0 for disable non zero for enable Returns 0 if successful non zero value otherwise Supported Since TTN 3 0 Enable or disable a location in the itinerary 6 2 35 INT IsItineraryLocationEnabled int aIndex INT aState Command Parameters int aIndex index in the itinerary INT aState...

Page 42: ...e default departure point for the itinerary 6 2 39 INT GetItineraryDefaultDepartureV01 TItineraryLocRecV01 aLoc Command Parameters TItineraryLocRecV01 aLoc record specifying itinerary location Returns 0 if successful non zero value otherwise Supported Since TTN 3 0 Get the default departure point for the itinerary 6 2 40 INT GetItineraryDefaultDepartureV02 TCHAR aName 128 long aLongitude long aLat...

Page 43: ...nerary 6 2 45 INT AbortItineraryLeg Returns 0 if successful non zero value otherwise Supported Since TTN 3 0 Abort navigation to the next stop over in the itinerary 6 2 46 INT GetItineraryState int aState Command Parameters int aState state of the itinerary Returns 0 if successful non zero value otherwise Supported Since TTN 3 0 Get the current state of the itinerary 6 2 47 INT GetCurrentStopover ...

Page 44: ...turn the co ordinates of the found location and its complete city and street names in the geocode information argument If the street name argument is empty the function will try to find the center of the city specified by the city name argument The house number is always ignored in versions of TomTom Navigator prior to 2 0 If no location is found with city and street names exactly matching the arg...

Page 45: ... version 2 22 of Navigator the postal code will be only used as a help in trying to find the city If no location is found with city and street names exactly matching the arguments then a city and a street will be chosen with names as similar as possible to the given ones This will be indicated in the status field of the geocode information argument 6 2 52 INT GetDataSetInfoV01 TDataSetInfoV01 aDat...

Page 46: ...onInfoV01 structure The struct TNavVersionInfoV01 has the following fields char iVersion 16 INT iBuildNumber 6 3 2 TFavouriteRecV01 structure The favorites record has the following fields TCHAR iName 64 TCHAR iDescription 128 long iLongitude long iLatitude 6 3 3 EDirectCommands enumeration EDirectCommands is an enumeration with the following items KCommandSoundOn turn spoken voice instructions on ...

Page 47: ...automatic recalculation of the route KCommandAutoZoomOn turn on automatic zooming KCommandAutoZoomOff turn off automatic zooming 6 3 4 TTTnLocationV01 structure The TTTnLocationV01 struct contains the following fields long iLongitude Longitude and latitude in millionths of degree WGS84 format long iLatitude int iDirection Direction in degrees zero is north continuing in clockwise direction int iSp...

Page 48: ...ion is a node i e a crossing KLocationTypeRoad the location is a street 6 3 8 EPoiTypeCode enumeration The Point of Interest types that are supported are KPoiTypeGovernmentOffice KPoiTypeMountainPeak KPoiTypeOpenParking KPoiTypeParkingGarage KPoiTypePetrolStation KPoiTypeRailwayStation KPoiTypeRestArea KPoiTypeAirport KPoiTypeCarDealer KPoiTypeCasino KPoiTypeChurch KPoiTypeCinema KPoiTypeCityCente...

Page 49: ...ampingGround KPoiTypeParkRecreationArea KPoiTypeConventionCentre KPoiTypeLeisureCentre KPoiTypeYachtBasin 6 3 9 TDataSetInfoV01 structure The TDataSetInfoV01 struct contains the following fields TCHAR iDataSetName 128 name of the data set unsigned long iFlags explained below The flags field can contain the following flags KHouseNrPrefixed indicates that the house numbers are written before the str...

Page 50: ...tude co ordinates in millionths of degree WGS84 format long iLatitude int iFlags flags explained below The flags field can contain the following KItineraryLocIsStopOver the location specified is a stopover KItineraryDefaultDeparture the location specified is the default departure point 6 3 12 EProperty enumeration These are all the proerties you can set KPropertyColorStyle The colour style used in...

Page 51: ...nuCmd2 KPropertyPoiQuickMenuCmd3 KPropertyPoiQuickMenuCmd4 You can use the following colour styles KColorStyleBelgica KColorStyleBrittanica KColorStyleGermanica KColorStyleGreys KColorStyleAmerica KColorStyleAstra KColorStyleAfrica KColorStyleAntarctica The following values can be used for the indicators on the screen KIndicatorTimeToDestination Time left to destination KIndicatorCurrentTime Curre...

Page 52: ...ickCmdTurnSoundOn switch on the sound KQuickCmdUseDaylightColors switch to daylight colours Additionally the following functions are only available to assign to hardware buttons KQuickCmdDisplayCompassOnMap display a compass on the map KQuickCmdFavorites go to favourites menu KQuickCmdInstructions Show instructions for the route KQuickCmdMap switch to map view KQuickCmdNavigateToAddress Navigate t...

Page 53: ... the other hand there are obvious disadvantages to refreshing files too often e g every few seconds in terms of power drain application speed degradation etc Tips For some applications it may be useful to switch between a limited set of pre defined fixed files For some applications it may be useful to use a single pre defined file of which records are enabled or disabled by the simple action of st...

Page 54: ...he current screen NOTE It is highly recommended in the interest of processing speed that you always provide a skipper record that specifies the surrounding rectangle for all the rectangle dependent records in the whole file together IGNORE type 0 Records with type 0 are completely ignored by the application 8 BYTES HEADER X bytes Ignored content NOTE Uses of this type of record range from permanen...

Page 55: ...set icon is only shown if the current GPS position is inside the specified rectangle 4 bytes First parameter of the message to be sent to the callback window 4 bytes Second parameter of the message to be sent to the callback window 1 byte W length of the name of the callback window INcluding zero termination 1 byte M length of the name of the message to be sent to the callback window INcluding zer...

Page 56: ...btained by using the Windows OS function RegisterWindowMessage and the two message parameters correspond to the WPARAM and LPARAM fields of the message structure respectively NOTE TomTom Navigator will never show more than 3 warning icons No matter how many icons match the specified criteria only the first three will be displayed and activated Please note that each string needs to be less than 256...

Page 57: ...ovided are TTNControl ARM cab for the ARM CPU TTNControl MIPS cab for the MIPS CPU TTNControl SH3 cab for the SH3 CPU The CAB file will install the components TTNCom dll TTNControl ocx and set settings in the registry to configure the SDK components Please be warned that the installation must take place in the default install directory If the file TTNCom dll is not installed in the Windows directo...

Page 58: ...ve any commands such as GPS reset from TomTom Navigator The Reset GPS for this location feature in TomTom Navigator will have no effect and you will need to implement such features yourself 9 2 Providing GPS information 9 2 1 Configuring TomTom Navigator In TomTom Navigator go to the GPS information screen and select the GPS tab Choose either the NMEA 0183v2 Driver or the SiRF Driver as your GPS d...

Page 59: ...er functions Warning Although it is possible to create multiple simultaneous sessions this is not recommended as the receiver of the feed will only recognise one feed stream 9 2 4 VOID DetachFromTomTomGPSEngine DWORD aHandle Command Parameters DWORD aHandle the session handle returned by a succesful call to AttachToTomTomGPSEngine Supported Since GPS 2 00 Terminates a session between your applicat...