Overall Parsed Data Code Structure
A version of this page is also available for
4/8/2010
Code that uses the GPS Intermediate Driver parsed API often has a common overall structure, with the following steps:
Create a mechanism for receiving notifications by creating one or two Windows Embedded CE events, by calling CreateEvent. These events are signaled when the GPS hardware delivers new data or when the state of the GPS hardware changes. This step is common, but optional; you only need to create events if you want to receive notifications of new data or device state changes.
Create a connection to the GPS hardware, via the GPS Intermediate Driver, by calling GPSOpenDevice. This function returns a handle you use to call other parsed API functions. If you created events for notification in step 1, pass these events when you call GPSOpenDevice.
Wait until the GPS hardware has location data to provide or until it changes state, by calling WaitForMultipleObjects (if you have two events) or WaitForSingleObject (if you have only one event).
When one of these events is signaled, retrieve location or device information.
To retrieve location information, call GPSGetPosition. This function fills the passed GPS_POSITION structure with location information, including latitude and longitude. This call does not block if the GPS Intermediate Driver does not have valid data. If there is no valid data, the dwValidFields field of the GPS_POSITION structure contains zero, which indicates that no fields contain valid data.
Alternatively, retrieve information about the device, by calling GPSGetDeviceState.Repeat step 3 until you don't need additional GPS information.
Close the connection to the GPS Intermediate Driver, by calling GPSCloseDevice.
Note
GPS hardware consumes relatively large amounts of power. Therefore, it is very important that you call GPSCloseDevice as soon as possible when you no longer need information from the GPS hardware. For more information about the implications of not closing the connection, see GPS Intermediate Driver Power Management.
If you do not pass events to GPSOpenDevice, you won't receive notifications when new data exists or when the device's state changes, but you can still call GPSGetPosition and GPSGetDeviceState whenever your application needs location or device information.
You can call GPSGetPosition without a handle retrieved using GPSOpenDevice. In this case, the GPS Intermediate Driver returns location information it has that meets the maximum age constraint you provided in your GPSGetPosition call. This can be useful in cases where you can use existing information, but don't want to take the time to initialize the GPS hardware or consume power driving the GPS hardware. If there is no location information that meets the specified time constraint, the GPS Intermediate Driver still returns a GPS_POSITION structure, but one where the dwValidFields member is zero, and where the structure doesn't contain any information.