Integrating with Garmin Mobile XT

Half a year ago, I wrote an article about Integrating with TomTom Navigator. This time I’m gonna discuss how you can integrate a .NET Compact Framework application with the Garmin Mobile XT navigation software. The process is a bit similar to integrating with TomTom because the Garmin SDK only provides a native API.

Before we get started, we need to have the Garmin Mobile XT for the Windows Mobile platform. Unlike TomTom’s SDK, Garmin’s SDK is available free of charge for download.

Before we can get more into detail, we will need the following:
1) Visual Studio 2005 or 2008
2) Windows Mobile 5.0 SDK for Pocket PC
3) A windows mobile device a GPS receiver and the Garmin Mobile XT (and Maps)
4) Garmin Mobile XT SDK for the Windows Mobile platform

We will be making the same projects we made for Integrating with TomTom Navigator:
1) Native wrapper for the Garmin XT SDK
2) Managed Garmin XT SDK wrapper
3) Device application that will call the Garmin XT SDK wrapper methods

Let’s get started…

Native wrapper for the Garmin XT SDK

The Garmin SDK ships with C++ header files and a static library that a native application can link to. For that reason we need to create a native DLL that exposes the methods that we need as C type funtions. Let’s call this Garmin.Native.dll.

In this article, we will implement a managed call to the Garmin Mobile XT to allow us to launch the Garmin Mobile XT, Navigate to a specific address or GPS coordinate, and to Show an address on the Map. These tasks will be performed on a native wrapper and which will be called from managed code.

We will be using the following methods from the Garmin Mobile XT SDK:
– QueLaunchApp
– QueAPIOpen
– QueAPIClose
– QueCreatePointFromAddress
– QueCreatePoint
– QueRouteToPoint
– QueViewPointOnMap

These methods return specific error codes describing whether the command executed successfully or not. This error information is translated to a .NET Framework enum which we will see later.

#include “QueAPI.h”

#define EXPORTC extern “C” __declspec(dllexport)

long DecimalDegreesToSemicircles(double degrees);

BOOL APIENTRY DllMain(
  HANDLE hModule,
  DWORD ul_reason_for_call,
  LPVOID lpReserved)
{
  switch (ul_reason_for_call)
  {
    case DLL_PROCESS_ATTACH:
    case DLL_THREAD_ATTACH:
    case DLL_THREAD_DETACH:
    case DLL_PROCESS_DETACH:
    break;
  }
  return TRUE;
}

static void QueCallback(QueNotificationT8 aNotification)
{
  // Used for debugging purposes
}

EXPORTC int CloseAPI()
{
  QueErrT16 err = QueAPIClose(QueCallback);
  return err;
}

EXPORTC int OpenNavigator()
{
  QueErrT16 err = QueLaunchApp(queAppMap);
  return err;
}

EXPORTC int NavigateToAddress(
  const wchar_t *streetAddress,
  const wchar_t *city,
  const wchar_t *postalCode,
  const wchar_t *state,
  const wchar_t *country)
{
  QueErrT16 err = QueAPIOpen(QueCallback);
  if (err != gpsErrNone) {
    return err;
  }

  QueSelectAddressType address;
  QuePointHandle point = queInvalidPointHandle;

  memset(&address, 0, sizeof(QueSelectAddressType));
  address.streetAddress = streetAddress;
  address.city = city;
  address.postalCode = postalCode;
  address.state = state;
  address.country = country;

  err = QueCreatePointFromAddress(&address, &point);
  if (err == queErrNone && point != queInvalidPointHandle) {
    err = QueRouteToPoint(point);
  }

  QueAPIClose(QueCallback);
  return err;
}

long DecimalDegreesToSemicircles(double degrees)
{
  return degrees * (0x80000000 / 180);
}

EXPORTC int NavigateToCoordinates(double latitude, double longitude)
{
  QueErrT16 err = QueAPIOpen(QueCallback);
  if (err != gpsErrNone) {
    return err;
  }

  QuePointType point;
  QuePositionDataType position;

  memset(&position, 0, sizeof(QuePositionDataType));
  position.lat = DecimalDegreesToSemicircles(latitude);
  position.lon = DecimalDegreesToSemicircles(longitude);

  memset(&point, 0, sizeof(QuePointType));
  point.posn = position;

  QuePointHandle hPoint;
  memset(&hPoint, 0, sizeof(QuePointHandle));

  err = QueCreatePoint(&point, &hPoint);
  if (err == queErrNone && hPoint != queInvalidPointHandle) {
    err = QueRouteToPoint(hPoint);
  }

  QueAPIClose(QueCallback);
  return err;
}

