Navigation API

Overview

Navigation API is about getting into navigation mode after route calculation is done, and monitoring the navigation by means of events.
There are several functions, which start up the navigation mode, namely StartNavigation, NavigateToAddress, SetRoute and LoadComputedRoute. To prematurely abandon the navigation mode StopNavigation needs to be called.
During the navigation you can monitor the actual execution using GetRouteStatus, or control navigation using SkipNextWaypoint.
As navigation progresses various API events are generated and it is a decision of a programmer whether to react on the events, such as route finished, passing waypoint, speed limit exceeded, etc.

StartNavigation

StartNavigation triggers route calculation a navigation to a single destination point defined with GPS coordinates, specified by WayPoint class object.
The start position is selected to be an actual GPS position, or if not currently available, the last valid position is initially used. In case the valid position is not known the function gets into the "Waiting for valid position" state. Once the GPS fix is obtained the route calculation is automatically triggered and navigation mode entered.
There can be few exceptions occuring with the function call, the most typical one would be the out of map condition.
Check details of StartNavigation in the reference manual.

Example

This example shows how to start navigation from a current GPS coordinates and capture an error message in case of a problem.

  using ApplicationAPI;

  void demo()
  {
        SError err;
        int ret;
        int maxTime = 0;

        SGpsPosition gps = new SGpsPosition();
        bool bSatellitesInfo = false;
        maxTime = 0;
        ret = CApplicationAPI.GetActualGpsPosition(out err, out gps, bSatellitesInfo, maxTime);
        if (ret != 1)
        {
           return; // problem
        }
        lat = gps.Latitude;
        lon = gps.Longitude;

        int flags = 0;
        bool bShowNavigation = true;
        bool bSearchAddress = false;
        maxTime = 0;
        SWayPoint wp = new SWayPoint();
    int x = (int)(lon * 100000);
    int y = (int)(lat * 100000);
        wp.Location.lX = x;
        wp.Location.lY = y; 
    WayPoint wp = new WayPoint("B", x, y);  
        if (CApplicationAPI.StartNavigation(out err, ref wp, flags, bShowNavigation, bSearchAddress, maxTime) != 1)
        {
           // problem
        }
}

Example

This example shows StartNavigation with fuzzy search on a given address string.

using ApplicationAPI;

void demo()
{
    string strAddress = "SVK,Bratislava,Einsteinova,18";    
    SError err;
    int maxTime = 0; 

    bool postal = false;
    bool fuzzy = true;
    LONGPOSITION location;
    int ret = CApplicationAPI.LocationFromAddress(out err, out location, strAddress, postal, fuzzy, maxTime);
    if (ret != 1)
    {
       return;
    }

    int flags = 0;
    bool bShowNavigation = true;
    bool bSearchAddress = true;
    SWayPoint wp = new SWayPoint();    
    wp.Location.lX = location.lX;
    wp.Location.lY = location.lY;
    if (CApplicationAPI.StartNavigation(out err, ref wp, flags, bShowNavigation, bSearchAddress, maxTime) != 1)
    {
       // problem
    }
}

NavigateToAddress

NavigateToAddress is similar to StartNavigation except that it takes the destination from an address string instead of explicit GPS latitude/longitude coordinates.
There can be few exceptions occuring with the function call, the most typical one would be an incorrect input of address string. The address string syntax is subject to address string specification, which follows the geocoding rules defined by LocationFromAddress.
Check details of NavigateToAddress in the reference manual.

Example

using ApplicationAPI;

void demo()
    string address = "SVK,Bratislava,Einsteinova,18";
    SError err;
    boolean postal = false;
    boolean bShowNavigation = true;
    int flags = 0;
    int ret = CApplicationAPI.NavigateToAddress(out err, address, postal, flags, bShowNavigation, 0);
    if (ret != 1)
    {
       // problem
    }

Example using postal scheme

using ApplicationAPI;

void demo()
    string address = "SVK,811 09,Einsteinova,18";
    SError err;
    boolean postal = true;
    boolean bShowNavigation = true;
    int flags = 0;
    int ret = CApplicationAPI.NavigateToAddress(out err, address, postal, flags, bShowNavigation, 0);
    if (ret != 1)
    {
       // problem
    }

SetRoute

SetRoute sets the given itinerary referenced by its name for route calculation followed by navigation.
The function is described in the Routes API section.

StopNavigation

StopNavigation cancel the routes and stops the navigation mode.
Cancel route is automatically done when navigation reaches the destination. This functions is applied with a premature stop.
Check details of StopNavigation in the reference manual.

Example

using ApplicationAPI;

void cancel()
{
    SError err;
    int ret = CApplicationAPI.StopNavigation(out err, 0);
    if (ret != 1)
    {
       // problem
    }
}

GetRouteStatus

GetRouteStatus retrieves the status of route execution during navigation and mainly returns ETAs and remaining distances to routes' waypoints
being it a simple destinaation waypoint for single route or many with a complext itinerary.
The function is described in the Routes API section.

SkipNextWaypoint

SkipNextWaypoint allows removing the approching waypoint from itinerary and thus cause route recalculation, as it is not anymore mandatory to pass the waypoint.
This function is typically called when a waypoint representing e.g. a customer delivery point is during navigation revoked.
Check details of SkipNextWaypoint in the reference manual.

Example

void skip()
{
    SError err;
    int ret = CApplicationAPI.SkipNextWaypoint(out err, 0);
    if (ret != 1)
    {
       // problem
    }
}

Events

API Events allow monitoring of significat navigation events with a possibility to react on it.
There are various events available.

Check details of Api Events in the reference manual.

Example

void NaviHandler(int nEventID, IntPtr strData)
{
    // cast the event to ApplicationEvents enumeration
    ApplicationEvents anAppEvent = (ApplicationEvents)nEventID;

    // handle event
    switch (anAppEvent)
    {
      case ApplicationEvents.EVENT_ROUTE_FINISH:
         Debug.WriteLine("Destination reached.");
         break;
    }
}

int StartSygic()
{
    string mySygicPath = ...
    IntPtr inParentWnd = ...
    CApplicationAPI.ApplicationHandler AppHnd = new CApplicationAPI.ApplicationHandler(NaviHandler);
    int ret = CApplicationAPI.InitApi(mySygicPath, AppHnd, 0, 0, 320, 240, true, false, inParentWnd);
    return ret;
}