Init API

Overview

Init API provides initialization and management functions to control Navigation module in terms of opening and closing operations.

It contains functions, which set up or close down connection such as InitApi and CloseApi, functions, which can exit navigation EndApplication, monitoring whether navigation is running, exit or in background through IsApplicationRunning and IsApplicationInForeground.
There are supporting functions, which allows you to put navigation into foreground or background such as BringApplicationToBackground and BringApplicationToForeground

Finally the API contains the version status functions such as GetMapVersion, GetApplicationVersion and GetSdkVersion.

Initialization

It is important to follow the correct initilization flow so that one avoids undesired errors when calling API functions.

InitApi is the decisive operation in the initialization flow as it opens API channel and triggers Navigation start.
The function defines which version of navigation is started, the placement on screen, and optionally but typically the callback handler.
For more details please check InitApi.

It is important that the InitApi is called from within a separate thread.

Initialization example

This sample demonstrates how to open Sygic navigation.
Here we demonstrate using Sygic Professional navigation, which is represented by the 1st argument of InitApi through SygicNavi variable. The exact filepath depends on your installation of Sygic navigation.
E.g. when using WindowsCE devices the path could be:
string SygicNavi = @"sdcard\Drive\WindowsCE\Drive.exe"

public void InitializationExample()
{
   // selecting Panel as embedding for navigation
   this.Embed_Width  = Panel.Width;
   this.Embed_Height = Panel.Height;
   this.Embed_Handle = Panel.Handle;

   Thread t = new Thread(StartSygic);
   t.Start();
}

public static int StartSygic()
{
    string SygicNavi = @"d:\SygicNavigation\bin\Fleet.exe";  // path to Sygic navigation executable
    int inLeft = 0;                   // X coordinate of Sygic application
    int inTop = 0;                    // Y coordinate of Sygic application
    int inWidth = this.Embed_Width;   // width of Sygic application
    int inHeight = this.Embed_Height; // height of Sygic application
    bool inRunForeground = true;      // true for running Sygic in foreground
    bool inNoCaption = false;         // true for removing the border of Sygic application window
    IntPtr inParentWnd = this.Embed_Handle;  // parent window definition

    CApplicationAPI.ApplicationHandler AppHnd = new CApplicationAPI.ApplicationHandler(NaviHandler);
    int ret = CApplicationAPI.InitApi(SygicNavi, AppHnd, inLeft, inTop, inWidth, inHeight, inRunInForeground, inNoCaption, inParentWnd);
    return ret;
}

public static void NaviHandler(int nEventID, IntPtr strData)
{
    // process navigation events if needed
}

Callback handler

Majority of integrating applications want to capture navigation events so that they can react appropriately.
It is the ApplicationHandler class object, which enacapsulates all events coming from navigation module. The callback is represented with a delegete derivative function.
Finally the NaviHandler method is called with various navigation events such as EVENT_SPEED_EXCEEDING, passing the event details in its argument.

For more details please check ApplicationHandler.

In order to see all available events check {link:https://developers.sygic.com/reference/cs/html/namespace_application_a_p_i_a76f55de70c2b2dd91c699f4f7e1cfef1.html#a76f55de70c2b2dd91c699f4f7e1cfef1abdb70301b64f0d46a31a317e8c17a3ec}

Example

This example shows a definition of the callback object ApiCallback and an intialization of API with the given callback.
The initialization is called, as typical in Android, with a start of application at the OnCreate method.

int StartSygic()
{
    ...
    CApplicationAPI.ApplicationHandler AppHnd = new CApplicationAPI.ApplicationHandler(NaviHandler);
    ...
}

public static void NaviHandler(int nEventID, IntPtr strData)
{
    // process navigation events if needed
}

Background/Foreground

In Windows environment one can use the functions to put running navigation into background or foreground.
For more details please check BringApplicationToBackground and BringApplicationToForeground.

Example

This sample shows how to switch Sygic navigation to background and again to foreground.
The sample is presented with the toggle function, which does the switching back and forth, while it uses the global variable bgmode to maintain the state.

private bool bgmode = false;

void Toggle()
{
    if (bgmode)
    {
        SError err;
        CApplicationAPI.BringApplicationToForeground(out err, 0);
    }
    else
    {
        SError err;
        CApplicationAPI.BringApplicationToBackground(out err, 0);
    }
    bgmode = !bgmode;
}

Exit

Exiting is typically closing API and exiting Navigation.
In theory, one can close API and reopen it while keeping Navigation running, but it is quite rare.
For more details please check CloseApi and EndApplication.

Example

This sample shows typicall case for clsoing API and navigation with clicking exit Windows Form button.

        private void Form1_FormClosing(object sender, FormClosingEventArgs e)
        {
            SError err;
            CApplicationAPI.EndApplication(out err, 0);
            CApplicationAPI.CloseApi();
            Environment.Exit(0);
        }