EXPORTC int ShowAddressOnMap(
  const wchar_t *streetAddress,
  const wchar_t *city,
  const wchar_t *postalCode,
  const wchar_t *state,
  const wchar_t *country)
{
  QueErrT16 err = QueAPIOpen(QueCallback);
  if (err != gpsErrNone) {
    return err;
  }

  QueSelectAddressType address;
  QuePointHandle point = queInvalidPointHandle;

  memset(&address, 0, sizeof(QueSelectAddressType));
  address.streetAddress = streetAddress;
  address.city = city;
  address.postalCode = postalCode;
  address.state = state;
  address.country = country;

  err = QueCreatePointFromAddress(&address, &point);
  if (err == queErrNone && point != queInvalidPointHandle) {
    err = QueViewPointOnMap(point);
  }

  QueAPIClose(QueCallback);
  return err;
}

The Garmin Mobile XT SDK works in a straight forward way. Before making any calls to the API, you first need to Open it. Once open, you can start executing a series of methods and then once you’re done you must Close the API. The Garmin Mobile XT has to be running before you can execute commands to it, otherwise you will get a communication error.

You might notice in the code above an empty static method called QueCallback(QueNotificationT8 aNotification). This is a callback method that receives the information about the application state. You can use this for making callbacks from native to managed code. You can pass a delegate method from managed code to the native methods that expect QueNotificationCallback as a parameter. We will only use it for debugging purposes in this example. We will not dig more into that in this article.

Normally when reverse geocoding an address to a GPS coordinates using some free service, you will get the coordinates in decimal degrees (WGS84 decimal format). Navigating to a coordinate using the Garmin Mobile XT SDK requires the coordinates to be in semicircles (2^31 semicircles equals 180 degrees).

To convert decimal degrees to semicircles we use the following formula:
semicircles = decimal degrees * (2^31 / 180)

Managed wrapper

In my article Integrating with TomTom Navigator, I created a Generic Navigator wrapper that uses the INavigator interface for defining methods to be used by the managed wrapper. The purpose of the Generic Navigator was to allow the application to integrate with several navigation solutions without changing any of the existing code. As I already discussed this in the past, I will skip this part and only focus on how to integrate with Garmin Mobile XT.

We first need to create an enumeration containing error codes we receive from the native wrapper.

public enum GarminErrorCodes : int
{
  None = 0,
  NotOpen = 1,
  InvalidParameter,
  OutOfMemory,
  NoData,
  AlreadyOpen,
  InvalidVersion,
  CommunicationError,
  CmndUnavailable,
  LibraryStillOpen,
  GeneralFailure,
  Cancelled,
  RelaunchNeeded
}

We of course need to create our P/Invoke declarations. This time let’s put them in an internal class called NativeMethods()

internal class NativeMethods
{
  [DllImport(“Garmin.Native.dll”)]
  internal static extern int CloseAPI();

  [DllImport(“Garmin.Native.dll”)]
  internal static extern int OpenNavigator();

  [DllImport(“Garmin.Native.dll”)]
  internal static extern int NavigateToAddress(
    string address,
    string city,
    string postalcode,
    string state,
    string country);

  [DllImport(“Garmin.Native.dll”)]
  internal static extern int NavigateToCoordinates(
    double latitude,
    double longitude);

  [DllImport(“Garmin.Native.dll”)]
  internal static extern int ShowAddressOnMap(
    string address,
    string city,
    string postalcode,
    string state,
    string country);
}

Let’s create a .NET exception that we can throw which contains native error details when a native method call fails. Let’s call it GarminNativeException()

[Serializable]
public class GarminNativeException : Exception
{
  public GarminNativeException() { }

  public GarminNativeException(GarminErrorCodes native_error) { }

  public GarminNativeException(
    string message,
    GarminErrorCodes native_error) : base(message) { }
}

Now we need a class that we can use for calling the wrapped managed methods to the Garmin mobile XT. Let’s call it GarminXT()

public class GarminXT : IDisposable
{
  public void Dispose()
  {
    NativeMethods.CloseAPI();
  }

  public void OpenNavigator()
  {
    GarminErrorCodes err = (GarminErrorCodes)NativeMethods.OpenNavigator();

    if (err != GarminErrorCodes.None) {
      ThrowGarminException(err);
    }
  }

  public void NavigateToAddress(
    string address,
    string city,
    string postalcode,
    string state,
    string country)
  {
    GarminErrorCodes err = (GarminErrorCodes)NativeMethods.NavigateToAddress(
      address,
      city,
      postalcode,
      state,
      country);

    if (err != GarminErrorCodes.None) {
      ThrowGarminException(err);
    }
  }

  public void NavigateToCoordinates(double latitude, double longitude)
  {
    GarminErrorCodes err = (GarminErrorCodes)NativeMethods.NavigateToCoordinates(
      latitude,
      longitude);

    if (err != GarminErrorCodes.None) {
      ThrowGarminException(err);
    }
  }

  public void ShowAddressOnMap(
    string address,
    string city,
    string postalcode,
    string state,
    string country)
  {
    GarminErrorCodes err = (GarminErrorCodes)NativeMethods.ShowAddressOnMap(
      address,
      city,
      postalcode,
      state,
      country);

    if (err != GarminErrorCodes.None) {
      ThrowGarminException(err);
    }
  }

