Navigation SDK Documentation

Functions

Functions

SDK_ERROR SDK_API SDK_GetRoutingOptions (SDK_RouteOptions *pRoutingSettings)
 
SDK_ERROR SDK_API SDK_SetRoutingOptions (const SDK_RouteOptions *pRoutingSettings)
 
SDK_ERROR SDK_API SDK_GetLorryOptions (SDK_LorryOptions *pLorrySettings)
 
SDK_ERROR SDK_API SDK_SetLorryOptions (const SDK_LorryOptions *pLorrySettings)
 
SDK_ERROR SDK_API SDK_LoadVehicleProfile (const SDK_WCHAR_T *pFilename)
 
SDK_ERROR SDK_API SDK_GetProfileName (const SDK_WCHAR_T *pFileName, const SDK_WCHAR_T *cc, SDK_WCHAR_T **pProfileName)
 
SDK_ERROR SDK_API SDK_CalculateViaRoute (const SDK_Waypoint *pWaypointStart, const SDK_Waypoint *pWaypointTarget, SDK_MatchedWaypoint *pMatchedRouteStopOff, SDK_INT4 iViaCount, SDK_Position *pViaPoint, SDK_INT4 *pViaRadius, SDK_ProgressCBFuncT pCallBackFunc)
 
SDK_ERROR SDK_API SDK_CreateTour (SDK_Tour **tour, SDK_Waypoint startPosition)
 
SDK_ERROR SDK_API SDK_DeleteTour (SDK_Tour *tour)
 
SDK_ERROR SDK_API SDK_AddStationToTour (SDK_Tour *tour, SDK_Waypoint waypoint)
 
SDK_ERROR SDK_API SDK_AddSVPsToTour (SDK_Tour *tour, SDK_INT4 svpCount, const SDK_SVPWaypoint *pSVPWaypoints)
 
SDK_ERROR SDK_API SDK_CalculateTour (const SDK_Tour *tour, SDK_ProgressCBFuncT pCallBackFunc, SDK_INT2 *pSectionErrorBelongsTo)
 
SDK_ERROR SDK_API SDK_SelectNextStation (SDK_INT4 coordX, SDK_INT4 coordY, SDK_BOOL visited)
 
SDK_ERROR SDK_API SDK_GetRouteInformation (SDK_RouteInformation *pRouteInformation, SDK_INT1 routeIdx, SDK_INT4 alternativeRouteNumber)
 
SDK_ERROR SDK_API SDK_GetAlternativeRouteCount (SDK_INT4 *routeCount)
 
SDK_ERROR SDK_API SDK_GetAlternativeRouteActive (SDK_INT4 *routeActive)
 
SDK_ERROR SDK_API SDK_SetAlternativeRouteActive (SDK_INT4 routeNumber)
 
SDK_ERROR SDK_API SDK_LoadRoute (const SDK_WCHAR_T *pRouteFileName, const SDK_TargetDescription *pTargetDescription)
 
SDK_ERROR SDK_API SDK_SaveRoute (const SDK_WCHAR_T *pRouteFileName, SDK_BOOL bOverWrite)
 
SDK_ERROR SDK_API SDK_AvoidDistanceInFront (SDK_INT4 dist)
 
SDK_ERROR SDK_API SDK_GetGuidanceRect (SDK_INT4 dist, SDK_INT4 &left, SDK_INT4 &top, SDK_INT4 &right, SDK_INT4 &bottom)
 
SDK_ERROR SDK_API SDK_GetManeuverCount (SDK_INT4 ListMode, SDK_INT4 *pCount)
 
SDK_ERROR SDK_API SDK_GetManeuverPoint (SDK_INT4 ListMode, SDK_INT4 StopOffID, SDK_ManeuverDescription *pSDK_StopOffInformation)
 
SDK_ERROR SDK_API SDK_CreateGPSSimulation (const SDK_WCHAR_T *pSimFileName)
 

Detailed Description

Functions for routing.

Function Documentation

SDK_ERROR SDK_API SDK_GetRoutingOptions ( SDK_RouteOptions pRoutingSettings)

Retrieve the routing settings.

