Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
4/14/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 GPSOpenDevicefunction, which returns a handle to the GPS device.

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

The device can be closed with the GPSCloseDevicefunction. 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 GPSOpenDevicefunction 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.

Copy Code 
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 WaitForMultipleObjectsto 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.

Copy Code 
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_DEVICEstructure is used to obtain the GPS device state information. This structure is passed to the GPSGetDeviceStatefunction. You must set the dwVersionmember to GPS_VERSION_1and set the dwSizefield 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.

Copy Code 
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_POSITIONstructure is used to retrieve position information through a call to GPSGetPosition. As with GPSGetDeviceState, you must set the dwVersionmember to GPS_VERSION_1and set the dwSizefield 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 dwFlagsmember of the returned GPS_POSITIONstructure to determine which elements of the GPS data are valid. The example above creates a second GPS_POSITIONstructure and copies the valid data into the new structure.

See Also