  private GarminNativeException ThrowGarminException(GarminErrorCodes err)
  {
    string message = string.Empty;

    switch (err) {
      case GarminErrorCodes.NotOpen:
        message = “Close() called without having Open() first”;
        break;
      case GarminErrorCodes.InvalidParameter:
        message = “Invalid parameter was passed to the function”;
        break;
      case GarminErrorCodes.OutOfMemory:
        message = “Out of Memory”;
        break;
      case GarminErrorCodes.NoData:
        message = “No Data Available”;
        break;
      case GarminErrorCodes.AlreadyOpen:
        message = “The API is already open”;
        break;
      case GarminErrorCodes.InvalidVersion:
        message = “The API is an incompatible version”;
        break;
      case GarminErrorCodes.CommunicationError:
        message = “There was an error communicating with the API”;
        break;
      case GarminErrorCodes.CmndUnavailable:
        message = “Command is unavailable”;
        break;
      case GarminErrorCodes.LibraryStillOpen:
        message = “API is still open”;
        break;
      case GarminErrorCodes.GeneralFailure:
        message = “General Failure”;
        break;
      case GarminErrorCodes.Cancelled:
        message = “Action was cancelled by the user”;
        break;
      case GarminErrorCodes.RelaunchNeeded:
        message = “Relaunch needed to load the libraries”;
        break;
      default:
        break;
    }

    throw new GarminNativeException(message, err);
  }
}

The managed wrapper GarminXT() implements IDisposible for ensuring that the API will be closed when the GarminXT object gets disposed. I check the return code of every method to verify if the native method call succeeded or failed. If the native method call failed then I throw a GarminNativeException containing a text description of the error and the GarminErrorCode returned by the native method call.

Using the Managed Wrapper

Now that we have a managed wrapper for the Garmin Mobile XT SDK we can start testing it with a simple smart device application. Let’s say that we created a simple application that accepts street address, city, postal code, country, latitude, longitude. We also have some buttons or menu items for: Navigating to an address, Navigating to coordinates, Showing an address on the map, and for launching Garmin Mobile XT.

Since the managed wrapper implements IDisposable, we surround our calls to it with the using statement:

using (GarminXT xt = new GarminXT()) {
  xt.OpenNavigator();
}

As I mentioned before, it is important that Garmin Mobile XT is running in the background for executing certain commands. Otherwise the managed Garmin XT wrapper will throw a GarminNativeException saying that there was an error communicating with the API. I would suggest handling the GarminNativeException everytime calls to the managed wrapper are made.

For launching Garmin Mobile XT:

try {
  using (GarminXT xt = new GarminXT()) {
    xt.OpenNavigator();
  }
}
catch (GarminNativeException ex) {
  Debug.Assert(false, ex.Message, ex.StackTrace);
}

For navigating to an address:

try {
  using (GarminXT xt = new GarminXT()) {
    xt.NavigateToAddress(
      “Hørkær 24”,
      “Herlev”,
      “2730”,
      null,
      “Denmark”);
  }
}
catch (GarminNativeException ex) {
  Debug.Assert(false, ex.Message, ex.StackTrace);
}

For navigating to coordinates:

try {
  using (GarminXT xt = new GarminXT()) {
    xt.NavigateToCoordinates(
      55.43019,
      12.26075);
  }
}
catch (GarminNativeException ex) {
  Debug.Assert(false, ex.Message, ex.StackTrace);
}

For showing an address on the map:

try {
  using (GarminXT xt = new GarminXT()) {
    xt.ShowAddressOnMap(
      “Hørkær 24”,
      “Herlev”,
      “2730”,
      null,
      “Denmark”);
  }
}
catch (GarminNativeException ex) {
  Debug.Assert(false, ex.Message, ex.StackTrace);
}

That wasn’t that hard was it?

But there is one thing that I don’t quite understand. Why do we have to wrap SDK’s like this ourselves? Why don’t they just provide managed SDK’s? Hopefully this will change in the near future. Until then, I guess I can just write a few more articles about it.

Transparent Controls in .NETCF

I work a lot with a graphic artist for developing solutions. The better the graphic artist you work with is, the harder it is to implement their designs to your application. One thing that my solutions have in common is that they all require transparent controls. My graphic artist loves having a image buttons on top of fancy background.

Here’s some screen shots of what I’ve made with my graphic artist:

In these screen shots I heavily use a transparent label control over a Form that has a background image. I normally set my controls to be designer visible so I can drag and drop while designing. Visual Studio 2005 and 2008 will automatically load all Custom Controls and UserControls

Implementing Transparent Controls

For creating transparent controls, I need the following:

1) IControlBackground interface – contains BackgroundImage { get; }
2) TransparentControlBase – draws the BackgroundImage of an IControlBackground form
3) Transparent Control – Inherits from TransparentControlBase
4) FormBase Form – implements IControlBackground and draws the background image to the form

Let’s start off with the IControlBackground interface. Like I mentioned above, it only contains a property called BackgroundImage.

