Navigon INTEGRATION KIT 4.0 User Manual
User’s manual
NAVIGON Integration Kit 4.0
as on October 2004
Impressum
NAVIGON GmbH
Berliner Platz 11
D-97080 Würzburg
Hotline (dtms-Service, 0,12 €/min): +49 180-5-NAVIGON (+49 180-5-6284466)
The information contained herein may be changed at any time without prior notification. This manual nor any
parts thereof may not be reproduced for any purpose whatsoever without the express written consent of
NAVIGON GmbH, nor transmitted in any form either electronically or mechanically, including photocopying and
recording.
Copyright 2004, NAVIGON GmbH
All rights reserved.
Table of contents
1 Introduction................................................................6
1.1
On this manual................................................................. 7
1.2
Specification of services .................................................... 7
1.2.1 Supported operating systems .................................. 8
1.3
System requirements ........................................................ 9
1.4
Installation ...................................................................... 9
1.4.1 Installation of the Windows 2000/XP version ............10
1.4.2 Installation of the Windows CE version ....................10
1.5
Search facilities and conventions .......................................11
1.6
Liability ..........................................................................11
1.6.1 Support ...............................................................12
1.7
Trademarks ....................................................................12
User’s manual NAVIGON Integration Kit 4.0
2 Programming interfaces............................................13
2.1
Requirements for using NIK with a development environment
14
2.2
2.3
2.4
2.1.1 Using the interfaces ..............................................14
2.1.2 A survey on the interfaces .....................................15
IMNNIK ..........................................................................15
2.2.1 MNOpen() method ................................................16
2.2.2 MNClose() method ................................................16
2.2.3 GetMNOpen() method ...........................................17
2.2.4 GetMNVersion() method ........................................17
2.2.5 Starting and closing NIK ........................................18
IADDRESS ......................................................................19
2.3.1 OpenAddress() method) ........................................20
2.3.2 CloseAdress() method ...........................................20
2.3.3 SearchFirstCityAddress() method............................21
2.3.4 SearchFirstCityPostalCodeAddress() method ............22
2.3.5 SearchNextCityAddress() method ...........................23
2.3.6 SearchFirstStreetAddress() method.........................25
2.3.7 SearchNextStreetAddress() method ........................27
2.3.8 SearchPoiByRadiusAddress() method ......................28
2.3.9 SearchNextPoiAddress() method .............................30
2.3.10 ConvertCoordInAddress() method .........................31
2.3.11 ConvertCoordInAddress2() method .......................32
2.3.12 ConvertCoordInCountry() method .........................33
IROUTING ......................................................................34
2.4.1 OpenRoute() method.............................................35
2.4.2 CloseRoute() method ............................................36
2.4.3 AddDestCoordRoute() method ................................36
2.4.4 GetDestCoordRoute() method ................................37
2.4.5 ClearDestCoordRoute() method ..............................38
2.4.6 StartRoute() method .............................................38
2.4.7 ShowRoute() method ............................................39
2.4.8 ClearRoute() method .............................................39
2.4.9 ZoomInRoute() method .........................................40
2.4.10 ZoomOutRoute() method .....................................40
Table of contents - I -
User’s manual NAVIGON Integration Kit 4.0
2.5
2.6
2.4.11 ShowDownRoute() method...................................40
2.4.12 ShowUpRoute() method .......................................41
2.4.13 ShowLeftRoute() method .....................................41
2.4.14 ShowRightRoute() method ...................................41
2.4.15 ShowStartPointRoute() method.............................42
2.4.16 ShowEndPointRoute() method ..............................42
2.4.17 SetRotationRoute() method ..................................43
2.4.18 GetRotationRoute() method..................................43
2.4.19 GetStatusRoute() method ....................................44
2.4.20 GetResultRoute() method.....................................44
2.4.21 MapShowRoute() method .....................................45
2.4.22 GetFirstWayListRoute() method ............................45
2.4.23 GetNextWayListRoute() method ............................46
2.4.24 SetZoomLevelInRoute() method ...........................47
2.4.25 GetZoomLevelInRoute() method ...........................48
2.4.26 SetMaxResolutionRoute() method .........................48
2.4.27 GetMaxResolutionRoute() method .........................49
2.4.28 ChangeGeoToMapCoordRoute() method .................49
2.4.29 ChangeMapToGeoCoordRoute() method .................50
2.4.30 Example for route calculation................................51
IPOSITION......................................................................52
2.5.1 OpenPosition() method ..........................................53
2.5.2 ClosePosition() method..........................................54
2.5.3 StartPosition() method ..........................................54
2.5.4 GetPosition() method ............................................55
2.5.5 ZoomInPosition() method ......................................55
2.5.6 ZoomOutPosition() method ....................................56
2.5.7 ShowDownPosition() method ..................................56
2.5.8 ShowUpPosition() method ......................................56
2.5.9 ShowLeftPosition() method ....................................57
2.5.10 ShowRightPosition() method.................................57
2.5.11 SetRotationPosition() method ...............................57
2.5.12 GetRotationPosition() method ...............................58
2.5.13 MapShowPosition() method ..................................59
2.5.14 SetBirdViewPosition() method...............................59
2.5.15 SetZoomLevelInPosition() method.........................60
2.5.16 GetZoomLevelInPosition() method ........................60
2.5.17 SetMaxResolutionPosition() method.......................61
2.5.18 GetMaxResolutionPosition() method ......................61
2.5.19 ChangeGeoToMapCoordPosition() method ..............62
2.5.20 ChangeMapToGeoCoordPosition() method ..............62
INAVIGATION .................................................................64
2.6.1 OpenNavigation() method ......................................66
2.6.2 CloseNavigation() method ......................................67
2.6.3 SetDestIdNavigation() method ...............................67
2.6.4 GetDestIdNavigation() method ...............................68
2.6.5 SetDestCoordNavigation() method ..........................68
2.6.6 GetDestCoordNavigation() method..........................69
2.6.7 SetDestTrackNavigation() method...........................70
2.6.8 StartNavigation() method ......................................71
2.6.9 ShowRouteNavigation() method .............................71
2.6.10 RepeatLastAdviceNavigation() method ...................72
2.6.11 ZoomInNavigation() method.................................72
2.6.12 ZoomOutNavigation() method ..............................72
2.6.13 ShowDownNavigation() method ............................73
2.6.14 ShowUpNavigation() method ................................73
2.6.15 ShowLeftNavigation() method...............................73
- II - Table of contents
User’s manual NAVIGON Integration Kit 4.0
2.7
2.8
2.6.16 ShowRightNavigation() method.............................74
2.6.17 ShowStartPointNavigation() method ......................74
2.6.18 ShowEndPointNavigation() method........................74
2.6.19 SetRotationNavigation() method ...........................75
2.6.20 GetRotationNavigation() method ...........................75
2.6.21 GetStatusNavigation() method..............................76
2.6.22 GetRoutingResultNavigation() method ...................76
2.6.23 ShematicViewOpenNavigation() method.................77
2.6.24 ShematicViewShowNavigation() method ................78
2.6.25 DistanceBarOpenNavigation() method ...................79
2.6.26 DistanceBarShowNavigation() method ...................80
2.6.27 MapShowNavigation() method ..............................80
2.6.28 SetBirdViewNavigation() method...........................81
2.6.29 GetFirstWayListNavigation() method......................81
2.6.30 GetNextWayListNavigation() method .....................82
2.6.31 SetZoomLevelInNavigation() method.....................83
2.6.32 GetZoomLevelInNavigation() method ....................84
2.6.33 SetMaxResolutionNavigation() method...................84
2.6.34 GetMaxResolutionNavigation() method ..................85
2.6.35 ChangeGeoToMapCoordNavigation() method ..........85
2.6.36 ChangeMapToGeoCoordLocationMap() method........86
2.6.37 Examples ...........................................................87
IOPTIONS.......................................................................89
2.7.1 SetRoutingAlgorithmOptions() method ....................90
2.7.2 SetRoutingAlgorithmOptions2() method...................91
2.7.3 GetRoutingAlgorithmOptions() method ....................91
2.7.4 GetRoutingAlgorithmOptions2() method ..................92
2.7.5 SetRoutingAvoidTypeOptions() method....................93
2.7.6 GetRoutingAvoidTypeOptions() method ...................94
2.7.7 SetStyleMapOptions() method ................................95
2.7.8 GetStyleMapOptions() method ................................95
2.7.9 SetKeyboardMapModeOptions() method ..................96
2.7.10 GetKeyboardMapModeOptions() method ................96
2.7.11 GetBasicMapFolderOptions() method .....................97
2.7.12 SetBasicMapFolderOptions() method .....................97
2.7.13 GetMapsNumberOptions() method ........................98
2.7.14 GetMapsPathsOptions() method ............................98
2.7.15 SetCurrentMapOptions() method...........................99
2.7.16 GetCurrentMapOptions() method ..........................99
2.7.17 GetRadioMutingOptions() method .......................100
2.7.18 SetRadioMutingOptions() method........................100
2.7.19 GetLanguageCodeOptions() method ....................101
2.7.20 SetLanguageCodeOptions() method ....................101
2.7.21 GetDistUnitOptions() method..............................102
2.7.22 SetDistUnitOptions() method ..............................102
2.7.23 SetLouderOptions() method ...............................103
2.7.24 SetQuieterOptions() method ...............................103
2.7.25 SetPoiMapFolderOptions() method ......................104
2.7.26 OpenPoiMapsOptions() method ...........................104
2.7.27 ClosePoiMapsOptions() method ...........................105
IGPS ............................................................................106
2.8.1 OpenGPS() method .............................................107
2.8.2 CloseGPS() method .............................................107
2.8.3 GetStatusGPS() method ......................................108
2.8.4 SetGpsReceiverType() method .............................109
2.8.5 GetGpsReceiverType() method .............................109
2.8.6 SetGpsReceiverPort() method ..............................110
Table of contents - III -
User’s manual NAVIGON Integration Kit 4.0
2.8.7 GetGpsReceiverPort() method ..............................110
2.8.8 SetGpsReceiverBaudRate() method.......................111
2.8.9 GetGpsReceiverBaudRate() method ......................111
2.8.10 SetDataSourceGps() method ..............................112
2.8.11 SetDataGps() method ........................................113
2.9
ITMC............................................................................114
2.9.1 OpenTmc() method .............................................115
2.9.2 OpenTmc2() method ...........................................116
2.9.3 CloseTmc() method.............................................116
2.9.4 GetStatusTmc() method ......................................117
2.9.5 UpdateTmc() method ..........................................118
2.9.6 GetRadioStationTmc() method..............................118
2.9.7 SearchFirstMessageTmc() method.........................120
2.9.8 SearchNextMessageTmc() method ........................121
2.9.9 GetLastKnownFreqTmc() method ..........................123
2.9.10 GetLastKnownPiCodeTmc() method .....................123
2.10 ILOCATIONMAP .............................................................124
2.10.1 OpenLocationMap() method................................125
2.10.2 CloseLocationMap() method ...............................126
2.10.3 StartLocationMap() method ................................126
2.10.4 ShowCoordInLocationMap() method ....................126
2.10.5 ShowObjectIDInLocationMap() method ................128
2.10.6 ZoomInLocationMap() method ............................129
2.10.7 ZoomOutLocationMap() method ..........................129
2.10.8 ShowDownLocationMap() method .......................129
2.10.9 ShowUpLocationMap() method............................130
2.10.10 ShowLeftLocationMap() method ........................130
2.10.11 ShowRightLocationMap() method ......................130
2.10.12 SetZoomLevelInLocationMap() method ..............131
2.10.13 GetZoomLevelInLocationMap() method ..............131
2.10.14 SetMaxResolutionLocationMap() method ............132
2.10.15 GetMaxResolutionLocationMap() method ............132
2.10.16 ChangeGeoToMapCoordLocationMap() method .... 133
2.10.17 ChangeMapToGeoCoordLocationMap() method .... 133
2.10.18 SetReceivePointLocationMap() method...............134
2.10.19 GetReceivePointLocationMap() method ..............135
2.10.20 MapShowLocationMap() method ........................135
2.11 ITRACK ........................................................................137
2.11.1 RecordTrack() method .......................................138
2.11.2 GetRecordTrackMode() method ...........................138
2.11.3 GetCoordTrack() method ...................................139
2.11.4 SetAngleTrack() method ....................................140
2.11.5 GetAngleTrack() method ....................................140
2.11.6 SetMaxNumberTrack() method ...........................141
2.11.7 GetMaxNumberTrack() method ...........................141
2.12 ISIMULATION................................................................142
2.12.1 CreateGPSFile() method.....................................143
2.12.2 StartSimulationGPS() method .............................144
2.12.3 StopSimulationGPS () method ............................144
2.12.4 StartSimulationTMC() method ............................145
2.12.5 StopSimulationTMC() method .............................145
2.12.6 SetSimulationSpeed() method ............................146
2.12.7 GetSimulationSpeed() method ............................146
2.12.8 SetSimulationPosition() method ..........................147
2.12.9 GetSimulationPosition() method..........................147
2.13 IMNNIKEvents...............................................................148
- IV - Table of contents
User’s manual NAVIGON Integration Kit 4.0
2.13.1 Declaring an event class ....................................149
2.13.2 Implementation in your application .....................149
2.13.3 RTProgressCallback() method .............................150
2.13.4 TMCMessageActivateCallback() method ...............150
2.13.5 TMCMessageDeactivateCallback() method ............151
2.13.6 GPSMessageCallback() method ...........................152
2.13.7 NAVAudioAdviceCallback() method......................152
2.13.8 NAVVisualAdviceCallback() method .....................153
2.13.9 LButtonDownNavigationMapCallback() method .....154
2.13.10 MouseMoveNavigationMapCallback() method ......154
2.13.11 LButtonDownRouteMapCallback() method ..........155
2.13.12 MouseMoveRouteMapCallback() method .............156
2.13.13 LButtonDownPositionMapCallback() method........ 156
2.13.14 MouseMovePositionMapCallback() method .......... 157
2.13.15 LButtonDownLocationMapCallback() method ....... 158
2.13.16 MouseMoveLocationMapCallback() method .........158
2.13.17 MAPKeyBoardCallback() method........................159
2.13.18 NAVOnDrawingCallback() method......................160
2.13.19 RoutingOnDrawingCallback() method.................161
2.13.20 PositionOnDrawingCallback() method.................162
2.13.21 LocationOnDrawingCallback() method................163
2.13.22 NAVOnRunningCallback() method......................164
2.13.23 NAVOnStopCallback() method ...........................164
3 Appendix.................................................................165
3.1
3.2
3.3
Appendix A: Enumerations..............................................166
Appendix B: User defined POI (optional)...........................174
Appendix C: Demo application.........................................174
4 Glossary ..................................................................175
Table of contents - V -
User’s manual NAVIGON Integration Kit 4.0
1 Introduction
Topics covered in this chapter:
1.1 On this manual page 7
1.2 Specification of services page 7
Supported operating systems
1.3 System requirements page 9
1.4 Installation page 9
Installation of the Windows 2000/XP version
Installation of the Windows CE version
1.5 Search facilities and conventions page 11
1.6 Liability page 11
Support
1.7 Trademarks page 12
- 6 - On this manual
User’s manual NAVIGON Integration Kit 4.0
1.1 On this manual
Introduction This manual describes the NAVIGON Integration Kit (NIK). It
explains the installation procedure and the registration of the
COM DLL, its methods, and the complete interface functionality.
Notice: Your CD contains an online help that also explains all
methods. Use the online help to look for contents quickly and
efficiently.
1.2 Specification of services
General survey on
NIK
COM-DLL NIK is a COM-DLL providing several interfaces which may be
Features NIK supports all features that are typical for navigation.
The NAVIGON Integration KIT (NIK) is a worldwide unique
development environment which meets the requirements of
individual and company specific claims. Based on NIK, NAVIGON
and their partners are developing customised navigation and
integration solutions – mobile navigation custom-tailored to your
requirements.
NIK offers a unique combination of both powerful navigation and
access to the company’s database using a standardised COM
interface.
applied irrespective of the used programming language (as e.g.
C++, Visual Basic, or Java). Thus it enables the easy integration
of an entire navigation solution into third-party systems as route
planning, order processing, or merchandise management
(transfer of positional coordinates or address data in both
directions).
The map for navigation may be displayed in any window using a
windows handle.
Additionally, it provides the possibility to represent data
transmitted by third party systems.
Introduction - 7 -
User’s manual NAVIGON Integration Kit 4.0
Methods The Integration Kit provides numerous methods for using the
functionality of the navigation software. Make use of the following
interfaces:
Interface Description
IMNNIK Running and closing the navigation software.
IADDRESS Connecting to the database of places.
IROUTING Route planning and calculation.
IPOSITION Displaying the current position on the map.
INAVIGATION Navigation to any destination.
IOPTIONS Determining global parameters.
IGPS Getting current GPS data.
ITMC Including TMC data.
ILOCATIONMAP Displaying customised maps.
ITRACK Recording tracks.
ISIMULATION Using GPS / TMC simulation files.
IMNNIKEvents Event handling.
1.2.1 Supported operating systems
Operating systems NIK supports the following operating systems:
MS Windows 2000 (with service pack 4)
MS Windows XP (with service pack 1)
MS Windows Mobile 2003
The NAVIGON Integration Kit has been tested under the
following environments:
Platform Operating
system
Notebook and
PC
Notebook and
PC
Pocket PC Windows Mobile
Windows 2000
Windows XP
Windows 2000
Windows XP
2003
Programming
language
C++ Microsoft Visual
Visual Basic Microsoft Visual
C++ Microsoft
Development
environment
Studio 6.0
Basic 6.0
eMbedded Visual
C++ 4.0
Notice: For further information on using the NAVIGON
Integration Kit with your preferred development environment,
please refer to the demo software.
- 8 - Specification of services
User’s manual NAVIGON Integration Kit 4.0
1.3 System requirements
PC The following requirements must be fulfilled for Integration Kit
based applications to be developed on a PC:
Pentium PC 266 MHz
MS Windows 2000 (with service pack 4) or
MS Windows XP (with service pack 1)
32x CD drive
DVD drive
64 MB RAM (128 MB RAM recommended)
VGA-graphics adapter with at least 32000 colours
Microsoft compatible mouse
about 40 MB of free hard disk capacity for the program data
optional: about 1.1 GB of free hard disk capacity for the
complete map of Europe
Pocket PC The following requirements must be fulfilled for Integration Kit
based applications to be developed on a Pocket PC:
ARM Processor
Windows Mobile 2003
64 MB RAM (128 MB RAM recommended)
1.4 Installation
Survey The NAVIGON Integration Kit is delivered on CDs and
contains:
NIK-DLL
Map of Europe
Files for programming (header and tlb)
Demo application
Software MapExport (Windows CE version only)
Installation 1. Insert CD 1 and run Setup.exe.
2. Select either the User’s mode or the Developer’s mode.
You want to... then...
install only the NIK runtime
environment,
install the development
environment with all files,
and the demo application,
select User’s mode.
select Developer’s mode.
Introduction - 9 -
User’s manual NAVIGON Integration Kit 4.0
Demo application Having executed the installation successfully, you may run the
NAVIGON Integration Kit demo application for getting
information on how to integrate NIK into your application.
Attention: You will have to export a map with MapExport
before running the demo application when you are using the
Windows CE version.
1.4.1 Installation of the Windows 2000/XP version
Windows 2000/XP,
all modes
Windows 2000/XP,
developer’s mode
NIK-SDK user’s manual
Setup installs the navigation software, the map of Europe, and
the MapExport software; and it registers the NIK-DLL with the
operating system.
In developer’s mode, setup copies the following additional files to
the program folder:
Interface files (Header, TLB, LIB und DLL)
Source code of the demo application
Demo application
1.4.2 Installation of the Windows CE version
Windows CE, all
modes
Windows CE,
developer’s mode
NIK-SDK user’s manual
Setup installs the NIK runtime environment; and it registers the
NIK-DLL with the operating system.
In developer’s mode, setup copies the following additional files to
the PC:
Interface files (Header, TLB, LIB und DLL)
Code for the demo application
Demo application
Map of Europe
MapExport software
- 10 - Installation
User’s manual NAVIGON Integration Kit 4.0
1.5 Search facilities and conventions
This manual offers the following search facilities: Find information
quickly
Conventions The conventions on the fonts and symbols used in this manual
In the footnote at the bottom of the page, you may check
which chapter and which section you are actually reading.
A glossary at the end of the manual contains explanations on
the technical terms used in this manual.
are explained in the two following tables:
Font Signification
bold Buttons, icons, names of entry fields, and
elements of the software’s user interface.
Also used for highlighting warnings and
notices.
bold italic Registered names and trademarks.
SMALL CAPITALS
Source code
Symbol Signification
Window and dialogue box titles.
File names and source code.
Indicates hints and notices that may ease the
use of Configuration Kit.
Indicates additional information.
Warns against dangers that might cause
damage to objects and persons.
1.6 Liability
Limitation of liability The present software and the present manual are subject to
change without notice. NAVIGON GmbH may not be liable for the
correctness of the information contained in this manual nor for
any damages resulting from the use of this manual.
To improve the quality of our products and our services, we
appreciate all suggestions for improvement and all error notices.
Introduction - 11 -
User’s manual NAVIGON Integration Kit 4.0
1.6.1 Support
You need help? Call our support staff for Telephone support:
Mondays to Fridays 9am to 6pm
+49 180-5-NAVIKIT (0180-5-6284548)
(dtms-Service, 0,12 €/min)
Or call our Fax support:
+49 180-5-6284444
(dtms-Service, 0,12 €/min)
On the web site of NAVIGON GmbH (http://www.navigon.com)
you will find a Support section with a FAQ-list which gives
answers to frequently asked questions.
1.7 Trademarks
Registered
trademarks
Outlook, Windows, Access, Excel, SQL Server, Visual Studio,
All brands and trademarks mentioned in this document are
possibly registered by third party and subject to the current
legislation and to the rights of their respective owners without
reservation. All mentioned names of products, societies, or
brands may be registered trademarks of their respective owners.
Every right that is not explicitly accorded is reserved.
The absence of an explicit labelling of registered trademarks does
not allow the conclusion that this brand was not subject to the
rights of third party.
Visual Basic, eMbedded Visual C++, and ActiveSync are
registered trademarks of the Microsoft Corporation.
- 12 - Trademarks
User’s manual NAVIGON Integration Kit 4.0
2 Programming interfaces
Topics covered in this chapter:
2.1 Requirements for using NIK with a development environment page 14
2.2 IMNNIK page 15
2.3 IADDRESS page 19
2.4 IROUTING page 34
2.5 IPOSITION page 52
2.6 INAVIGATION page 64
2.7 IOPTIONS page 89
2.8 IGPS page 106
2.9 ITMC page 114
2.10 ILOCATIONMAP page 124
2.11 ITRACK page 137
2.12 ISIMULATION page 142
2.13 IMNNIKEvents page 148
Programming interfaces - 13 -
User’s manual NAVIGON Integration Kit 4.0
2.1 Requirements for using NIK with a development
environment
Survey
The header file NIKxx.h, the object library NIKxx.TLB, and the
NIKxx.DLL are the programming interface. They enable the use
of the other interfaces with your specific environment. Your
project’s development environment (e.g. Microsoft Visual
Studio) must therefore be bound to these files.
Platform Files
MS Windows 2000
MS Windows XP
Windows Mobile
2003
2.1.1 Using the interfaces
Interface
instantiation
Releasing an
interface instance
CoCreateInstance creates an instance of IMNNIK
QueryInterface creates instances of all other interfaces
CComObject::CreateInstance creates an instance of
IMNNIKEvents
AtlAdvise connects to the NAVIGON Integration Kit
Release releases instances of interfaces
AtlUnadvise closes the connection of IMNNIKEvents to the
NAVIGON Integration Kit.
Header file: NIK32.h
Object library: NIK32.TLB
COM-DLL: NIK32.DLL
Header file: NIKCE.h
Object library: NIKCE.TLB
COM-DLL: NIKCE.DLL
Notice: You may find further information e.g. in the MSDN
(Microsoft Software Developer’s Network).
Using interface
methods
- 14 - Requirements for using NIK with a development environment
Most interfaces have open/close methods which have to be called
before/after calling other methods of the respective interface.
User’s manual NAVIGON Integration Kit 4.0
2.1.2 A survey on the interfaces
Provided interfaces The NAVIGON Integration Kit provides the following
interfaces:
IMNNIK (Default-Interface), see page 15
IADDRESS, see page 19
IROUTING, see page 34
IPOSITION, see page 52
INAVIGATION, see page 59
IOPTIONS, see page 89
IGPS, see page 106
ITMC, see page 114
ILOCATIONMAP, see page 124
ITRACK, see page 137
ISIMULATION, see page 142
2.2 IMNNIK
Survey
Typical use
Methods
IMNNIKEvents, see page 142
The IMMNIK programming interface is used to run and to close
the navigation software.
The Integration Kit must be opened at the start of an
application and be closed at its end. Opening the Integration
Kit when the application is running is not recommended.
Notice: Make sure that the MNOpen() method has completed
before calling another method of this or of another interface
(except GetMNOpen() and GetMNVersion(), see below).
MNOpen();
// other interfaces|methods
MNClose();
The IMNNIK interface defines the following methods:
MNOpen(), see page 16
MNClose() method, see page 16
GetMNOpen() method, see page 17
GetMNVersion() method, see page 17
Programming interfaces - 15 -
2.2.1 MNOpen() method
User’s manual NAVIGON Integration Kit 4.0
Description
The MNOpen() method starts the navigation software as a
background process. It also executes a basic initialisation which
makes NIK ready to use the other interfaces.
C++ syntax
IMNNIK::MNOpen
Type
HRESULT MNOpen()
Return values The method returns one of the following values:
Return value Signification
S_OK
S_FALSE
Done
Error
Notes The navigation software needs a certain time for initialising and
running. Make sure not to call methods of other interfaces before
the initialisation and start process has been completed. Use the
GetMNOpen() method (see page 17) to find out whether it has
been completed or not.
The MNOpen() method identifies other instances of the navigation
software and closes them.
Attention: Do not call another method before MNOpen() has
been completed.
2.2.2 MNClose() method
Description
C++ syntax
Type
Return values The method returns one of the following values:
The MNClose() method closes the navigation software.
IMNNIK::MNClose
HRESULT MNClose()
Return value Signification
S_OK
S_FALSE
Done
Error
- 16 - IMNNIK
2.2.3 GetMNOpen() method
User’s manual NAVIGON Integration Kit 4.0
Description
The GetMNOpen() method returns the status of the current
initialisation and starting process of the navigation software.
C++ syntax
IMNNIK::GetMNOpen
Type
HRESULT GetMNOpen([out] BOOL * a_open )
Parameters The method takes the following parameter:
Parameter Signification
a_open
Pointer to a BOOL variable which contains the
status.
Return values The method returns one of the following values:
Return value Signification
S_OK
The initialisation and starting process has
been completed.
S_FALSE
The initialisation and starting procedures has
not yet been completed or is faulty.
2.2.4 GetMNVersion() method
Description
C++ syntax
Type
Parameters The method takes the following parameters:
The GetMNversion() method retrieves the version number
(major version, minor version, and build) of the navigation
software.
IMNNIK::GetMNVersion
HRESULT GetMNVersion(
[out] int * a_rnMajor,
[out] int * a_rnMinor,
[out] int * a_rnBuild )
Parameter Signification
a_rnMajor
Pointer to an INT variable which contains the
major version number.
a_rnMinor
Pointer to an INT variable which contains the
minor version number.
a_rnBuild
Pointer to an INT variable which contains the
build number.
Programming interfaces - 17 -
User’s manual NAVIGON Integration Kit 4.0
Return values The method returns one of the following values:
Return value Signification
S_OK
S_FALSE
Done
Error
2.2.5 Starting and closing NIK
Example
/* create an instance of the IMNNIK interface */
CoCreateInstance( __uuidof(MNNIK), NULL,
CLSCTX_INPROC_SERVER,__uuidof(IMNNIK),
(void**)&m_NIK );
/* Open NIK */
m_NIK->MNOpen();
/* Wait until NIK has been opened */
while( !bOpen )
m_NIK->GetMNOpen( &bOpen );
/* Close NIK */
m_NIK->MNClose();
- 18 - IMNNIK
2.3 IADDRESS
User’s manual NAVIGON Integration Kit 4.0
Survey
Exposed functionality Access to the address and POI data of the map which is
Typical use
Methods
The IADDRESS programming interface is designed to retrieve
town, street, and POI data from the cartographic data of the map
which is currently loaded. You may as well retrieve geographic
coordinates for routing or navigation purposes.
currently loaded
Query for towns, streets and POI (e.g. all petrol stations in a
specific town)
Retrieval of the geographic coordinates of an address or of a
POI
Retrieval of addresses belonging to given geographic
coordinates
Notice: The format of geographic coordinates is always WGS-84.
OpenAddress();
// More IADDRESS methods
CloseAddress();
The IADDRESS interface defines the following methods:
OpenAddress() method), see page 20
CloseAdress() method, see page 20
SearchFirstCityAddress() method, see page 21
SearchFirstCityPostalCodeAddress() method, see page 22
SearchNextCityAddress() method, see page 23
SearchFirstStreetAddress() method, see page 25
SearchNextStreetAddress() method, see page 27
SearchPoiByRadiusAddress() method, see page 28
SearchNextPoiAddress() method, see page 30
ConvertCoordInAddress() method, see page 31
ConvertCoordInAddress2() method, see page 32
ConvertCoordInCountry() method, see page 33
Programming interfaces - 19 -
2.3.1 OpenAddress() method)
User’s manual NAVIGON Integration Kit 4.0
Description
The OpenAddress() method opens the IADDRESS interface.
C++ syntax
IADDRESS::OpenAddress
Type
HRESULT OpenAddress()
Return values The method returns one of the following values:
Return value Signification
S_OK
S_FALSE
Done
Error
2.3.2 CloseAdress() method
Description
C++ syntax
Type
Return values The method returns one of the following values:
The CloseAddress() method closes the IADDRESS interface. You
will have to open the interface again before calling more of its
methods.
IADDRESS::CloseAddress
HRESULT CloseAddress()
Return value Signification
S_OK
S_FALSE
Done
Error
- 20 - IADDRESS
User’s manual NAVIGON Integration Kit 4.0
2.3.3 SearchFirstCityAddress() method
Description
The SearchFirstCityAddress() method retrieves the first entry
from a list of towns which are in a specified country and have a
given string in or at the beginning of their names. When you are
searching for POI, you may also specify a category.
Use the SearchNextCityAddress() method to retrieve further
entries from the list (see page 23).
C++ syntax
IADDRESS::SearchFirstCityAddress
Type
HRESULT SearchFirstCityAddress(
[in] int a_country,
[in] BSTR prefix,
[out] BSTR * city,
[out] BSTR * plz,
[out] long * a_id,
[out] BOOL * a_find,
[out] double * a_latx,
[out] double * a_longy )
Parameters The method takes the following parameters:
Parameter Signification
a_country
Specifies the country in which towns shall be
looked for. Must be a member of the
_CountryCode enumeration (e.g. cc_DEU for
Germany or cc_FRA for France, see
_CountryCode on page 166)
prefix
The string towns to be found must have in or
at the beginning of their names.
city
Pointer to a BSTR variable which contains the
name of the retrieved town.
plz
Pointer to a BSTR variable which contains the
postcode of the retrieved town.
a_id
Pointer to a LONG variable which contains
the ID of the retrieved town (town ID).
a_find Pointer to a BOOL variable which indicates
whether a town has been found: TRUE when
a town has been retrieved, FALSE when no
town matches both the a_country and the
prefix_postalcode search criteria.
a_latx
Pointer to a DOUBLE variable which contains
the latitude of the retrieved town in WGS-84
format.
a_longy
Pointer to a DOUBLE variable which contains
the longitude of the retrieved town in WGS84 format.
Programming interfaces - 21 -
User’s manual NAVIGON Integration Kit 4.0
Return values The method returns one of the following values:
Return value Signification
S_OK
S_FALSE
Done
Error
Example
m_NIK_Address->OpenAddress();
/* Search for the first town */
m_NIK_Address->SearchFirstCityAddress( DEU, “Frankf“,
&bstrCity, &bstrPlz, &nCityId,
&bFoundMore, &dLatX, &dLongY);
m_NIK_Address->CloseAddress();
2.3.4 SearchFirstCityPostalCodeAddress() method
Description
The SearchFirstCityPostalCodeAddress() method retrieves
the first entry from a list of towns which are in a specified
country and have a given string at the beginning of their
postcodes.
Use the SearchNextCityAddress() method to retrieve further
entries from the list (see page 23).
C++ syntax
IADDRESS::SearchFirstCityPostalCodeAddress
Type
HRESULT SearchFirstCityPostalCodeAddress(
[in] int a_country,
[in] BSTR prefix_postalcode,
[out] BSTR * city,
[out] BSTR * postalcode,
[out] long * a_id,
[out] BOOL * a_find,
[out] double * a_latx,
[out] double * a_longy )
Parameters The method takes the following parameters:
Parameter Signification
a_country
Specifies the country in which towns shall be
looked for. Must be a member of the
_CountryCode enumeration (e.g. cc_DEU for
Germany or cc_FRA for France, see
_CountryCode page 166).
- 22 - IADDRESS
User’s manual NAVIGON Integration Kit 4.0
Parameter Signification
prefix_
postalcode
city
The string towns to be found must have at
the beginning of their postcodes.
Pointer to a BSTR variable which contains the
name of the retrieved town.
postalcode
Pointer to a BSTR variable which contains the
postcode of the retrieved town.
a_id
Pointer to a LONG variable which contains
the ID of the retrieved town (town ID).
a_find
Pointer to a BOOL variable which indicates
whether a town has been found: TRUE when
a town has been retrieved, FALSE when no
town matches both the a_country and the
prefix_postalcode search criteria.
a_latx
Pointer to a DOUBLE variable which contains
the latitude of the retrieved town in WGS-84
format.
a_longy
Pointer to a DOUBLE variable which contains
the longitude of the retrieved town in WGS84 format.
Return values The method returns one of the following values:
Return value Signification
S_OK
S_FALSE
Done
Error
Notes
If the SearchFirstCityPostalCodeAddress() method has
retrieved a town (a_find is TRUE), you may find all further towns
that match the search criteria by calling the
SearchNextCityAddress() method.
2.3.5 SearchNextCityAddress() method
Description
C++ syntax
Type
Programming interfaces - 23 -
The SearchNextCityAddress() method retrieves the next entry
from a search result list which must have been created by calling
the SearchFirstCityAddress() method or the
SearchFirstCityPostalCodeAddress() method.
IADDRESS::SearchNextCityAddress
HRESULT SearchNextCityAddress (
[out] BSTR * city,
[out] BSTR * plz,
[out] long * a_id,
[out] BOOL * a_find,
[out] double * a_latx,
[out] double * a_longy )
User’s manual NAVIGON Integration Kit 4.0
Parameters The method takes the following parameters:
Parameter Signification
city
Pointer to a BSTR variable which contains the
name of the retrieved town.
plz
Pointer to a BSTR variable which contains the
postcode of the retrieved town.
a_id
Pointer to a LONG variable which contains
the ID of the retrieved town (town ID).
a_find Pointer to a BOOL variable which indicates
whether a town has been found: TRUE when
a town has been retrieved, FALSE when the
end of the list has been reached.
a_latx
Pointer to a DOUBLE variable which contains
the latitude of the retrieved town in WGS-84
format.
a_longy
Pointer to a DOUBLE variable which contains
the longitude of the retrieved town in WGS84 format.
Return values The method returns one of the following values:
Return value Signification
S_OK
S_FALSE
Done
Error
Example
m_NIK_Address->OpenAddress();
/* Search for the first town */
m_NIK_Address->SearchFirstCityAddress( DEU, “Frankf“,
&bstrCity, &bstrPlz, &nCityId,
&bFoundMore, &dLatX, &dLongY );
/* Search for all further towns */
while( bFoundMore )
m_NIK_Address->SearchNextCityAddress( &bstrCity,
&bstrPlz, &nCityId, &bFoundMore,
&dLatX, &dLongY );
m_NIK_Address->CloseAddress();
- 24 - IADDRESS
User’s manual NAVIGON Integration Kit 4.0
2.3.6 SearchFirstStreetAddress() method
Description
C++ syntax
Type
The SearchFirstStreetAddress() method retrieves the first
entry from a list of streets or POI which are in a specified town and
have a given string in or at the beginning of their names. When
you are searching for POI, you may also specify a category.
Use the SearchNextStreetAddress() method to retrieve further
entries from the list (see page 27).
IADDRESS:: SearchFirstStreetAddress
HRESULT SearchFirstStreetAddress (
[in] long id_city,
[in] BSTR prefix,
[in] int type_from,
[in] int type_to,
[in] BSTR hn,
[out] BSTR * street,
[out] BSTR * plz,
[out] long * a_id,
[out] BOOL * a_find,
[out] double * a_latx,
[out] double * a_longy )
Parameters The method takes the following parameters:
Parameter Signification
id_city
Specifies the ID of the town in which streets
or POI shall be looked for (town ID).
prefix
The string streets or POI to be found must
have in or at the beginning of their names.
type_from
When you are looking for POI, you may
indicate categories which a retrieved POI
shall be assigned to. type_from specifies the
first category from the enumeration.
Should be enAllTypes when looking for
streets.
type_to
Specifies the first category from the
enumeration which does no more belong to
the specified category list. Example: looking
for petrol stations:
type_from = enPetrolStation
type_to = enRentACar
Should be enAllTypes when looking for
streets.
hn
Specifies a house number to be searched for
when searching for streets.
Programming interfaces - 25 -
User’s manual NAVIGON Integration Kit 4.0
Parameter Signification
street
Pointer to a BSTR variable which contains the
name of the retrieved street.
plz
Pointer to a BSTR variable which contains the
postcode of the retrieved street.
a_id
Pointer to a LONG variable which contains
the ID of the retrieved street (street ID).
a_find
Pointer to a BOOL variable which indicates
whether a street or POI has been found:
TRUE when a street or POI has been
retrieved, FALSE when no street or POI
matches the search criteria.
a_latx
Pointer to a DOUBLE variable which contains
the latitude of the retrieved street or POI in
WGS-84 format.
a_longy
Pointer to a DOUBLE variable which contains
the longitude of the retrieved street or POI in
WGS-84 format.
Return values The method returns one of the following values:
Return value Signification
S_OK
S_FALSE
Done
Error
Example
m_NIK_Address->OpenAddress();
/* search for the first street in nCityId */
m_NIK_Address->SearchFirstStreetAddress( nCityId,
“Bahn“,enAllTypes, enAllTypes, NULL,
&bstrStreet, &bstrPlz, &nStreetId,
&bFoundMore, &dLatX, &dLongY );
m_NIK_Address->CloseAddress();
- 26 - IADDRESS
User’s manual NAVIGON Integration Kit 4.0
2.3.7 SearchNextStreetAddress() method
Description
The SearchNextStreetAddress() method retrieves the next
entry from a search result list which must have been created by
calling the SearchFirstStreetAddress() method.
C++ syntax
IADDRESS::SearchNextStreetAddress
Type
HRESULT SearchNextStreetAddress (
[out] BSTR * street,
[out] BSTR * plz,
[out] long * a_id,
[out] BOOL * a_find,
[out] double * a_latx,
[out] double * a_longy )
Parameters The method takes the following parameters:
Parameter Signification
street
Pointer to a BSTR variable which contains the
name of the retrieved street or the street
name of the retrieved POI.
plz
Pointer to a BSTR variable which contains the
postcode of the retrieved street or POI.
a_id
Pointer to a LONG variable which the ID of
the retrieved street (street ID) or of the
street of a retrieved POI.
a_find
Pointer to a BOOL variable which indicates
whether a street or POI has been found:
TRUE when a street or POI has been
retrieved, FALSE when the end of the list has
been reached.
a_latx
Pointer to a DOUBLE variable which contains
the latitude of the retrieved street or POI in
WGS-84 format.
a_longy
Pointer to a DOUBLE variable which contains
the longitude of the retrieved street or POI in
WGS-84 format.
Return values The method returns one of the following values:
Return value Signification
S_OK
S_FALSE
Done
Error
Programming interfaces - 27 -
User’s manual NAVIGON Integration Kit 4.0
Example: Searching
for streets
Example: Searching
for POI
m_NIK_Address->OpenAddress();
/* search for the first street in nCityId */
m_NIK_Address->SearchFirstStreetAddress( nCityId,
“Bahn“,enAllTypes, enAllTypes, NULL,
&bstrStreet, &bstrPlz, &nStreetId,
&bFoundMore, &dLatX, &dLongY );
/* search for further streets */
while( bFoundMore )
m_NIK_Address->SearchNextStreetAddress( &bstrStreet,
&bstrPlz,&nStreetId,&bFoundMore, &dLatX, &dLongY );
m_NIK_Address->CloseAddress();
m_NIK_Address->OpenAddress();
/* search for the first petrol station in nCityId */
m_NIK_Address->SearchFirstStreetAddress( nCityId, ““,
enPetrolStation, enPetrolStation+1,
NULL,&bstrStreet, &bstrPlz, &nPoiId,
&bFoundMore, &dLatX, &dLongY );
/* search for further petrol stations */
while( bFoundMore )
m_NIK_Address->SearchNextStreetAddress( &bstrStreet,
&bstrPlz,&nPoiId,&bFoundMore, &dLatX, &dLongY );
m_NIK_Address->CloseAddress();
2.3.8 SearchPoiByRadiusAddress() method
Description
C++ syntax
Type
The SearchPoiByRadiusAddress() method retrieves the first
entry from a list of POI which are to be found within a specified
radius round a specified geographic point, which have a given
string in or at the beginning of their names, and which belong to
a given category.
Use the SearchNextPoiAddress() method to retrieve further
entries from the list (see page 30).
IADDRESS::SearchPoiByRadiusAddress
HRESULT SearchPoiByRadiusAddress(
[in] BSTR prefix,
[in] double a_lat,
[in] double a_long,
[in] int a_radius,
[in] int type_from,
[in] int type_to,
[out] BOOL * a_find )
- 28 - IADDRESS
Loading...