|
|
||
Navigation SDK Documentation |
||
Functions for routing.
| SDK_ERROR SDK_API SDK_GetRoutingOptions | ( | SDK_RouteOptions * | pRoutingSettings | ) |
Retrieve the routing settings.
| [out] | pRoutingSettings | The structure to be filled with the current settings. |
| 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.
\return Error code (\ref Errorcodes).
| SDK_ERROR SDK_API SDK_GetLorryOptions | ( | SDK_LorryOptions * | pLorrySettings | ) |
Retrieve the lorry settings.
| [out] | pLorrySettings | The structure to be filled with the current settings. |
| 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.
| [in] | pLorrySettings | Structure 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. |
| 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.
| [in] | pFilename | The filename of the profile file (with full path). |
| 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.
| [in] | pFilename | The filename of the profile file (with full path). |
| [in] | cc | The country code for the wanted translation. |
| [in,out] | pProfileName | The name of the profile. |
| 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!
| [in] | pWaypointStart | Pointer to the start stop-off point. |
| [in] | pWaypointTarget | Pointer to the target stop-off point. |
| [out] | pMatchedWaypoints | Matched 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] | iViaCount | Number of points / radii in the arrays pViaPoint and pViaRadius. Set to 0 if no via routing is wanted. |
| [in] | pViaPoint | Array of via points. Set to 0 if no via routing is wanted. |
| [in] | pViaRadius | Array of radii for the points given in pViaPoint. Set to 0 if no via routing is wanted. |
| [in] | pCallBackFunc | Optional pointer to a callback method. Used to indicate the actual status of the routing process. May be NULL or of type SDK_ProgressCBFuncT. |
| 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:
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);
| [in] | tour | A pointer to a pointer to an SDK_Tour. |
| [in] | pos | The start position of the tour. |
| 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.
| [in] | tour | The tour to delete. |
| SDK_ERROR SDK_API SDK_AddStationToTour | ( | SDK_Tour * | tour, |
| SDK_Waypoint | waypoint | ||
| ) |
Add a regular station to a tour.
| [in] | tour | The tour to a add a station to. |
| [in] | waypoint | The coordinate of the station. |
| 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.
| [in] | tour | The tour to a add an svp station to. |
| [in] | svpCount | The number of provided coordinates. |
| [in] | pSVPWaypoints | The provided SVP route coordinates. |
| 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.
| [in] | tour | The tour which should be calculated |
| [in] | pCallBackFunc | Optional progress callback |
| [out] | If | an error returns, the error belongs to the returned tour section |
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.
| [in] | mercator | x coordinate of the current position. |
| [in] | mercator | y coordinate of the current position. |
| [in] | visited | Mark 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.
| [in,out] | pRouteInformation | |
| [in] | routeIdx | the 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] | alternativeRouteNumber | the index of the route alternative. If alternative route calculation is not activated, only an index of 0 will return a route. |
Get the number of alternative routes including the default or original route.
| [in,out] | routeCount | the number of alternative routes. If alternative routing is not activated, you will always get 1. |
Get the current active route alternative.
| [in,out] | routeActive | the index of the current active alternative route |
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.
| [in] | routeNumber | the index of the alternative route to hilight. |
| 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.
| [in] | pRouteFileName | Name 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] | pTargetDescription | Supply additional information about route. Maybe NULL. |
| SDK_ERROR SDK_API SDK_SaveRoute | ( | const SDK_WCHAR_T * | pRouteFileName, |
| SDK_BOOL | bOverWrite | ||
| ) |
Save the current existing route.
| [in] | pRouteFileName | file name where the route will be saved to |
| [in] | bOverWrite | If SDK_TRUE overwrite an existing file, else return an error if the file already exists |
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().
| [in] | dist | Distance on current route [m]. Use 0 to cancel the last request. |
| 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.
| [in] | dist | distance along the route [m] |
| [out] | left | left value of the rectangle [merc] |
| [out] | top | top value of the rectangle [merc] |
| [out] | right | right value of the rectangle [merc] |
| [out] | bottom | bottom value of the rectangle [merc] |
Return the number of stop-off points of a calculated route.
Returns the number of maneuvers of a calculated route.
| [in] | ListMode | The 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] | pCount | Number of stop-off points or ErrorCode |
| 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.
| [in] | ListMode | The desired ListMode type (lmComplete or lmImportant). |
| [in] | StopOffID | The ID of the stop-off point. The first stop-off has id=1! |
| [out] | pSDK_StopOffInformation | Pointer to the StationInformation object. Contains the detailed information of the stop-off point. |
| 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.
| [in] | pSimFileName | Name of file to be created. |
| © PTV Group 2018 | Generated on Mon Dec 17 2018 21:00:19 for NavigationSDK by  1.8.8 |