User manual NAVIGON INTEGRATION KIT 4.0

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. User's manual NAVIGON Integration Kit 4.0 Table of contents 1 Introduction................................................................6 1.1 1.2 1.3 1.4 On this manual................................................................. 7 Specification of services .................................................... 7 1.2.1 Supported operating systems .................................. 8 System requirements ........................................................ 9 Installation ...................................................................... 9 1.4.1 Installation of the Windows 2000/XP version ............10 1.4.2 Installation of the Windows CE version ....................10 Search facilities and conventions .......................................11 Liability ..........................................................................11 1.6.1 Support ...............................................................12 Trademarks ....................................................................12 1.5 1.6 1.7 2 Programming interfaces............................................ 13 2.1 Requirements for using NIK with a development environment 14 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 2.2 2.3 2.4 Table of contents -I- User's manual NAVIGON Integration Kit 4.0 2.4.11 2.4.12 2.4.13 2.4.14 2.4.15 2.4.16 2.4.17 2.4.18 2.4.19 2.4.20 2.4.21 2.4.22 2.4.23 2.4.24 2.4.25 2.4.26 2.4.27 2.4.28 2.4.29 2.4.30 2.5 ShowDownRoute() method...................................40 ShowUpRoute() method .......................................41 ShowLeftRoute() method .....................................41 ShowRightRoute() method ...................................41 ShowStartPointRoute() method.............................42 ShowEndPointRoute() method ..............................42 SetRotationRoute() method ..................................43 GetRotationRoute() method..................................43 GetStatusRoute() method ....................................44 GetResultRoute() method.....................................44 MapShowRoute() method .....................................45 GetFirstWayListRoute() method ............................45 GetNextWayListRoute() method ............................46 SetZoomLevelInRoute() method ...........................47 GetZoomLevelInRoute() method ...........................48 SetMaxResolutionRoute() method .........................48 GetMaxResolutionRoute() method .........................49 ChangeGeoToMapCoordRoute() method .................49 ChangeMapToGeoCoordRoute() method .................50 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 2.6 - II - Table of contents User's manual NAVIGON Integration Kit 4.0 2.6.16 2.6.17 2.6.18 2.6.19 2.6.20 2.6.21 2.6.22 2.6.23 2.6.24 2.6.25 2.6.26 2.6.27 2.6.28 2.6.29 2.6.30 2.6.31 2.6.32 2.6.33 2.6.34 2.6.35 2.6.36 2.6.37 2.7 ShowRightNavigation() method.............................74 ShowStartPointNavigation() method ......................74 ShowEndPointNavigation() method........................74 SetRotationNavigation() method ...........................75 GetRotationNavigation() method ...........................75 GetStatusNavigation() method..............................76 GetRoutingResultNavigation() method ...................76 ShematicViewOpenNavigation() method.................77 ShematicViewShowNavigation() method ................78 DistanceBarOpenNavigation() method ...................79 DistanceBarShowNavigation() method ...................80 MapShowNavigation() method ..............................80 SetBirdViewNavigation() method...........................81 GetFirstWayListNavigation() method......................81 GetNextWayListNavigation() method .....................82 SetZoomLevelInNavigation() method.....................83 GetZoomLevelInNavigation() method ....................84 SetMaxResolutionNavigation() method...................84 GetMaxResolutionNavigation() method ..................85 ChangeGeoToMapCoordNavigation() method ..........85 ChangeMapToGeoCoordLocationMap() method........86 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 2.8 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 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 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 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 IMNNIKEvents...............................................................148 2.10 2.11 2.12 2.13 - IV - Table of contents User's manual NAVIGON Integration Kit 4.0 2.13.1 2.13.2 2.13.3 2.13.4 2.13.5 2.13.6 2.13.7 2.13.8 2.13.9 2.13.10 2.13.11 2.13.12 2.13.13 2.13.14 2.13.15 2.13.16 2.13.17 2.13.18 2.13.19 2.13.20 2.13.21 2.13.22 2.13.23 Declaring an event class ....................................149 Implementation in your application .....................149 RTProgressCallback() method .............................150 TMCMessageActivateCallback() method ...............150 TMCMessageDeactivateCallback() method ............151 GPSMessageCallback() method ...........................152 NAVAudioAdviceCallback() method ......................152 NAVVisualAdviceCallback() method .....................153 LButtonDownNavigationMapCallback() method .....154 MouseMoveNavigationMapCallback() method ......154 LButtonDownRouteMapCallback() method ..........155 MouseMoveRouteMapCallback() method .............156 LButtonDownPositionMapCallback() method........156 MouseMovePositionMapCallback() method ..........157 LButtonDownLocationMapCallback() method .......158 MouseMoveLocationMapCallback() method .........158 MAPKeyBoardCallback() method........................159 NAVOnDrawingCallback() method......................160 RoutingOnDrawingCallback() method.................161 PositionOnDrawingCallback() method.................162 LocationOnDrawingCallback() method ................163 NAVOnRunningCallback() method......................164 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 page 7 page 7 Topics covered in this chapter: 1.1 On this manual 1.2 Specification of services Supported operating systems 1.3 System requirements 1.4 Installation Installation of the Windows 2000/XP version Installation of the Windows CE version 1.5 Search facilities and conventions 1.6 Liability Support 1.7 Trademarks page 12 page 11 page 11 page 9 page 9 -6- On this manual User's manual NAVIGON Integration Kit 4.0 1.1 On this manual 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. Introduction 1.2 Specification of services 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. General survey on NIK COM-DLL NIK is a COM-DLL providing several interfaces which may be 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. Features NIK supports all features that are typical for navigation. 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 IMNNIK IADDRESS IROUTING IPOSITION INAVIGATION IOPTIONS IGPS ITMC ILOCATIONMAP ITRACK ISIMULATION IMNNIKEvents Description Running and closing the navigation software. Connecting to the database of places. Route planning and calculation. Displaying the current position on the map. Navigation to any destination. Determining global parameters. Getting current GPS data. Including TMC data. Displaying customised maps. Recording tracks. Using GPS / TMC simulation files. Event handling. 1.2.1 Supported 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 Notebook and PC Notebook and PC Pocket PC Operating system Windows 2000 Windows XP Windows 2000 Windows XP Windows Mobile 2003 Programming language C++ Visual Basic C++ Development environment Microsoft Visual Studio 6.0 Microsoft Visual Basic 6.0 Microsoft eMbedded Visual C++ 4.0 Operating systems 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 PC System requirements 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 Survey Installation 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... install only the NIK runtime environment, install the development environment with all files, and the demo application, then... 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 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: NIK-SDK user's manual Interface files (Header, TLB, LIB und DLL) Source code of the demo application Demo application Windows 2000/XP, all modes Windows 2000/XP, developer's mode 1.4.2 Installation of the Windows CE version 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: NIK-SDK user's manual Interface files (Header, TLB, LIB und DLL) Code for the demo application Demo application Map of Europe MapExport software Windows CE, all modes Windows CE, developer's mode - 10 - Installation User's manual NAVIGON Integration Kit 4.0 1.5 Search facilities and conventions This manual offers the following search facilities: 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. Find information quickly Conventions The conventions on the fonts and symbols used in this manual are explained in the two following tables: Font bold Signification Buttons, icons, names of entry fields, and elements of the software's user interface. Also used for highlighting warnings and notices. Registered names and trademarks. Window and dialogue box titles. File names and source code. Signification 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. bold italic SMALL CAPITALS Source code Symbol 1.6 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. Limitation of liability Introduction - 11 - User's manual NAVIGON Integration Kit 4.0 1.6.1 Support 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. You need help? 1.7 Trademarks 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. Outlook, Windows, Access, Excel, SQL Server, Visual Studio, Visual Basic, eMbedded Visual C++, and ActiveSync are registered trademarks of the Microsoft Corporation. Registered trademarks - 12 - Trademarks User's manual NAVIGON Integration Kit 4.0 2 Programming interfaces page 14 page 15 page 19 page 34 page 52 page 64 page 89 page 106 page 114 page 124 page 137 page 142 page 148 Topics covered in this chapter: 2.1 Requirements for using NIK with a development environment 2.2 IMNNIK 2.3 IADDRESS 2.4 IROUTING 2.5 IPOSITION 2.6 INAVIGATION 2.7 IOPTIONS 2.8 IGPS 2.9 ITMC 2.10 ILOCATIONMAP 2.11 ITRACK 2.12 ISIMULATION 2.13 IMNNIKEvents Programming interfaces - 13 - User's manual NAVIGON Integration Kit 4.0 2.1 Requirements for using NIK with a development environment 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 MS Windows 2000 MS Windows XP Files Header file: Object library: COM-DLL: Windows Mobile 2003 Header file: Object library: COM-DLL: NIK32.h NIK32.TLB NIK32.DLL NIKCE.h NIKCE.TLB NIKCE.DLL Survey 2.1.1 Using the interfaces 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 Interface instantiation Releasing an interface instance Release releases instances of interfaces AtlUnadvise closes the connection of IMNNIKEvents to the NAVIGON Integration Kit. Notice: You may find further information e.g. in the MSDN (Microsoft Software Developer's Network). Using interface methods Most interfaces have open/close methods which have to be called before/after calling other methods of the respective interface. - 14 - Requirements for using NIK with a development environment User's manual NAVIGON Integration Kit 4.0 2.1.2 A survey on the 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 IMNNIKEvents, see page 142 Provided interfaces 2.2 Survey IMNNIK 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). Typical use MNOpen(); // other interfaces|methods MNClose(); Methods 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 - User's manual NAVIGON Integration Kit 4.0 2.2.1 MNOpen() method 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. IMNNIK::MNOpen HRESULT MNOpen() The method returns one of the following values: Return value S_OK S_FALSE Signification Done Error Description C++ syntax Type Return values 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 The MNClose() method closes the navigation software. IMNNIK::MNClose HRESULT MNClose() The method returns one of the following values: Return value S_OK S_FALSE Signification Done Error Description C++ syntax Type Return values - 16 - IMNNIK User's manual NAVIGON Integration Kit 4.0 2.2.3 GetMNOpen() method The GetMNOpen() method returns the status of the current initialisation and starting process of the navigation software. IMNNIK::GetMNOpen HRESULT GetMNOpen([out] BOOL * a_open ) Description C++ syntax Type Parameters The method takes the following parameter: Parameter a_open Signification Pointer to a BOOL variable which contains the status. Return values The method returns one of the following values: Return value S_OK S_FALSE Signification The initialisation and starting process has been completed. The initialisation and starting procedures has not yet been completed or is faulty. 2.2.4 GetMNVersion() method The GetMNversion() method retrieves the version number (major version, minor version, and build) of the navigation software. IMNNIK::GetMNVersion HRESULT GetMNVersion( [out] int * [out] int * [out] int * a_rnMajor, a_rnMinor, a_rnBuild ) Description C++ syntax Type Parameters The method takes the following parameters: Parameter a_rnMajor a_rnMinor a_rnBuild Signification Pointer to an INT variable which contains the major version number. Pointer to an INT variable which contains the minor version number. 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 S_OK S_FALSE Signification Done Error 2.2.5 Example Starting and closing NIK /* 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 User's manual NAVIGON Integration Kit 4.0 2.3 Survey IADDRESS 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. Access to the address and POI data of the map which is 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. Exposed functionality Typical use OpenAddress(); // More IADDRESS methods CloseAddress(); Methods 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 - User's manual NAVIGON Integration Kit 4.0 2.3.1 OpenAddress() method) The OpenAddress() method opens the IADDRESS interface. IADDRESS::OpenAddress HRESULT OpenAddress() The method returns one of the following values: Return value S_OK S_FALSE Signification Done Error Description C++ syntax Type Return values 2.3.2 CloseAdress() method 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() The method returns one of the following values: Return value S_OK S_FALSE Signification Done Error Description C++ syntax Type Return values - 20 - IADDRESS User's manual NAVIGON Integration Kit 4.0 2.3.3 SearchFirstCityAddress() method 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). Description C++ syntax Type IADDRESS::SearchFirstCityAddress HRESULT SearchFirstCityAddress( [in] int [in] BSTR a_country, prefix, city, plz, a_id, a_find, a_latx, a_longy ) [out] BSTR * [out] BSTR * [out] long * [out] BOOL * [out] double * [out] double * Parameters The method takes the following parameters: Parameter a_country Signification 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) The string towns to be found must have in or at the beginning of their names. Pointer to a BSTR variable which contains the name of the retrieved town. Pointer to a BSTR variable which contains the postcode of the retrieved town. Pointer to a LONG variable which contains the ID of the retrieved town (town ID). 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. Pointer to a DOUBLE variable which contains the latitude of the retrieved town in WGS-84 format. Pointer to a DOUBLE variable which contains the longitude of the retrieved town in WGS84 format. prefix city plz a_id a_find a_latx a_longy Programming interfaces - 21 - User's manual NAVIGON Integration Kit 4.0 Return values The method returns one of the following values: Return value S_OK S_FALSE Signification 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 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). Description C++ syntax Type IADDRESS::SearchFirstCityPostalCodeAddress HRESULT SearchFirstCityPostalCodeAddress( [in] [in] int a_country, BSTR prefix_postalcode, city, postalcode, a_id, a_find, a_latx, a_longy ) [out] BSTR * [out] BSTR * [out] long * [out] BOOL * [out] double * [out] double * Parameters The method takes the following parameters: Parameter a_country Signification 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 prefix_ postalcode city postalcode a_id a_find Signification 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. Pointer to a BSTR variable which contains the postcode of the retrieved town. Pointer to a LONG variable which contains the ID of the retrieved town (town ID). 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. Pointer to a DOUBLE variable which contains the latitude of the retrieved town in WGS-84 format. Pointer to a DOUBLE variable which contains the longitude of the retrieved town in WGS84 format. a_latx a_longy Return values The method returns one of the following values: Return value S_OK S_FALSE Signification 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 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 * [out] BSTR * [out] long * [out] BOOL * [out] double * [out] double * city, plz, a_id, a_find, a_latx, a_longy ) ( Description C++ syntax Type Programming interfaces - 23 - User's manual NAVIGON Integration Kit 4.0 Parameters The method takes the following parameters: Parameter city plz a_id a_find Signification Pointer to a BSTR variable which contains the name of the retrieved town. Pointer to a BSTR variable which contains the postcode of the retrieved town. Pointer to a LONG variable which contains the ID of the retrieved town (town ID). 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. Pointer to a DOUBLE variable which contains the latitude of the retrieved town in WGS-84 format. Pointer to a DOUBLE variable which contains the longitude of the retrieved town in WGS84 format. a_latx a_longy Return values The method returns one of the following values: Return value S_OK S_FALSE Signification 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 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). Description C++ syntax Type IADDRESS:: SearchFirstStreetAddress HRESULT SearchFirstStreetAddress [in] long [in] BSTR [in] int [in] int [in] BSTR id_city, prefix, type_from, type_to, hn, street, plz, a_id, a_find, a_latx, a_longy ) ( [out] BSTR * [out] BSTR * [out] long * [out] BOOL * [out] double * [out] double * Parameters The method takes the following parameters: Parameter id_city prefix type_from Signification Specifies the ID of the town in which streets or POI shall be looked for (town ID). The string streets or POI to be found must have in or at the beginning of their names. 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. 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. type_to Programming interfaces - 25 - User's manual NAVIGON Integration Kit 4.0 Parameter street plz a_id a_find Signification Pointer to a BSTR variable which contains the name of the retrieved street. Pointer to a BSTR variable which contains the postcode of the retrieved street. Pointer to a LONG variable which contains the ID of the retrieved street (street ID). 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. Pointer to a DOUBLE variable which contains the latitude of the retrieved street or POI in WGS-84 format. Pointer to a DOUBLE variable which contains the longitude of the retrieved street or POI in WGS-84 format. a_latx a_longy Return values The method returns one of the following values: Return value S_OK S_FALSE Signification 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 The SearchNextStreetAddress() method retrieves the next entry from a search result list which must have been created by calling the SearchFirstStreetAddress() method. IADDRESS::SearchNextStreetAddress HRESULT SearchNextStreetAddress [out] BSTR * [out] BSTR * [out] long * [out] BOOL * [out] double * [out] double * street, plz, a_id, a_find, a_latx, a_longy ) ( Description C++ syntax Type Parameters The method takes the following parameters: Parameter street Signification Pointer to a BSTR variable which contains the name of the retrieved street or the street name of the retrieved POI. Pointer to a BSTR variable which contains the postcode of the retrieved street or POI. Pointer to a LONG variable which the ID of the retrieved street (street ID) or of the street of a retrieved POI. 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. Pointer to a DOUBLE variable which contains the latitude of the retrieved street or POI in WGS-84 format. Pointer to a DOUBLE variable which contains the longitude of the retrieved street or POI in WGS-84 format. plz a_id a_find a_latx a_longy Return values The method returns one of the following values: Return value S_OK S_FALSE Signification Done Error Programming interfaces - 27 - User's manual NAVIGON Integration Kit 4.0 Example: Searching for streets 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(); Example: Searching for POI 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 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). Description C++ syntax Type IADDRESS::SearchPoiByRadiusAddress HRESULT SearchPoiByRadiusAddress( [in] [in] [in] [in] [in] [in] BSTR double double int int int prefix, a_lat, a_long, a_radius, type_from, type_to, a_find ) [out] BOOL * - 28 - IADDRESS User's manual NAVIGON Integration Kit 4.0 Parameters The method takes the following parameters: Parameter prefix a_lat a_long a_radius Signification The string that POI to be found must have in or at the beginning of their names. Specifies the latitude of a geographical point in WGS-84 format. Specifies the longitude of a geographical point in WGS-84 format. Specifies the radius (in meters) round the geographical point in which POI are to be found. Specifies the first category from an enumeration which a retrieved POI has to be assigned 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 = enPetrolStation+1 Pointer to a BOOL variable which indicates whether a street or POI has been found within the specified circle: TRUE when a POI has been retrieved, FALSE when no POI matches the search criteria. type_from type_to a_find Return values The method returns one of the following values: Return value S_OK S_FALSE Signification Done Error Programming interfaces - 29 - User's manual NAVIGON Integration Kit 4.0 2.3.9 SearchNextPoiAddress() method The SearchNextPoiAddress() method retrieves the next entry from a search result list which must have been created by calling the SearchPoiByRadiusAddress() method. IADDRESS::SearchNextPoiAddress HRESULT SearchNextPoiAddress ( [out] BSTR * [out] BSTR * [out] BSTR * [out] long * [out] BOOL * [out] double * [out] double * poi_name, postalcode, city_name, a_id, a_find, a_latx, a_longy ) Description C++ syntax Type Parameters The method takes the following parameters: Parameter poi_name postalcode city_name a_id a_find Signification Pointer to a BSTR variable which contains the name of the retrieved POI. Pointer to a BSTR variable which contains the postcode of the retrieved POI. Pointer to a BSTR variable which contains the city of the retrieved POI. Pointer to a LONG variable which contains the ID of the retrieved POI (POI ID). Pointer to a BOOL variable which indicates whether a POI has been found: TRUE when a POI has been retrieved, FALSE when the end of the list has been reached. Pointer to a DOUBLE variable which contains the latitude of the retrieved POI in WGS-84 format. Pointer to a DOUBLE variable which contains the longitude of the retrieved POI in WGS-84 format. a_latx a_longy Return values The method returns one of the following values: Return value S_OK S_FALSE Signification Done Error Notes Further POI may be retrieved as long as the a_find variable is TRUE. - 30 - IADDRESS User's manual NAVIGON Integration Kit 4.0 2.3.10 ConvertCoordInAddress() method Attention: Old method! This method has been kept for compatibility reasons. Use the ConvertCoordInAddress2() for new projects as it returns, in addition to the parameters returned by this method, the country code and the house number (if retrievable). Description The ConvertCoordInAddress() method converts the given coordinates of a geographic point into a postal address. IADDRESS::ConvertCoordInAddress HRESULT ConvertCoordInAddress ( [in] [in] double double a_latx, a_longy, city, street, plz, a_find ) C++ syntax Type [out] BSTR * [out] BSTR * [out] BSTR * [out] BOOL * Parameters The method takes the following parameters: Parameter a_latx a_longy city street plz a_find Signification The latitude of a geographic point in WGS-84 format. The longitude of a geographic point in WGS-84 format. Pointer to a BSTR variable which contains the name of the town of the geographic point. Pointer to a BSTR variable which contains the name of the street of the geographic point. Pointer to a BSTR variable which contains the postcode of the geographic point. Pointer to a BOOL variable which indicates whether the conversion was successful: TRUE when an address has been retrieved, FALSE if not. Return values The method returns one of the following values: Return value S_OK S_FALSE Signification Done Error Example m_NIK_Address->OpenAddress(); /* Conversion of a geographical pt into an Address */ m_NIK_Address->ConvertCoordInAddress( dLatX, dLongY, &bstrCity, &bstrStreet, &bstrPlz,&bFound ); m_NIK_Address->CloseAddress(); Programming interfaces - 31 - User's manual NAVIGON Integration Kit 4.0 2.3.11 ConvertCoordInAddress2() method Description The ConvertCoordInAddress2() method converts the given coordinates of a geographic point into a postal address. IADDRESS::ConvertCoordInAddress2 HRESULT ConvertCoordInAddress2 [in] double [in] double [out] int * [out] BSTR * [out] BSTR * [out] BSTR * [out] BSTR * [out] BOOL * Parameters a_latx, a_longy, a_country, city, street, plz, hn, a_find ) ( C++ syntax Type The method takes the following parameters: Parameter a_latx a_longy a_country Signification The latitude of a geographic point in WGS-84 format. The longitude of a geographic point in WGS-84 format. Pointer to an INT variable which contains the country code of the geographic point. Is a member of the _CountryCode enumeration (e.g. cc_DEU for Germany or cc_FRA for France, see _CountryCode page 166). Pointer to a BSTR variable which contains the name of the town of the geographic point. Pointer to a BSTR variable which contains the name of the street of the geographic point. Pointer to a BSTR variable which contains the postcode of the geographic point. Pointer to a BSTR variable which contains the postcode of the geographic point (if retrievable). Pointer to a BOOL variable which indicates whether the conversion was successful: TRUE when an address has been retrieved, FALSE if not. city street plz hn a_find Return values The method returns one of the following values: Return value S_OK S_FALSE Signification Done Error - 32 - IADDRESS User's manual NAVIGON Integration Kit 4.0 2.3.12 ConvertCoordInCountry() method Description The ConvertCoordInCountry() method retrieves the country code of the country a specified geographic point belongs to. IADDRESS::ConvertCoordInCountry HRESULT ConvertCoordInCountry ( [in] [in] double double a_latx, a_longy, a_country, a_find ) C++ syntax Type [out] int * [out] BOOL * Parameters The method takes the following parameters: Parameter a_latx a_longy a_country Signification The latitude of a geographic point in WGS-84 format. The longitude of a geographic point in WGS-84 format. Pointer to an INT variable which contains the country code of the geographic point. Is a member of the _CountryCode enumeration (e.g. cc_DEU for Germany or cc_FRA for France, see _CountryCode page 166). Pointer to a BOOL variable which indicates whether a country has been identified: TRUE when a country has been retrieved, FALSE if not. a_find Return values The method returns one of the following values: Return value S_OK S_FALSE Signification Done Error Programming interfaces