LocationGetReport

Other versions of this page are also available for the following:

• Windows Embedded CE 6.0 R3

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

See Also

Reference

Location Framework Functions
LocationOpen