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.
A version of this page is also available for
4/8/2010

This function retrieves location information, including latitude and longitude, by setting the fields of the passed GPS_POSITIONstructure with location information that meets the specified maximum age criteria.

Syntax 

DWORD GPSGetPosition(
  HANDLE	
hGPSDevice,
  GPS_POSITION 
*pGPSPosition,
  DWORD		 
dwMaximumAge,
  DWORD		 
dwFlags
);

Parameters

hGPSDevice

Handle returned by a call to GPSOpenDevice, or NULL.

If NULL, the GPS Intermediate Driver returns cached location fix data that is within the dwMaximumAge, if available; otherwise, the dwValidFieldsof &pGPSPosition will contain zeroes on return.

pGPSPosition

Pointer to a GPS_POSITIONstructure. On return, this structure is filled with location data obtained by the GPS Intermediate Driver. The dwValidFields member of the GPS_POSITIONinstance specifies which fields of the instance are valid. This structure must be properly initialized, otherwise an error will be returned.

dwMaximumAge

Maximum age, in milliseconds, of location information. The GPS Intermediate Driver only returns information that has been received within the time specified by this parameter. Any information that is older than this age is not returned. The elements of the GPS_POSITIONinstance that are valid for the given dwMaximumAge value are specified in the dwValidFields element of the instance.

dwFlags

Reserved. Must be 0.

Return Value

If successful, returns ERROR_SUCCESS.

If unsuccessful, returns an error code.

Remarks

Applications call this function in three scenarios:

  1. an event passed in GPSOpenDevice, hNewLocationData parameter is signaled

  2. the application is in a polling loop, or

  3. a single time and then close the device using GPSCloseDevice.

GPSGetPositiondoes not query the GPS device directly to determine the current position. Instead, it will read the last position that the GPS device indicated to the GPS Intermediate Driver. The GPS device will indicate a position to the GPS Intermediate Driver in the background, independently of calls to GPSGetPosition.

Requirements

Header gpsapi.h
Library Gpsapi.lib
Windows Embedded CE Windows Embedded CE 6.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also