Guidance 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_GetTourRouteTraces (SDK_TraceExt **ppTraces, SDK_INT4 *pNumberOfRouteTraces)
SDK_ERROR SDK_API	SDK_FreeRouteTraces (SDK_TraceExt *pTraces, SDK_INT4 NumberOfRouteTraces)
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]

pNavigationSettings

The 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]

pNavigationSettings

New 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]	pGPSData	object with actual GPS information. This argument must not be NULL! (as it was allowed in previous versions of the Navigation SDK)
[out]	pNavigationInformation	Pointer to user supplied object that contains all relevant information of the actual routing. Filling either the GPSPosition or the GPSPositionMerc member is sufficient.
[in]	forecast	Not yet implemented
[in]	pCallBackFunc	Optional 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]

  pManeuverGeneratorSettings

  settings 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]

pManeuverGeneratorSettings

settings 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]	pNavigationInformation	navigation information from which the announcement text will be generated.
[out]	pManeuverText	the 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]	pStringRetrieverCallBackFunc	a 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]	pTrace	Pointer to trace structure to be filled with trace.
[in]	onlyToNextStation	if 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]

pTrace

Pointer 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 detailed route information of the first route trace part.

The trace of an A-B routing or the trace to the first station of a tour holds beside the trace points also information about different guidance kinds for this trace, like onroad and offroad parts. These trace parts will be returned as separate traces. You only need to call this function, if you want to get more detailed information about the first part of a trace. If you just need the trace itself, or all traces between the stations of a tour, use SDK_GetTourRouteTraces() instead.

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

Parameters

[out]	ppTraces	Pointer to array of trace structures to be filled with the trace for the current route.
[out]	pNumberOfRouteTraces	will be set to the number of route traces

Returns

Error code (Errorcodes)

SDK_ERROR SDK_API SDK_GetTourRouteTraces	(	SDK_TraceExt **	ppTraces,
		SDK_INT4 *	pNumberOfRouteTraces
	)

Retrieve the route traces of a whole tour.

If a tour was calculated, all traces between the different stations will be returned. If the calculation was a normal A-B routing, one trace will be returned. Attention: The GuidanceKind field of the SDK_TraceExt structure will always be set to SDK_gkSTANDARD. If you want more detailed information about the guidance kinds of the first trace of the tour/route, use SDK_GetRouteTraces() instead.

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

Parameters

[out]	ppTraces	Pointer to array of trace structures to be filled with trace for the current route.
[out]	pNumberOfRouteTraces	will 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]	pTraces	Pointer to route traces retrieved by SDK_GetRouteTraces()
[in]	NumberOfRouteTraces	Number of route traces supplied in pTraces pointer

Returns

Error code (Errorcodes)

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]	bEnable	If set to SDK_TRUE activate the map tracking mode, otherwise deactivate
[in]	i	reserved for future applications. Use 0 for now.
[in]	j	reserved for future applications. Use 0 for now.

Returns

Error code (Errorcodes)