Parameters
[out]pRoutingSettingsThe structure to be filled with the current settings.
Returns
Error code (Errorcodes)
SDK_ERROR SDK_API SDK_SetRoutingOptions ( const SDK_RouteOptions pRoutingSettings)

Set the routing settings.

Call SDK_GetRoutingOptions() before calling SDK_SetRoutingOptions() to retrieve the default values.

With this function, all available routing options can be set manually. 

Hint: Because some of the options are not easily settable without a deeper knowing of their impact to routing and navigation and to simplify the 
task of setting options for a particular vehicle, we recommend to use \ref SDK_LoadVehicleProfile, which loads a PTV Navigator vehicle profile 
from a file and sets the routing-, navigation- and lorry options appropriately for the selected vehicle.
After loading the profile, you can certainly use this function to change special options afterwards.

\param[in] pRoutingSettings Structure with the new settings.

If NULL the default settings are restored.

Bug:
if vehicle profile SDK_rvUSER is selected then the flags RouteWithoutFerry and RouteWithoutAutoroute may not work. To get close to the desired behaviour use 0 speed for the road types 12 and (0-2).
\return Error code (\ref Errorcodes).  
SDK_ERROR SDK_API SDK_GetLorryOptions ( SDK_LorryOptions pLorrySettings)

Retrieve the lorry settings.

Parameters
[out]pLorrySettingsThe structure to be filled with the current settings.
Returns
Error code (Errorcodes)
SDK_ERROR SDK_API SDK_SetLorryOptions ( const SDK_LorryOptions pLorrySettings)

Set the Lorry settings.

With this function, all available lorry options can be set manually.

Hint: Because some of the options are not easily settable without a deeper knowing of their impact to routing and navigation and to simplify the task of setting options for a particular vehicle, we recommend to use SDK_LoadVehicleProfile, which loads a PTV Navigator vehicle profile from a file and sets the routing-, navigation- and lorry options appropriately for the selected vehicle. After loading the profile, you can certainly use this function to change special options afterwards.

Parameters
[in]pLorrySettingsStructure to be filled with the new settings. If NULL the default settings are restored. One may use SDK_GetLorryOptions() before calling SDK_SetLorryOptions() to retrieve the default values.
Returns
Error code (Errorcodes).
SDK_ERROR SDK_API SDK_LoadVehicleProfile ( const SDK_WCHAR_T pFilename)

Load a vehicle profile from a PTV Navigator profile file.

This routine loads a PTV Navigator vehicle profile file and sets the routing-, lorry- and navigation options appropriately to the values for the particular vehicle. We recommend to use this function instead of setting the routing-, navigation- and lorry options manually unless you need the full control over the options. We deliver predefined profiles for slow and fast cars, slow and fast trucks and many more vehicles. All relevant options like the speed tables will be set to the values in the file when loading it with this function. After loading a profile, you can certainly use SDK_SetLorryOptions, SDK_SetRoutingOptions and SDK_SetNavigationSettings to change special options afterwards.

Parameters
[in]pFilenameThe filename of the profile file (with full path).
Returns
Error code (Errorcodes).
SDK_ERROR SDK_API SDK_GetProfileName ( const SDK_WCHAR_T pFileName,
const SDK_WCHAR_T cc,
SDK_WCHAR_T **  pProfileName 
)

Get the profile name from the profile given by pFilename.

Load the profile name for the given iso code (SDK_ccf_ISO_2) from the profile file. If cc == 0, the english version of the name will be returned if available.

Parameters
[in]pFilenameThe filename of the profile file (with full path).
[in]ccThe country code for the wanted translation.
[in,out]pProfileNameThe name of the profile.
Returns
Error code (Errorcodes).
SDK_ERROR SDK_API SDK_CalculateViaRoute ( const SDK_Waypoint pWaypointStart,
const SDK_Waypoint pWaypointTarget,
SDK_MatchedWaypoint pMatchedRouteStopOff,
SDK_INT4  iViaCount,
SDK_Position pViaPoint,
SDK_INT4 pViaRadius,
SDK_ProgressCBFuncT  pCallBackFunc 
)

Calculate a route through a via area.

