Share via

LocationGetReport (Windows Embedded CE 6.0)

  • Article

1/6/2010

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