LocationGetReport
Other versions of this page are also available for the following:
.gif "A hyphen indicates that the information in this topic is not relevant for this platform, or that the platform does not support the API that is listed.")
.gif "A checkmark indicates that the information in this topic is relevant for this platform, and that any API listed is also supported on this platform.")
8/28/2008
This function indicates that an application wants the Location Framework to retrieve the report requested.
Syntax
DWORD LocationGetReport(
HLOCATION hLocation,
REFGUID reportType,
DWORD maximumAge,
LOCATION_REPORT* pLocationReport,
DWORD* pcbLocationReport,
DWORD flags
);
Parameters
- hLocation
A handle to the Location Framework returned from a call to LocationOpen.
- reportType
GUID specifying the report type for the retrieve information.
- maximumAge
Maximum age, in milliseconds, of location information. The Location Framework 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.
- pLocationReport
Pointer to a LOCATION_REPORT structure. The representation and size of this structure will vary according to the report type specified.
- pcbLocationReport
Pointer to the size of pLocationReport on input, and the size of the structure required on output..
- flags
Reserved. Must be 0.
Return Value
If successful, returns ERROR_SUCCESS.
If unsuccessful, returns an error code.
This is a table of error codes:
| Error Codes | Meaning |
|---|---|
ERROR_INVALID_PARAMATER |
One or more of the parameters is not valid |
ERROR_DEV_NOT_EXIST |
There is no plugin on the system that can generate the specified report type. |
ERROR_NO_DATA |
Since the startup of the Location Framework service, no plugin has generated the specified report type. |
ERROR_TIMEOUT |
Location Report concerning the report type is available, but it is greater then maximumAge milliseconds old. |
ERROR_INSUFFICIENT_BUFFER |
The size of the buffer passed in pcbLocationReport is not valid. |
Remarks
On almost all Windows Embedded CE 6.0 Platforms, maximumAge is only accurate to 1000ms. A smaller granularity should not be assumed.
Applications may call LocationGetReport for any report type, and not just ones that they have registered with LocationRegisterForReport. Because the Location Framework caches the last report a plugin generates for each report type, this allows for optimizing battery in some conditions. Imagine for instance an application that needs location information either opportunistically – so that it will perform without location data, but will perform slightly better with it – and at the same time it does not want to consume battery power to retrieve the position. This application could call LocationGetReport and attempt to get a position if one was available without forcing the position to be retrieved.
Some applications may have more tolerance for timing delays. An application that displayed local weather, for instance, may be willing to accept a report if it is less than ten minutes old. This application could call LocationGetReport with an appropriately high maximum age and only call LocationRegisterForReportif there was no information available.
Requirements
| Header | lfapi.h |
| Library | lfapi.lib |
| Windows Embedded CE | Windows Embedded CE 6.0 and later |