The routing will try to route through every given via area, so you can manipulate the original routing pathway. These areas have to be specified by an array of points and a corresponding array of radii.

For s standard route or tour calculation without via areas, please use SDK_CalculateTour.

Note that this call may change the currently open map within the Navigation SDK!

Parameters
[in]pWaypointStartPointer to the start stop-off point.
[in]pWaypointTargetPointer to the target stop-off point.
[out]pMatchedWaypointsMatched stop-off points on the map. May be NULL. If no route can be calculated and the error code is SDK_ERROR_NoRouteFound a coordinate set to {-1,1} indicates that this station could not be linked (maybe the street is not allowed for the specified vehicle type).
[in]iViaCountNumber of points / radii in the arrays pViaPoint and pViaRadius. Set to 0 if no via routing is wanted.
[in]pViaPointArray of via points. Set to 0 if no via routing is wanted.
[in]pViaRadiusArray of radii for the points given in pViaPoint. Set to 0 if no via routing is wanted.
[in]pCallBackFuncOptional pointer to a callback method. Used to indicate the actual status of the routing process. May be NULL or of type SDK_ProgressCBFuncT.
Returns
Error code (Errorcodes). SDK_ERROR_NoMap indicates that one the required maps is missing, this may indicate a missing major road map for cross-border routing. SDK_ERROR_OutOfResources indicates that the route can not be calculated with the given routing options.
SDK_ERROR SDK_API SDK_CreateTour ( SDK_Tour **  tour,
SDK_Waypoint  startPosition 
)

Create a tour with the given coordinate as start coordinate.

This function creates an SDK_Tour object and adds the given station as the start station. A tour is an object that holds a start station and one or multiple stations. A tour can contain "regular" stations and SVP stations. Regular stations are stations which are defined solely by a geo-coordinate. SVP stations are defined by a set of coordinates with directions (and other attributes) which describe a way to get to a destination. Attention: The direction of the start station will be set internally to -1 and will override a potential course to ensure that the start station can be linked correctly. All other stations in the tour can have a direction (or the course can be set to -1 to ignore the direction). The tour can be calculated later by calling SDK_CalculateTour. You can create as many tours as you want, but be sure to free them if not used anymore by calling SDK_DeleteTour. To calculate a tour and start a navigation, do the following:

  • Create a tour with SDK_CreateTour with the start position as parameter pos and a tour pointer. The tour will be allocated by this function.
  • Add as much following stations as you like with SDK_AddStationToTour or SDK_AddSVPsToTour to the generated tour.
  • Call SDK_CalculateTour to calculate the tour.
  • Delete the tour object if not needed anymore by calling SDK_DeleteTour.

An example for creating a tour with Karlsruhe town center as start position would be:

SDK_WayPoint startPos; SDK_InitWaypoint(&startPos); startPos.x = 960040; startPos.y = 6985085; SDK_Tour * tour; SDK_CreateTour(&tour, startPos);

Parameters
[in]tourA pointer to a pointer to an SDK_Tour.
[in]posThe start position of the tour.
Returns
Error code (Errorcodes)
SDK_ERROR SDK_API SDK_DeleteTour ( SDK_Tour *  tour)

Delete a tour.

This function deletes a formerly generated SDK_Tour. Be sure to call this function on tours that are not needed anymore to avoid memory leaks.

Parameters
[in]tourThe tour to delete.
Returns
Error code (Errorcodes)
SDK_ERROR SDK_API SDK_AddStationToTour ( SDK_Tour *  tour,
SDK_Waypoint  waypoint 
)

Add a regular station to a tour.

Parameters
[in]tourThe tour to a add a station to.
[in]waypointThe coordinate of the station.
Returns
Error code (Errorcodes)
SDK_ERROR SDK_API SDK_AddSVPsToTour ( SDK_Tour *  tour,
SDK_INT4  svpCount,
const SDK_SVPWaypoint pSVPWaypoints 
)

Add an SVP station to a tour.

An SVP station is a set of coordinates + direction which describe an approximation of a route to a destination. The navigation sdk will try to calculate a route which comes close to the provided coordinates.