public interface IControlBackground
{
  Image BackgroundImage { get; }
}

Next we will need to create the TransparentControlBase. Let’s create a class that inherits from Control. We then need to override the OnPaintBackground() event to draw the IControlBackground.BackgroundImage of the Parent control. To do this, we create an instance of IControlBackground from the Parent. Once we have the BackgroundImage, we draw part of the BackgroundImage where the transparent control is lying on.

We also override the OnTextChanged() and OnParentChanged() events to force a re-draw whenever the text or parent of the control is changed.

public class TransparentControlBase : Control
{
  protected bool HasBackground = false;

  protected override void OnPaintBackground(PaintEventArgs e)
  {
    IControlBackground form = Parent as IControlBackground;
    if (form == null) {
      base.OnPaintBackground(e);
      return;
    } else {
      HasBackground = true;
    }

    e.Graphics.DrawImage(
      form.BackgroundImage,
      0,
      0,
      Bounds,
      GraphicsUnit.Pixel);
  }

  protected override void OnTextChanged(EventArgs e)
  {
    base.OnTextChanged(e);
    Invalidate();
  }

  protected override void OnParentChanged(EventArgs e)
  {
    base.OnParentChanged(e);
    Invalidate();
  }
}

Now we need to create a control that inherits from TransparentControlBase. I’ll create a simple TransparentLabel control for this example. The control will have the same behavior as the standard Label control, except that it can be transparent when used over a form or control that implements IControlBackground.

public class TransparentLabel : TransparentControlBase
{
  ContentAlignment alignment = ContentAlignment.TopLeft;
  StringFormat format = null;
  Bitmap off_screen = null;

  public TransparentLabel()
  {
    format = new StringFormat();
  }

  public ContentAlignment TextAlign
  {
    get { return alignment; }
    set
    {
      alignment = value;
      switch (alignment) {
        case ContentAlignment.TopCenter:
          format.Alignment = StringAlignment.Center;
          format.LineAlignment = StringAlignment.Center;
          break;
        case ContentAlignment.TopLeft:
          format.Alignment = StringAlignment.Near;
          format.LineAlignment = StringAlignment.Near;
          break;
        case ContentAlignment.TopRight:
          format.Alignment = StringAlignment.Far;
          format.LineAlignment = StringAlignment.Far;
          break;
      }
    }
  }

  protected override void OnPaint(PaintEventArgs e)
  {
    if (!base.HasBackground) {
      if (off_screen == null) {
        off_screen = new Bitmap(ClientSize.Width, ClientSize.Height);
      }
      using (Graphics g = Graphics.FromImage(off_screen)) {
        using (SolidBrush brush = new SolidBrush(Parent.BackColor)) {
          g.Clear(BackColor);
          g.FillRectangle(brush, ClientRectangle);
        }
      }
    } else {
      using (SolidBrush brush = new SolidBrush(ForeColor)) {
        e.Graphics.DrawString(
          Text,
          Font,
          brush,
          new Rectangle(0, 0, Width, Height),
          format);
      }
    }
  }
}

Now that we have our transparent controls, we need to create a Form that will contain these controls. First we need to create a base class that will implement IControlBackground and inherit from Form.

In this example, I added a background image to the solution and as an embedded resource. My default namespace is called TransparentSample and my background image is located at the root folder with the filename background.jpg

public class FormBase : Form, IControlBackground
{
  Bitmap background;

  public FormBase()
  {
    background = new Bitmap(
      Assembly.GetExecutingAssembly().GetManifestResourceStream(
      “TransparentSample.background.jpg”));
  }

  protected override void OnPaint(PaintEventArgs e)
  {
    e.Graphics.DrawImage(background, 0, 0);
  }

  public Image BackgroundImage
  {
    get { return background; }
  }
}

For the last step, we need to create a Form that will contain these transparent controls. To start, let’s add a new Form to our project and let it inherit from FormBase instead of Form.

Now we can add our transparent controls to the main form.

public class MainForm : FormBase
{
  TransparentLabel label;

  public MainForm()
  {
    label = new TransparentLabel();
    label.Font = new Font(“Arial”, 16f, FontStyle.Bold);
    label.ForeColor = Color.White;
    label.Text = “Transparent Label”;
    label.Bounds = new Rectangle(20, 60, 200, 50);
    Controls.Add(label);
  }
}

That wasn’t very complicated, was it? Having a nice and intuitive UI offers a very good user experience. Being creative, imaginative, and learning to work with a graphic artist can really pay off.

Displaying the Calendar view on a DateTimePicker Control in .NETCF

I’ve recently made a solution where the customer requested to be able to bring up the calendar view in a DateTimePicker control by pressing on a specific button on the screen. The solution to that was really simple: Create a control that inherits from System.Windows.Forms.DateTimePicker and add a method called ShowCalendar() which I call to bring up the Calendar view.

public class DateTimePickerEx : DateTimePicker
{
  [DllImport(“coredll.dll”)]
  static extern int SendMessage(
    IntPtr hWnd, uint uMsg, int wParam, int lParam);

