Navigation SDK Documentation

Functions

Functions

SDK_ERROR SDK_API SDK_GetNavigationSettings (SDK_NavigationSettings *pNavigationSettings)
 
SDK_ERROR SDK_API SDK_SetNavigationSettings (const SDK_NavigationSettings *pNavigationSettings)
 
SDK_ERROR SDK_API SDK_GetGuidanceInformation (const SDK_GPSData *pGPSData, SDK_NavigationInformation *pNavigationInformation, SDK_INT4 forecast, SDK_ProgressCBFuncT pCallBackFunc)
 
SDK_ERROR SDK_API SDK_TakeOverTrafficReRoute (const SDK_GPSData *pGPSData, SDK_NavigationInformation *pNavigationInformation, SDK_ProgressCBFuncT pCallBackFunc)
 
SDK_ERROR SDK_API SDK_SetManeuverGeneratorSettings (const SDK_ManeuverGeneratorSettings *pManeuverGeneratorSettings)
 
SDK_ERROR SDK_API SDK_GetManeuverGeneratorSettings (SDK_ManeuverGeneratorSettings *pManeuverGeneratorSettings)
 
SDK_ERROR SDK_API SDK_GetManeuverText (const SDK_NavigationInformation *pNavigationInformation, SDK_WCHAR_T *pManeuverText, SDK_StringCBFuncT pStringRetrieverCallBackFunc)
 
SDK_ERROR SDK_API SDK_CheckIfTunnel (const SDK_NavigationInformation *pNavigationInformation, const SDK_GPSData *pGPSData, SDK_BOOL *pIsTunnel)
 
SDK_ERROR SDK_API SDK_GetRouteTrace (SDK_Trace *pTrace)
 
SDK_ERROR SDK_API SDK_GetRouteTraceAhead (SDK_Trace *pTrace, SDK_BOOL onlyToNextStation)
 
SDK_ERROR SDK_API SDK_FreeRouteTrace (SDK_Trace *pTrace)
 
SDK_ERROR SDK_API SDK_GetRouteTraces (SDK_TraceExt **ppTraces, SDK_INT4 *pNumberOfRouteTraces)
 
SDK_ERROR SDK_API SDK_FreeRouteTraces (SDK_TraceExt *pTraces, SDK_INT4 NumberOfRouteTraces)
 
SDK_ERROR SDK_API SDK_SkipCurrentTarget ()
 
SDK_ERROR SDK_API SDK_TrackingMode (SDK_BOOL bEnable, SDK_INT4 i, SDK_INT4 j)
 

Detailed Description

Functions for Navigation.

Function Documentation

SDK_ERROR SDK_API SDK_GetNavigationSettings ( SDK_NavigationSettings pNavigationSettings)

Retrieve the navigation settings.

Parameters
[out]pNavigationSettingsThe structure will be filled with the current settings.
Returns
Error code (Errorcodes)
SDK_ERROR SDK_API SDK_SetNavigationSettings ( const SDK_NavigationSettings pNavigationSettings)

Set the navigation settings.

Note that some changes don't have effect unless a navigation is initiated by calling SDK_CalculateTour(), SDK_LoadRoute() or SDK_CalculateViaRoute().

Parameters
[in]pNavigationSettingsNew settings. One may use SDK_GetNavigationSettings() before calling SDK_SetNavigationSettings() to retrieve the default values.
Returns
Error code (Errorcodes)
SDK_ERROR SDK_API SDK_GetGuidanceInformation ( const SDK_GPSData pGPSData,
SDK_NavigationInformation pNavigationInformation,
SDK_INT4  forecast,
SDK_ProgressCBFuncT  pCallBackFunc 
)

Retrieve guidance information for a position on the current routing.

Guidance information is necessary to interpret actual routing data. Note that this call may change the currently open map within the Navigation SDK!

Due to the nature of "navigation" this call may take a while to return. Especially in the case of cross-border routing it may be more than one minute on certain devices if a reroute calculation has to be performed internally. So be prepared for this, e.g. by using the callback or application intrinsic methods. Don't forget that the SDK is not re-entrant, during this call there is no map rendering, etc. available!