Parameters
[in]tourThe tour to a add an svp station to.
[in]svpCountThe number of provided coordinates.
[in]pSVPWaypointsThe provided SVP route coordinates.
Returns
Error code (Errorcodes)
SDK_ERROR SDK_API SDK_CalculateTour ( const SDK_Tour *  tour,
SDK_ProgressCBFuncT  pCallBackFunc,
SDK_INT2 pSectionErrorBelongsTo 
)

Calculate a route/tour.

This method calculates the first route of the given tour, generates its route trace, appends all route traces of the next stations (added with SDK_AddStationToTour and SDK_AddSVPsToTour), and activates the guidance of the first route. This method has to be called before a navigation on a tour can be started.

Calculating a tour to one or to multiple stations is done by the following steps:

You can also use this function to calculate standard A-B routes by adding only one station with SDK_AddStationToTour. In this case, there is also the possibility to calculate alternative routes (up to 3) by setting the SDK_RouteOptions parameter RouteCalculationType to SDK_RouteAlternative. If no alternatives should be calculated, set the parameter to SDK_RouteClassic.

See also SDK_SetAlternativeRouteActive, SDK_getAlternativeRouteActive, SDK_GetRouteInformation.

When an error in the calculation of a tour section occurs, the returned error code will be set and the tour section which caused the error will be returned in pSectionErrorBelongsTo.

The tour will not be deleted by this function. Be sure to call SDK_DeleteTour() to avoid memory leaks.

Parameters
[in]tourThe tour which should be calculated
[in]pCallBackFuncOptional progress callback
[out]Ifan error returns, the error belongs to the returned tour section
Returns
Error code (Errorcodes)
SDK_ERROR SDK_API SDK_SelectNextStation ( SDK_INT4  coordX,
SDK_INT4  coordY,
SDK_BOOL  visited 
)

Switch to the next station during multi station routing.

This method might only be called during a multi station routing. It marks the current destination as visited or skipped. Then it calculates a route to the next station which is neither visited nor skipped. The route is calculated from the provided position.

Parameters
[in]mercatorx coordinate of the current position.
[in]mercatory coordinate of the current position.
[in]visitedMark the current station visited (true) or skipped (false).
SDK_ERROR SDK_API SDK_GetRouteInformation ( SDK_RouteInformation pRouteInformation,
SDK_INT1  routeIdx,
SDK_INT4  alternativeRouteNumber 
)

Get information about a route and their optional alternatives.

Return general information about a route and their optional alternatives like the length, the duration and so on. If a route calculation was started with alternatives, the first routes' number is 0, the next alternatives number is 1 and so on. The total number of route alternatives can be retrieved via SDK_GetAlternativeRouteCount. If the route was calculated without alternatives, alternativeRouteNumber has to be set to 0.

Parameters
[in,out]pRouteInformation
[in]routeIdxthe index of the route about which to return the route information for a multi station tour. This value is ignored if no multi station tour is calculated. In the case of a multi station tour '-1' will return the accumulated route information over all routes. '0' returns the route information of the current route. '1' returns the route information of the first inactive route, '2' returns the route information of the second inactive route, and so on.
[in]alternativeRouteNumberthe index of the route alternative. If alternative route calculation is not activated, only an index of 0 will return a route.
Returns
Error code (Errorcodes).
SDK_ERROR SDK_API SDK_GetAlternativeRouteCount ( SDK_INT4 routeCount)

Get the number of alternative routes including the default or original route.

Parameters
[in,out]routeCountthe number of alternative routes. If alternative routing is not activated, you will always get 1.
Returns
Error code (Errorcodes).
SDK_ERROR SDK_API SDK_GetAlternativeRouteActive ( SDK_INT4 routeActive)

Get the current active route alternative.

Parameters
[in,out]routeActivethe index of the current active alternative route
Returns
Error code (Errorcodes).
SDK_ERROR SDK_API SDK_SetAlternativeRouteActive ( SDK_INT4  routeNumber)

Set the given route as the active route.

The active route will be highlighted in a map view, while the other alternative routes will get greyed out. As soon as SDK_GetGuidanceInformation is called for the first time, the currently selected alternative will be the only selectable alternative. The SDK will remove the unwanted alternatives automatically and start navigation.