  const int WM_LBUTTONDOWN = 0x0201;

  public void ShowCalendar() {
    int x = Width – 10;
    int y = Height / 2;
    int lParam = x + y * 0x00010000;

    SendMessage(Handle, WM_LBUTTONDOWN, 1, lParam);
  }
}

Retrieving the Icon Image within the System Image List in .NETCF 2.0

Here’s a nice trick for retrieving the icon image of a file or folder from the system image list. All we actually need is to P/Invoke SHGetFileInfo and use Icon.FromHandle() to get the Icon.

First, we need to declare our P/Invokes.

[StructLayout(LayoutKind.Sequential)]
struct SHFILEINFO
{
  public IntPtr hIcon;
  public IntPtr iIcon;
  public uint dwAttributes;
  [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 260)]
  public string szDisplayName;
  [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 80)]
  public string szTypeName;
}

const uint SHGFI_ICON = 0x000000100;
const uint SHGFI_LARGEICON = 0x000000000;
const uint SHGFI_SMALLICON = 0x000000001;
const uint SHGFI_SELECTICON = 0x000040000;

[DllImport(“coredll.dll”)]
static extern IntPtr SHGetFileInfo(string pszPath, uint dwFileAttributes,
  ref SHFILEINFO psfi, uint cbSizeFileInfo, uint uFlags);

To get an instance of System.Drawing.Icon for the small icon of a file

Icon GetSystemIconSmall(string file)
{
  SHFILEINFO shinfo = new SHFILEINFO();
  IntPtr i = SHGetFileInfo(file, 0, ref shinfo,
    (uint)Marshal.SizeOf(shinfo), SHGFI_ICON | SHGFI_SMALLICON);

  return Icon.FromHandle(shinfo.hIcon);
}

For the large icon of a file

Icon GetSystemIconLarge(string file)
{
  SHFILEINFO shinfo = new SHFILEINFO();
  IntPtr i = SHGetFileInfo(file, 0, ref shinfo,
    (uint)Marshal.SizeOf(shinfo), SHGFI_ICON | SHGFI_LARGEICON);

  return Icon.FromHandle(shinfo.hIcon);
}

For the small icon of a file when it is selected

Icon GetSystemIconSmallSelected(string file)
{
  SHFILEINFO shinfo = new SHFILEINFO();
  IntPtr i = SHGetFileInfo(file, 0, ref shinfo,
    (uint)Marshal.SizeOf(shinfo), SHGFI_ICON | SHGFI_SMALLICON | SHGFI_SELECTICON);

  return Icon.FromHandle(shinfo.hIcon);
}

And last for the large icon of a file when it is selected

Icon GetSystemIconLargeSelected(string file)
{
  SHFILEINFO shinfo = new SHFILEINFO();
  IntPtr i = SHGetFileInfo(file, 0, ref shinfo,
    (uint)Marshal.SizeOf(shinfo), SHGFI_ICON | SHGFI_LARGEICON | SHGFI_SELECTICON);

  return Icon.FromHandle(shinfo.hIcon);
}

Ok, now how is this helpful? Well if you want to implement a File Explorer-ish control, then wouldn’t have to include Icons and other images in your application. You can just use the icons in the system image list

Logging Unhandled Exceptions

Bugs are sometimes unavoidable. They’re best caught during the development or testing phase. There might be some cases where the developer forgot to handle possible exceptions in a function. It could be possible that this exception isn’t handled anywhere at all. But even so, it is still possible to catch this exception. To do this we handle the UnhandledException event of the current AppDomain. We should do this in our static void Main() before calling Application.Run([Main Form])

Here’s a small snippet to accomplish this task.

