Using the GPS Intermediate Driver from Native Code

4/19/2010

The GPS Intermediate Driver is a software layer that sits between applications and the device driver for GPS hardware. This layer of abstraction allows applications to be written once and work with multiple GPS devices. The GPS Intermediate Driver API is exposed through a native code library. To access this library, include the header file "gpsapi.h" in your code and add "gpsapi.h" to the input of the linker for your project.

Opening the GPS Device

Before your application can access any GPS data, you must open the GPS device. This is done with the GPSOpenDevice function, which returns a handle to the GPS device.

HANDLE g_hGPSDevice;
…
g_hGPSDevice = GPSOpenDevice(NULL,NULL,NULL,0);

The device can be closed with the GPSCloseDevice function. Your application should allow the user to start and stop the device so that battery power is conserved when GPS data isn't needed.

The first two arguments to the GPSOpenDevice function are optional handles to Windows Embedded CE Events. If you use NULL for these parameters, you will need to poll the GPS device for the latest device status or location information. You can either do this periodically or in response to a user action. If you open the GPS device and supply the events in the call, the events will be triggered when updated information about the device state or updated location information are available. The following example shows the creation of these events.

HANDLE g_hGPSDevice;
HANDLE g_hGPSEvents
…
// Create the device state changed event
g_hGPSEvents[0]=CreateEvent(NULL,true,false,NULL);
// Create the position changed event
g_hGPSEvents[1]=CreateEvent(NULL,true,false,NULL);
g_hGPSDevice=GPSOpenDevice(g_hGPSEvents[0],g_hGPSEvents[1],NULL,0);

Then, in an event loop, you can use WaitForMultipleObjects to wait for the events to be triggered. When the events are triggered, you call your handler functions for the events.

Creating GPS Event Handlers

There are two different sets of data that you can obtain from the GPS Device through the GPS Intermediate Driver. These are device status information and location information. The following shows an example device status event handler.

VOID DeviceHandler(void)
{
    GPS_DEVICE gpsDevice;
    ZeroMemory(&gpsDevice,sizeof(GPS_DEVICE));
    gpsDevice.dwVersion=GPS_VERSION_1;
    gpsDevice.dwSize=sizeof(GPS_DEVICE);

    DWORD result=GPSGetDeviceState(&gpsDevice);
    if(result == ERROR_SUCCESS)
    {
        PCWSTR pszFormat=L"ServiceState: %d DeviceState: %d\0";
        StringCchPrintfW(g_pszDeviceStatus,g_cchDeviceStatus,pszFormat,gpsDevice.dwServiceState,gpsDevice.dwDeviceState);
}

The GPS_DEVICE structure is used to obtain the GPS device state information. This structure is passed to the GPSGetDeviceState function. You must set the dwVersion member to GPS_VERSION_1 and set the dwSize field to the size of the structure before you make the function call. The rest of this example function copies device state information into a global string variable which could then be displayed to the user.

A position handler should be defined to query the GPS device for the latest location information. The following is an example GPS location handler.

VOID PositionHandler(void)
{
    GPS_POSITION gpsPosition;
    ZeroMemory(&gpsPosition,sizeof(GPS_POSITION));
    gpsPosition.dwVersion=GPS_VERSION_1;
    gpsPosition.dwSize=sizeof(GPS_POSITION);
    
    DWORD result=GPSGetPosition(g_hGPSDevice,&gpsPosition,10000,0);
    if(result == ERROR_SUCCESS)
    {
        GPS_POSITION gpsPositionValid;
        ZeroMemory(&gpsPositionValid,sizeof(GPS_POSITION));

        if(gpsPosition.dwFlags & GPS_VALID_LATITUDE != 0)
          gpsPositionValid.dblLatitude=gpsPosition.dblLatitude;

        if(gpsPosition.dwFlags & GPS_VALID_LONGITUDE != 0)
          gpsPositionValid.dblLatitude=gpsPosition.dblLongitude;

        if(gpsPosition.dwFlags & GPS_VALID_UTC_TIME != 0)
          gpsPositionValid.stUTCTime=gpsPosition.stUTCTime;

        PCWSTR pszFormat=L"Time: %d:%d:%d\nLat: %f\nLong: %f\0";
        StringCchPrintfW(g_pszDeviceStatus,g_cchDeviceStatus,pszFormat,gpsPositionValid.stUTCTime.wHour,gpsPositionValid.stUTCTime.wMinute,gpsPositionValid.stUTCTime.wSecond,gpsPositionValid.dblLatitude,gpsPositionValid.dblLongitude);
}
}

In this example, the GPS_POSITION structure is used to retrieve position information through a call to GPSGetPosition. As with GPSGetDeviceState, you must set the dwVersion member to GPS_VERSION_1 and set the dwSize field to the size of the structure before calling GPSGetPosition.

When the function returns, it is possible that one or more members of the structure contain invalid data, because the GPS device may not have valid data for a particular parameter at any given time. There is a constant for each element of GPS data that can be returned. You can compare these constants to the dwFlags member of the returned GPS_POSITION structure to determine which elements of the GPS data are valid. The example above creates a second GPS_POSITION structure and copies the valid data into the new structure.

See Also

Concepts

Using the GPS Intermediate Driver from Managed Code

Other Resources

GPS Intermediate Driver