Parameters
[in]routeNumberthe index of the alternative route to hilight.
Returns
Error code (Errorcodes).
SDK_ERROR SDK_API SDK_LoadRoute ( const SDK_WCHAR_T pRouteFileName,
const SDK_TargetDescription pTargetDescription 
)

Load a saved route (.mre file).

Note that a route is tied to a map and can only be loaded if the very same map is available. The same map means it's not possible to use an updated or newer one even for the same country.

Parameters
[in]pRouteFileNameName of existing route file. The route will be appended to existing routes which have been calculated (SDK_CalculateRoute(), estimated (SDK_EstimateRoute()), created ( or SDK_CreateOffroadGuidance()), or loaded (SDK_LoadRoute()). If NULL then those previous routes will discarded.
[in]pTargetDescriptionSupply additional information about route. Maybe NULL.
Returns
Error code (Errorcodes). SDK_ERROR_DistanceTooLong is being returned if the routes are disconnected, i.e. if a route is about to be loaded which doesn't start at the end of the previous calculated/loaded.
SDK_ERROR SDK_API SDK_SaveRoute ( const SDK_WCHAR_T pRouteFileName,
SDK_BOOL  bOverWrite 
)

Save the current existing route.

Bug:
Currently only implemented for a single route within a single map
Parameters
[in]pRouteFileNamefile name where the route will be saved to
[in]bOverWriteIf SDK_TRUE overwrite an existing file, else return an error if the file already exists
Returns
Error code (Errorcodes)
SDK_ERROR SDK_API SDK_AvoidDistanceInFront ( SDK_INT4  dist)

Avoid distance ahead on current route.

The navigation will try to avoid a given distance on the current route if possible. If there is no other way around it keeps following the original route. This call will take effect upon the next call to SDK_GetGuidanceInformation().

Bug:
This interface takes effect only on the part of the route within the current active map!
Parameters
[in]distDistance on current route [m]. Use 0 to cancel the last request.
Returns
Error code (Errorcodes)
SDK_ERROR SDK_API SDK_GetGuidanceRect ( SDK_INT4  dist,
SDK_INT4 left,
SDK_INT4 top,
SDK_INT4 right,
SDK_INT4 bottom 
)

Get a rectangle around the current route for a certain distance.

Parameters
[in]distdistance along the route [m]
[out]leftleft value of the rectangle [merc]
[out]toptop value of the rectangle [merc]
[out]rightright value of the rectangle [merc]
[out]bottombottom value of the rectangle [merc]
Returns
Error code (Errorcodes)
SDK_ERROR SDK_API SDK_GetManeuverCount ( SDK_INT4  ListMode,
SDK_INT4 pCount 
)

Return the number of stop-off points of a calculated route.

Returns the number of maneuvers of a calculated route.

Parameters
[in]ListModeThe Listmode of the result (see Stop-Off list modes) SDK_lmCOMPLETE returns all stop-off points of the list, also the ones that are not necessary to navigate. SDK_lmIMPORTANT only returns the relevant stop-off points.
[out]pCountNumber of stop-off points or ErrorCode
Returns
Error code (Errorcodes)
SDK_ERROR SDK_API SDK_GetManeuverPoint ( SDK_INT4  ListMode,
SDK_INT4  StopOffID,
SDK_ManeuverDescription pSDK_StopOffInformation 
)

Get detailed information of a stop-off point.

Query detailed information of a maneuver point.

Parameters
[in]ListModeThe desired ListMode type (lmComplete or lmImportant).
[in]StopOffIDThe ID of the stop-off point. The first stop-off has id=1!
[out]pSDK_StopOffInformationPointer to the StationInformation object. Contains the detailed information of the stop-off point.
Returns
Error code (Errorcodes)
SDK_ERROR SDK_API SDK_CreateGPSSimulation ( const SDK_WCHAR_T pSimFileName)

Create a GPS simulation file.

Create a GPS simulation file for the most recent calculated route.

Parameters
[in]pSimFileNameName of file to be created.
Returns
Error code (Errorcodes)

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