[C# CODE]

static void Main()
{
  AppDomain.CurrentDomain.UnhandledException +=
    new UnhandledExceptionEventHandler(CurrentDomain_UnhandledException);
  Application.Run(new MainForm());
}

static void CurrentDomain_UnhandledException(object sender, UnhandledExceptionEventArgs e)
{
  Exception exception = (Exception)e.ExceptionObject;
  if (exception != null) {
    Error.Append(exception.Message, exception.StackTrace);
  }
}

Now we need a mechanism for saving to a Error log file. Let’s create a simple class called Error() and add a function called Append(string message, string stacktrace)

[C# CODE]

public class Error
{
  internal static void Append(string message, string stacktrace)
  {
    string file = string.Format(“{0}\Errors.txt”,
      Path.GetDirectoryName(Assembly.GetExecutingAssembly().GetName().CodeBase));
    if (File.Exists(file)) {
      FileInfo fi = new FileInfo(file);
      if (fi.Length > 100 * 1024) {
        fi.Delete();
      }
    }
    StreamWriter sw = new StreamWriter(file, true, Encoding.UTF8);
    sw.WriteLine(string.Format(
      “-=-=-=-=-=–=-=-n{0}nMESSAGE:n{1}nSTACK TRACE:n{3}n”,
        DateTime.Now, message, stacktrace));
    sw.Close();
    }
  }
}

The Error() class should be put in a namespace that is accessible throughout the application. This will be very helpful tool for finding those nasty almost impossible to reproduce bugs.

Integrating with TomTom Navigator

PDA’s are used for pretty much everything these days. From the bunch of devices the I work (play) with, I took a great liking to devices that have built in GPS receivers. These devices are usually bundled with really cool navigation software from various vendors. Some of these navigation software have SDK’s that you can buy separately. By using these SDK’s, you can fully integrate navigation features to your mobile solutions.

In this article, I would like to discuss how to integrate a .NET Compact Framework application with TomTom Navigator. I will also demonstrate an example of making a generic navigator wrapper so your application is not just bound to one kind of navigation software.

Before we get started, we need to have the TomTom Navigator SDK. Unfortunately this is not free, but can be easily purchased from the TomTom Pro website.

Before we dig into more detail, let’s go through our software requirements. We need the following:

    1. Visual Studio 2005
    2. Windows Mobile 5.0 SDK for Pocket PC
    3. A device running Windows Mobile 5.0 with TomTom Navigator 5 installed
    4. The TomTom Navigator SDK
    5. ActiveSync 4.2 or higher (for Vista, the Mobile Device Center)

Now, Lets get started…

Here is what we need to make:

    1. native wrapper for the TomTom SDK (native dll)
    2. generic navigator wrapper in .NET CF
    3. managed TomTom wrapper
    4. device application that will call TomTom SDK wrapper methods

Sounds pretty simple doesn’t it?

1. Native Wrapper for the TomTom SDK

We will first need a little help from native code to access the TomTom SDK. We cannot access the TomTom SDK directly from .NET due to the architecture of the SDK. We have to wrap around the TomTom SDK C++ classes and methods and expose them as C type functions.

In your native wrapper, lets say we want to wrap the following TomTom SDK functions:
  – GetApplicationVersion(TError* err, TVersion* ver)
  – FlashMessage(TError* err, char* msg, int ms)
  – NavigateToAddress(TError* aError, char* aCity, char* aStreet, char* aHouseNr, char* aPostcode)

[C++ CODE]

#include “sdkconstants.h”
#include “TomTomAPI.h”
#include “TomTomGoFileLayer.h”

#define CLIENT_NAME “client”

CTomTomAPI::TError err;
int res = 0;

BOOL APIENTRY DllMain(
  HANDLE hModule, DWORD ul_reason_for_call, LPVOID lpReserved )
{
  switch (ul_reason_for_call)
  {
  case DLL_PROCESS_ATTACH:
  case DLL_THREAD_ATTACH:
  case DLL_THREAD_DETACH:
  case DLL_PROCESS_DETACH:
    break;
  }
  return TRUE;
}

extern “C” __declspec(dllexport) int TTN_GetApplicationVersion(
  int* iError, LPTSTR szVersion, int *iBuildNumber )
{
  MTomTomCommunicationLayerInterface *comms =
    DEFAULT_TRANSPORTATION_LAYER(CLIENT_NAME,2005,TOMTOM_TCPIP_PORT);

  CTomTomAPI api(*comms);
  CTomTomAPI::TVersion version;
  res = api.GetApplicationVersion(&err, &version);
  *iError = err.iError;

  TCHAR str[16];
  _stprintf(str, TEXT(“%S”), version.iVersion);
  lstrcpy( szVersion, (LPTSTR)str );
  *iBuildNumber = version.iBuildNumber;

  delete comms;
  return res;
}

extern “C” __declspec(dllexport) int TTN_FlashMessage(
   int* iError, char* aMessage, int aMilliSeconds )
{
  char message[256];
  sprintf(message, “%S”, aMessage);

  MTomTomCommunicationLayerInterface *comms =
    DEFAULT_TRANSPORTATION_LAYER(CLIENT_NAME,2005,TOMTOM_TCPIP_PORT);

  CTomTomAPI api(*comms);
  res = api.FlashMessage(&err, message, aMilliSeconds);
  *iError = err.iError;

  delete comms;
  return res;
}

extern “C” __declspec(dllexport) int TTN_NavigateToAddress(
   int* iError, char* aCity, char* aStreet, char* aHouseNr, char* aPostcode )
{
  char city[256];
  char street[256];
  char houseNr[16];
  char postcode[32];

  sprintf(city, “%S”, aCity);
  sprintf(street, “%S”, aStreet);
  sprintf(houseNr, “%S”, aHouseNr);
  sprintf(postcode, “%S”, aPostcode);

  MTomTomCommunicationLayerInterface *comms =
    DEFAULT_TRANSPORTATION_LAYER(CLIENT_NAME,2005,TOMTOM_TCPIP_PORT);

  CTomTomAPI api(*comms);
  res = api.NavigateToAddress(&err, city, street, houseNr, postcode);
  *iError = err.iError;

  delete comms;
  return res;
}

Let’s set the output of the project to be called TTSDK.dll

2. Generic Navigator Wrapper in .NET CF

Once we’ve gotten our native wrapper up and running, we create a generic navigator wrapper. We start off by creating a smart device class library project. Once the project is created, add the following classes: INavigator.cs, Navigator.cs, and Common.cs

Lets go and define the common objects we want to use in Common.cs

[C# CODE]

public struct NVersion {
  string Version;
  int BuildNumber;
}

INavigator.cs will be an interface defining the how the wrapper will look like. Lets add methods for the 3 TomTom SDK methods we want to use.

[C# CODE]

public interface INavigator
{
  NVersion GetApplicationVersion();
  void FlashMessage(string text, int duration);
  void NavigateToAddress(string city, string street, string houseno, string zipcode);
}

Navigator.cs will be the class your application will call. This will load the managed TomTom wrapper as an instance of INavigator. Navigator itself will implement INavigator and will return calls from the TomTom wrapper.

[C# CODE]

public class Navigator : INavigator
{
  private INavigator instance;

  public Navigator(string typeName)
  {
    Type type = Type.GetType(typeName);
    if (type == null) {
      throw new TypeLoadException();
    } else {
      instance = (INavigator)Activator.CreateInstance(type);
      if (instance == null) {
        throw new TypeLoadException();
      }
    }
  }

  public TVersion GetApplicationVersion()
  {
    return instance.GetApplicationVersion();
  }

  public void FlashMessage(string text, int duration)
  {
    instance.FlashMessage(text, duration);
  }

  public void NavigateToAddress(string city, string street, string houseno, string zipcode)
  {
    instance.NavigateToAddress(city, street, houseno, zipcode);
  }
}

The default constructor for Navigator accepts a type name. The format for type name is “[Namespace].[ClassName], [AssemblyName]”

3. Managed TomTom Wrapper

Here we create a new smart device class library. Once the project is created, add a reference to the generic navigator wrapper since we will implement the INavigator interface and add a class called TomTom.cs

Lets implement TomTom.cs as INavigator

[C# CODE]

[DllImport(“TTSDK.dll”, EntryPoint=”TTN_GetApplicationVersion”)]
internal static extern int TTN_GetApplicationVersion(
  ref int iError, StringBuilder szVersion, ref int iBuildNumber);

[DllImport(“TTSDK.dll”, EntryPoint=”TTN_FlashMessage”)]
internal static extern int TTN_FlashMessage(
  ref int iError, string aMessage, int aMilliseconds);

[DllImport(“TTSDK.dll”, EntryPoint=”TTN_NavigateToAddress”)]
internal static extern int TTN_NavigateToAddress(
  ref int iError, string aCity, string aStreet, string aHouseNo, string aPostcode);

public void FlashMessage(string aMessage, int aMilliseconds)
{
  if (0 != TTN_FlashMessage(ref iError, aMessage, aMilliseconds)) {
    throw new InvalidOperationException();
  }
}

public NVersion GetApplicationVersion()
{
  NVersion version = new TVersion();
  StringBuilder szVersion = new StringBuilder();
  int iBuildNumber = 0;
  int iError = 0;

  if (0 != TTN_GetApplicationVersion(ref iError, szVersion, ref iBuildNumber)) {
    throw new InvalidOperationException();
  } else {
    version.iVersion = szVersion.ToString();
    version.iBuildNumber = iBuildNumber;
  }
}

public void NavigateToAddress(string sCity, string sStreet, string sHouseNo, string sPostcode)
{
  int iError = 0;

  if (0 != TTN_NavigateToAddress(ref iError, sCity, sStreet, sHouseNo, sPostcode)) {
    throw new InvalidOperationException();
  }
}

Now our TomTom wrapper is pretty much ready

4. Device Application

In our application, we want to integrate with TomTom Navigator for navigating to a specific address. The address can could be retrieved from a web service, or stored in your pocket outlook. For this article, we’re going to retrieve address information of a customer from Pocket Outlook.

In order to do this, we will need the Windows Mobile 5.0 SDK for Pocket PC to be installed. Let’s start off by creating a Windows Mobile 5.0 device application project. Once the project is created, add a reference to the Navigator wrapper and the TomTom wrapper. Next we have to build the Native wrapper project, and add the output file TTSDK.dll to our project. Set TTSDK.dll to be “Copied if Newer”. To retrieve address information from contacts, we must add a reference to Microsoft.WindowsMobile.PocketOutlook.dll.

Once the references and files are in place, we can start adding some code to Form1.cs. No need to change the name of the main form since this is only a small demo. We need to have a control that can contain the contacts, lets use the ComboBox control for now. Add a ComboBox control to the form and call it cbContacts. Lets add a “Navigate to” button to the form as well and call it btnNavigate.

To retrieve a list of contacts we need to create a global instance of Microsoft.WindowsMobile.PocketOutlook.OutlookSession and Microsoft.WindowsMobile.PocketOutlook.ContactsCollection, once we instantiate our OutlookSession, we can then retrieve a list of Contacts through OutlookSession.Contacts.Items.

To communicate with TomTom, we create an instance of Navigator(). The default constructor for Navigator will need a typeName for loading the TomTom wrapper as INavigator. It would be a smart idea to store the typeName in a seperate file, text or xml would be perfect. Once again, we do this so that if we want our application to integrate with different navigation software, we don’t have to re-write everything. In this demo, the typeName will just be a hard coded string constant.

[C# CODE]

private Microsoft.WindowsMobile.PocketOutlook.OutlookSession session;
private Microsoft.WindowsMobile.PocketOutlook.ContactsCollection contacts;

private const string TYPENAME=”[The namespace].[The class name], [The assembly name]”;
private Navigator navigator;

public Form1()
{
  InitializeComponent();

  btnNavigate.Click += new EventHandler(btnNavigate_Click);
  Closing += new CancelEventHandler(Form1_Closing);

  navigator = new Navigator(TYPENAME);

  string restriction = “[BusinessAddressStreet] <> ” ” OR [HomeAddressStreet] <> ” “”;
  session = new OutlookSession();
  contacts = session.Contacts.Items.Restrict(restriction);
  cbContacts.DataSource = contacts;
}

private void Form1_Closing(object sender, CancelEventArgs e)
{
  contacts.Dispose();
  contacts = null;

  session.Dispose();
  session = null;
}

private void btnNavigate_Click(object sender, EventArgs e)
{
  Contact contact = cbContacts.SelectedItem as Contact;
  navigator.FlashMessage(“Navigating…”, 1500);
  navigator.NavigateToAddress(contact.BusinessAddressCity,
    contact.BusinessAddressStreet,
    “PARSE THE HOUSE NUMBER…”,
    contact.BusinessAddressPostalCode);
}

When the application launches, your pocket outlook contacts that have a valid address will be loaded into our ComboBox control. Let’s select an item in the ComboBox. Once you click on the Navigate button it will launch TomTom Navigator and display the message “Navigating” for 1.5 seconds, after that it will start calculating the route from your current location to your destination (in this case, the selected contact).

That wasn’t too hard was it?

Programmatically Minimize an Application in .NET CF 2.0

I once made a solution that runs on full screen. The solution was written completely in managed code (except for the CE Setup and other small stuff..). Since I took over the screen completely, I don’t have access to the (X) button in the upper right corner of the screen. I wanted the application running at all times, but I also wanted the user to be able to get in and out of the application. Since the user won’t be able to access the Start button, I added a “Close” button to my application. This “Close” button won’t exit the application, instead it will just Minimize the application.

In the .NET Compact Framework 2.0, you can’t just set the form’s WindowState to WindowState.Minimized since the WindowState enum only contains Normal and Maximized. Currently, the only way you can programmatically minimize an application is by doing a P/Invoke to ShowWindow and passing SW_MINIMIZE to specify how the window will be displayed. It is also required that your Form has the Taskbar visible, this is done by setting the following properties:

  FormBorderStyle = FormBorderStyle.FixedDialog;
  WindowState = FormWindowState.Normal;
  ControlBox = true;
  MinimizeBox = true;
  MaximizeBox = true;

Here’s a small code snippet of how to minimize your application

[DllImport(“coredll.dll”)]
static extern int ShowWindow(IntPtr hWnd, int nCmdShow);

const int SW_MINIMIZED = 6;

void Minimize() {
  // The Taskbar must be enabled to be able to do a Smart Minimize
  this.FormBorderStyle = FormBorderStyle.FixedDialog;
  this.WindowState = FormWindowState.Normal;
  this.ControlBox = true;
  this.MinimizeBox = true;
  this.MaximizeBox = true;

  // Since there is no WindowState.Minimize, we have to P/Invoke ShowWindow
  ShowWindow(this.Handle, SW_MINIMIZED);
}

Programmatically Refreshing the Today Screen

A simple trick for forcing the today screen to re-read from the registry (or refresh) is by sending the message WM_WININICHANGE with the parameter 0x000000F2 to a window called the DesktopExplorerWindow.

Here’s a small code snippet on how to accomplish this programmatically:

void RefreshTodayScreen() {
  HWND hWnd = FindWindow(_T(“DesktopExplorerWindow”), _T(“Desktop”));
  SendMessage(hWnd, WM_WININICHANGE, 0x000000F2, 0);
}

and in managed code…

[DllImport(“coredll.dll”)]
static extern IntPtr FindWindow(string class_name, string caption);

[DllImport(“coredll.dll”)]
static extern int SendMessage(IntPtr hWnd, uint Msg, int wParam, int lParam);

const uint WM_WININICHANGE = 0x1a;

void RefreshTodayScreen() {
  IntPtr hWnd = FindWindow(“DesktopExplorerWindow”, “Desktop”);
  SendMessage(hWnd, WM_WININICHANGE, 0x000000F2, 0);
}

Scroll to top