|
|
||
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 |
| SDK_ERROR SDK_API SDK_LoadTour | ( | SDK_Tour ** | tour, |
| const SDK_WCHAR_T * | filename | ||
| ) |
Load a tour from a BCR file.
This method loads a tour from a given BCR file (which was formerly created by SDK_SaveTour()). A BCR file is a kind of ini file which stores information about a tour by persisting the stations in a special format. For more details about the format, see the external BCR documentation.
The tour will be newly created with the operator 'new' by calling this method, so be sure to delete it afterwards with SDK_DeleteTour(). If the tour object you pass in was formerly created with SDK_CreateTour() or with this function, delete the tour with SDK_DeleteTour() before calling this function to avoid memory leaks.
Attention: The start station of the tour will be set to the first station in the file ("STATION1"). All following stations in the file will be handled as destinations. SVP points are supported and will be properly added to the tour.
There is no route calculation triggered after the loading. To calculate the loaded tour, call SDK_CalculateTour().
| [in,out] | tour | The tour object, which will be filled by the function |
| [in] | filename | The name of the BCR file to load |
| SDK_ERROR SDK_API SDK_SaveTour | ( | const SDK_Tour * | tour, |
| const SDK_WCHAR_T * | filename | ||
| ) |
Save a tour to a BCR file.
This method saves a tour to a given BCR file. A BCR file is a kind of ini file which stores information about a tour by persisting the stations in a special format. For more details about the format, see the external BCR documentation.
Attention: "STATION1" in the BCR file will be set to the start station of the tour. All other stations of the tour will be written in the order of appearance. Also, the BCR format has much more fields which are not filled by SDK_SaveTour, only values in SDK_Waypoint and SDK_SVPWaypoint will be saved (e.g. the skipped flag will not be set in the BCR). SVP points are supported and will be properly written.
| [in] | tour | The tour object, which should be persisted |
| [in] | filename | The name of the BCR file to save the tour to |
| SDK_ERROR SDK_API SDK_GetTourStartStation | ( | const SDK_Tour * | tour, |
| SDK_Waypoint * | start | ||
| ) |
Get the start station from a tour.
This method is a reads the start station of a tour (which was created with SDK_CreateTour() or loaded with SDK_LoadTour()).
| [in] | tour | The tour object to read from |
| [in,out] | start | Will be filled with the start station of the tour |
Get the number of destinations of a tour.
This method is used to get the number of destination stations of a tour.
| [in] | tour | The tour object to read from |
| [in,out] | count | Will be set to the number of destinations of the tour |
| SDK_ERROR SDK_API SDK_GetTourDestinationType | ( | const SDK_Tour * | tour, |
| SDK_UINT4 | index, | ||
| SDK_INT1 * | type | ||
| ) |
Get the destination type of a tour destination.
This method retrieves the destination type of the station at the given index. There are two types of stations
| [in] | tour | The tour object to read from |
| [in] | index | The index of the wanted destination (starts from 0) |
| [in,out] | type | Will be set to the destination type of the station at the given index (0 == regular, 1 == SVP) |
| SDK_ERROR SDK_API SDK_GetTourDestination | ( | const SDK_Tour * | tour, |
| SDK_UINT4 | index, | ||
| SDK_Waypoint * | destination | ||
| ) |
Get a destination from a tour.
This method gets one destination station from a tour (either a regular or an SVP station) at the given index. If the station is an SVP station, the destination will be filled with the last SVP point.
| [in] | tour | The tour object to read from |
| [in] | index | The index of the wanted destination (starts from 0) |
| [in,out] | destination | Will be set to the destination at index. If the destination is an SVP station, it will be filled with the last SVP point of this station |
| SDK_ERROR SDK_API SDK_GetTourDestinationSVPs | ( | const SDK_Tour * | tour, |
| SDK_UINT4 | index, | ||
| SDK_SVPWaypoint ** | waypoints, | ||
| SDK_UINT4 * | waypointsCount | ||
| ) |
Get the SVP points of a destination.
If the destination at the given index is an SVP station, the waypoints array will be filled with the approriate SVP points. If the station is a regular station an error will be returned.
| [in] | tour | The tour object to read from |
| [in] | index | The index of the wanted destination (starts from 0) |
| [in,out] | waypoints | Will be filled with the last SVP point of this station |
| [in,out] | waypointsCount | Will be set to the number of SVP points in waypoints |
| SDK_ERROR SDK_API SDK_GetReRouteAttractionFactor | ( | const SDK_Tour * | tour, |
| SDK_INT4 * | reRouteAttractionFactor | ||
| ) |
Get the reroutefactor of tour.
If a tour was loaded per file, a special reroute attraction factor could be set for this tour (see SDK_NavigationSettings for more details). This method is used to retrieve this value. A value of -1 indicates that no attraction factor was set in the file.
To use it for navigation, this value has to be set in SDK_NavigationSettings.
| [in] | tour | The tour object to read from |
| [in,out] | reRouteAttractionFactor | Will be set to the factor of this tour (Regular = -1 no value set, else value stored in tourfile). |
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_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.
| 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_GetManeuverArrowVisibility | ( | SDK_INT4 | MapView, |
| SDK_BOOL * | isVisible2d, | ||
| SDK_BOOL * | isVisible3d | ||
| ) |
Retrieves the visibility of maneuver arrows - separately in 2d and 3d.
| [in] | MapView | Handle to the MapView/MapDC |
| [out] | isVisible2d | The visibility in 2d mode |
| [out] | isVisible3d | The visibility in 3d mode |
| SDK_ERROR SDK_API SDK_SetManeuverArrowVisibility | ( | SDK_INT4 | MapView, |
| SDK_BOOL | isVisible2d, | ||
| SDK_BOOL | isVisible3d | ||
| ) |
Enables or disables the visibility of the maneuver arrows - separately in 2d and 3d.
| [in] | isVisible2d | Sets visibility in 2d mode |
| [in] | isVisible3d | Sets visibility in 3d mode |
| SDK_ERROR SDK_API SDK_GetManeuverArrow | ( | const SDK_ManeuverDescription * | maneuver, |
| const SDK_CrossingView * | crossing, | ||
| SDK_INT4 * | maneuverArrow | ||
| ) |
Retrieve a simplified arrow representation for the given maneuver situation.
| [in] | maneuver | |
| [in] | crossing | |
| [out] | maneuverArrow | (Maneuver arrow types) |
| 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 2019 | Generated on Thu Mar 28 2019 02:27:02 for NavigationSDK by  1.8.8 |