Parameters
[in]pGPSDataobject with actual GPS information. This argument must not be NULL! (as it was allowed in previous versions of the Navigation SDK)
[out]pNavigationInformationPointer to user supplied object that contains all relevant information of the actual routing. Filling either the GPSPosition or the GPSPositionMerc member is sufficient.
[in]forecastNot yet implemented
[in]pCallBackFuncOptional pointer to a callback method. Returns the actual status of the routing process.
Returns
Error code (Errorcodes). Usually it should return SDK_ERROR_Ok. In case the API gets called more than once with the same content for the pGPSData parameter SDK_ERROR_SamePosition will be returned. Note that reaching the destination will be only indicated once. Further calls will just give SDK_ERROR_NoRouteFound or SDK_ERROR_NoDestination.
SDK_ERROR SDK_API SDK_SetManeuverGeneratorSettings ( const SDK_ManeuverGeneratorSettings pManeuverGeneratorSettings)

Set the maneuver generator settings The maneuver generator has serveral options which can be set by this function. The options are:

  • set if streetnames should be included in the assembled text (only if output type is set to SDK_spTTS)
  • set if signposts should be included in the assembled text (only if output type is set to SDK_spTTS)
  • set the decimal separator for numbers in the text ((only if output type is set to SDK_spTTS)
  • set the output type of the generator. See Maneuver generator output types output types for details. The generator can output a normal string with the navigation commands as clear text (SDK_spTTS for TTS use) or it can output a string with all filenames in the correct order if type is set to SDK_spSAMPLES.
    Parameters
    [in]pManeuverGeneratorSettingssettings to set.
    Returns
    Error code (Errorcodes).
SDK_ERROR SDK_API SDK_GetManeuverGeneratorSettings ( SDK_ManeuverGeneratorSettings pManeuverGeneratorSettings)

Get the maneuver generator settings The maneuver generator has serveral options which can be get by this function.

Parameters
[in,out]pManeuverGeneratorSettingssettings to retrive.
Returns
Error code (Errorcodes).
SDK_ERROR SDK_API SDK_GetManeuverText ( const SDK_NavigationInformation pNavigationInformation,
SDK_WCHAR_T pManeuverText,
SDK_StringCBFuncT  pStringRetrieverCallBackFunc 
)

Get the maneuver text This function builds and returns a string that can be used for navigation announcements. The navigation information given will be interpreted, decoded and a corresponding sentence will be built up. The generator only returns a text if the current maneuver situation should be spoken, multiple same outputs will be avoided. If the returned string is not empty, the announcement is valid and should be spoken or outputted by a player. The grammar and the localization of the strings is not done in the generator itself. The generator uses the callback function to retrieve the correct grammar and sentence portions from outside the SDK. This callback, which has to be implemented by the caller, must return the correct sentence for the given id. The callback itself is declared in SDKDef.h as "typedef const SDK_WCHAR_T * (SDK_API * SDK_StringCBFuncT)(SDK_INT4 id)". It will be called by the SDK with the ID for the needed string when building the annoncement text. The implementation of the callback must then return the correct sentences for the used language. This has the great advantage that no localization is needed in the generator, the grammar and sentences will all be declared in a separate place and the callee will return the correct portions of the sentence by the callback. The string IDs used for the sentences and the grammar can be found in SDKDef.h. There is also an example in NaviTest2 which shows the usage of this functionality and a header file with the needed String <-> ID mappings for english and german. We also have the mappings for several other languages, both for TTS and sound output.

There are two output types of the text:

  • SDK_spTTS: Readable output of the announcement for direct output via TTS. An Example output would be "In 150m turn right onto Park Avenue". For this type, you can set if streetnames and signposts should be announced. You can also determine the decimal sign for numbers in the output.
  • SDK_spSAMPLES: When the announcement output should be based on soundfiles, the returned string will represent the announcement by a series of filesnames needed to be played for the announcement (in this case no segnposts and streetnames will be spoken).
Parameters
[in]pNavigationInformationnavigation information from which the announcement text will be generated.
[out]pManeuverTextthe generated maneuver text in the previous set format. The buffer must be allocated by the user and should have a minimum size of 1024 chars. The function copies the resulting text into this buffer.
[in]pStringRetrieverCallBackFunca callback function to retrieve the correct localized sentences for the generator.
Returns
Error code (Errorcodes).
SDK_ERROR SDK_API SDK_CheckIfTunnel ( const SDK_NavigationInformation pNavigationInformation,
const SDK_GPSData pGPSData,
SDK_BOOL pIsTunnel 
)

Check if position in a tunnel.

Wether the given position is in a tunnel or not, the gps position extrapolator will be started or deactivated.

Parameters
[in]Pointer
[in]object with actual GPS information.
[out]Position is in Tunnel. Position was checked by positionvalidator.
Returns
Error code (Errorcodes).
SDK_ERROR SDK_API SDK_GetRouteTrace ( SDK_Trace pTrace)

Retrieve route trace.

Deprecated:
Please use SDK_GetRouteTraces()/SDK_FreeRouteTraces() instead! That call must be matched with suitable calls to SDK_FreeRouteTrace() to avoid memory leaks.
\param[out] pTrace Pointer to trace structure to be filled with trace for the current route.
If there's no current route an error code is returned.
\return Error code (\ref Errorcodes)  
SDK_ERROR SDK_API SDK_GetRouteTraceAhead ( SDK_Trace pTrace,
SDK_BOOL  onlyToNextStation 
)

Retrieve remaining trace ahead of Route or complete tour.

That call must be matched with suitable calls to SDK_FreeRouteTrace() to avoid memory leaks.

Parameters
[out]pTracePointer to trace structure to be filled with trace.
[in]onlyToNextStationif true, trace ends at next station, else complete tourtrace will be generated. If there's no current route an error code is returned.
Returns
Error code (Errorcodes)
SDK_ERROR SDK_API SDK_FreeRouteTrace ( SDK_Trace pTrace)

Free route trace.

Free a route trace that was retrieved by SDK_GetRouteTraceAhead().

Parameters
[in]pTracePointer to route trace structure which had been previously set by SDK_GetRouteTrace()
Returns
Error code (Errorcodes)
SDK_ERROR SDK_API SDK_GetRouteTraces ( SDK_TraceExt **  ppTraces,
SDK_INT4 pNumberOfRouteTraces 
)

Retrieve route traces.

If a tour was calculated, the traces between the different stations will be returned. If the calculation was a normal A-B routing, one trace will be returned. That call must be matched with suitable calls to SDK_FreeRouteTraces() to avoid memory leaks.

Parameters
[out]ppTracesPointer to array of trace structures to be filled with trace for the current route.
[out]pNumberOfRouteTraceswill be set to the number of route traces
Returns
Error code (Errorcodes)
SDK_ERROR SDK_API SDK_FreeRouteTraces ( SDK_TraceExt pTraces,
SDK_INT4  NumberOfRouteTraces 
)

Free route trace.

Parameters
[in]pTracesPointer to route traces retrieved by SDK_GetRouteTraces()
[in]NumberOfRouteTracesNumber of route traces supplied in pTraces pointer
Returns
Error code (Errorcodes)
SDK_ERROR SDK_API SDK_SkipCurrentTarget ( )

Skip the current target.

Sometimes the current target (stop over point) can not be reached or the client decides to go already to the next stop over point. Then one may skip that and launch the navigation to the next.

Returns
Standard error code. SDK_ERROR_Ok if everything is ok and there is still another navigation, SDK_ERROR_NoDestination if there is no further target for a navigation.
SDK_ERROR SDK_API SDK_TrackingMode ( SDK_BOOL  bEnable,
SDK_INT4  i,
SDK_INT4  j 
)

Start tracking mode.

The tracking mode should be used if there is no need for navigation any longer. Any internal data about navigation will be cleared. Calls to SDK_SetMapViewParameter() to adjust the map position result in setting the most suitable map, so there's always the best map available!. Since switching maps may not be always the intent of the user this mode can be switched off. There is no need to stop this mode prior to calculating a new route and starting navigation afterwards.

Parameters
[in]bEnableIf set to SDK_TRUE activate the map tracking mode, otherwise deactivate
[in]ireserved for future applications. Use 0 for now.
[in]jreserved for future applications. Use 0 for now.
Returns
Error code (Errorcodes)

© PTV Group 2018 Generated on Mon Dec 17 2018 21:00:19 for NavigationSDK by doxygen 1.8.8