ILocation::GetReport method (locationapi.h)

Article
10/13/2021

[The Win32 Location API is available for use in the operating systems specified in the Requirements section. It may be altered or unavailable in subsequent versions. Instead, use the Windows.Devices.Geolocation API. ]

Retrieves a location report.

Syntax

HRESULT GetReport(
  [in]  REFIID          reportType,
  [out] ILocationReport **ppLocationReport
);

Parameters

[in] reportType

REFIID that specifies the type of report to retrieve.

[out] ppLocationReport

Address of a pointer to ILocationReport that receives the specified location report.

Return value

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code	Description
S_OK	The method succeeded.
E_ACCESSDENIED	The location provider has permissions disabled and report data cannot be retrieved.
HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED)	reportType is other than IID_ILatLongReport or IID_ICivicAddressReport.
HRESULT_FROM_WIN32(ERROR_NO_DATA)	No data is available. This may be due to an error or due to the provider being unavailable.
E_POINTER	ppLocationReport is NULL.
E_INVALIDARG	reportType is IID_ILatLongReport, and the latitude or longitude value is out of bounds.
E_FAIL	The underlying sensor is NULL or disconnected.
E_OUTOFMEMORY	Out of memory.

Remarks

ILocationReport is the base interface for specific location report types. Call QueryInterface to retrieve a pointer to the correct report type.

When GetReport is called, it may result in a notification being displayed in the taskbar, and a Location Activity event being logged in Event Viewer, if it is the application's first use of location.

Note When an application first starts, or when a new location sensor is enabled, GetReportStatus may report a status of REPORT_RUNNING shortly before the new location report is available. Therefore, an initial call to GetReport can return an error (ERROR_NO_DATA) or a value that is not from the expected location sensor, even if GetReportStatus indicates a status of REPORT_RUNNING. See GetReportStatus for a description of a workaround for this issue.

Examples

The following example calls GetReport for latitude/longitude reports and demonstrates how to call QueryInterface to retrieve a pointer to the specified report type.

CComPtr<ILocationReport> spLocationReport; // This is our location report object
CComPtr<ILatLongReport> spLatLongReport; // This is our LatLong report object

// Get the current latitude/longitude location report,
hr = spLocation->GetReport(IID_ILatLongReport, &spLocationReport);
// then get a pointer to the ILatLongReport interface by calling QueryInterface
if (SUCCEEDED(hr))
{
    hr = spLocationReport->QueryInterface(&spLatLongReport);
}

Requirements

Requirement	Value
Minimum supported client	Windows 7 [desktop apps only],Windows 7
Minimum supported server	None supported
Target Platform	Windows
Header	locationapi.h
DLL	LocationAPI.dll

Share via