Método ILocation::GetReportStatus (locationapi.h)
[La API de ubicación de Win32 está disponible para su uso en los sistemas operativos especificados en la sección Requisitos. En versiones posteriores podría modificarse o no estar disponible. En su lugar, use la API Windows.Devices.Geolocation . ]
Recupera el estado del tipo de informe especificado.
Sintaxis
HRESULT GetReportStatus(
[in] REFIID reportType,
[out] LOCATION_REPORT_STATUS *pStatus
);
Parámetros
[in] reportType
REFIID que especifica el tipo de informe para el que se va a obtener el intervalo.
[out] pStatus
Dirección de un LOCATION_REPORT_STATUS que recibe el estado actual del informe especificado.
Valor devuelto
El método devuelve un valor HRESULT. Entre los valores posibles se incluyen los que se indican en la tabla siguiente, entre otros.
| Código devuelto | Descripción |
|---|---|
|
El método se ha llevado a cabo de forma correcta. |
|
reportType es distinto de IID_ILatLongReport o IID_ICivicAddressReport. |
|
pStatus es NULL. |
Comentarios
Este método recupera el estado del informe para los nuevos informes. Los informes más recientes siguen estando disponibles a través de ILocation::GetReport, independientemente del estado notificado por este método.
Problemas conocidos
Cuando se inicia por primera vez una aplicación o cuando se habilita un nuevo sensor de ubicación, GetReportStatus puede notificar un estado de REPORT_RUNNING poco antes de que el informe de ubicación esté disponible.Por lo tanto, una llamada inicial a GetReport devolverá un error (ERROR_NO_DATA) o un valor que no procede del sensor de ubicación esperado, aunque GetReportStatus indique un estado de REPORT_RUNNING. Esto puede ocurrir en los siguientes casos:
- La aplicación sondea el estado mediante GetReportStatus hasta que se devuelve un estado de informe de REPORT_RUNNING y, a continuación, llama a GetReport.
- Se llama a GetReportStatus cuando se inicia la aplicación. Esto puede producirse después de la creación del objeto location o después de llamar a RequestPermissions.
Una aplicación puede mitigar el problema mediante la implementación de la siguiente solución alternativa. La solución alternativa implica suscribirse a eventos de informe de ubicación.
Solución alternativa: Suscribirse a eventos
La aplicación puede suscribirse a eventos de informe y esperar al informe desde el evento OnLocationChanged o el evento OnStatusChanged . La aplicación debe esperar una cantidad de tiempo finita especificada.En el ejemplo siguiente se muestra una aplicación que espera un informe de ubicación de tipo ILatLongReport. Si un informe se recupera correctamente dentro del período de tiempo especificado, imprime un mensaje que indica que se recibieron los datos.
En el código de ejemplo siguiente se muestra cómo una aplicación puede llamar a una función denominada WaitForLocationReport que se registra para eventos y espera al primer informe de ubicación. WaitForLocationReport espera un evento establecido por un objeto de devolución de llamada. La función WaitForLocationReport y el objeto de devolución de llamada se definen en los ejemplos que siguen a este.
// main.cpp
// An application that demonstrates how to wait for a location report.
// This sample waits for latitude/longitude reports but can be modified
// to wait for civic address reports by replacing IID_ILatLongReport
// with IID_ICivicAddressReport in the following code.
#include "WaitForLocationReport.h"
#define DEFAULT_WAIT_FOR_LOCATION_REPORT 500 // Wait for half a second.
int wmain()
{
// You may use the flags COINIT_MULTITHREADED | COINIT_DISABLE_OLE1DDE
// to specify the multi-threaded concurrency model.
HRESULT hr = ::CoInitializeEx(NULL,
COINIT_APARTMENTTHREADED | COINIT_DISABLE_OLE1DDE);
if (SUCCEEDED(hr))
{
int args;
PWSTR *pszArgList = ::CommandLineToArgvW(::GetCommandLineW(), &args);
DWORD const dwTimeToWait =
(2 == args) ? static_cast<DWORD>(_wtoi(pszArgList[1])) : DEFAULT_WAIT_FOR_LOCATION_REPORT;
::LocalFree(pszArgList);
wprintf_s(L"Wait time set to %lu\n", dwTimeToWait);
ILocation *pLocation; // This is the main Location interface.
hr = CoCreateInstance(CLSID_Location, NULL, CLSCTX_INPROC, IID_PPV_ARGS(&pLocation));
if (SUCCEEDED(hr))
{
// Array of report types to listen for.
// Replace IID_ILatLongReport with IID_ICivicAddressReport
// for civic address reports.
IID REPORT_TYPES[] = { IID_ILatLongReport };
// Request permissions for this user account to receive location data for all the
// types defined in REPORT_TYPES (which is currently just one report)
// TRUE means a synchronous request.
if (FAILED(pLocation->RequestPermissions(NULL, REPORT_TYPES, ARRAYSIZE(REPORT_TYPES), TRUE)))
{
wprintf_s(L"Warning: Unable to request permissions.\n");
}
ILocationReport *pLocationReport; // This is our location report object
// Replace IID_ILatLongReport with IID_ICivicAddressReport for civic address reports
hr = ::WaitForLocationReport(pLocation, IID_ILatLongReport, dwTimeToWait, &pLocationReport);
if (SUCCEEDED(hr))
{
wprintf_s(L"Successfully received data via GetReport().\n");
pLocationReport->Release();
}
else if (RPC_S_CALLPENDING == hr)
{
wprintf_s(L"No LatLong data received. Wait time of %lu elapsed.\n", dwTimeToWait);
}
pLocation->Release();
}
::CoUninitialize();
}
return 0;
}
El código de ejemplo siguiente se divide en WaitForLocationReport.h y WaitForLocationReport.cpp. WaitForLocationReport.h contiene el encabezado de la función WaitForLocationReport . WaitForLocationReport.cpp contiene la definición de la función WaitForLocationReport y la definición del objeto de devolución de llamada que usa. El objeto de devolución de llamada proporciona implementaciones de los métodos de devolución de llamada OnLocationChanged y OnStatusChanged . Dentro de estos métodos, establece un evento que indica cuándo un informe está disponible.
// WaitForLocationReport.h
// Header for the declaration of the WaitForLocationReport function.
#pragma once
#include <windows.h>
#include <LocationApi.h>
#include <wchar.h>
HRESULT WaitForLocationReport(
ILocation* pLocation, // Location object.
REFIID reportType, // Type of report.
DWORD dwTimeToWait, // Milliseconds to wait.
ILocationReport** ppLocationReport // Receives the location report.
);
// WaitForLocationReport.cpp
// Contains definitions of the WaitForLocationReport function and
// the callback object that it uses.
#include "WaitForLocationReport.h"
#include <shlwapi.h>
#include <new>
// Implementation of the callback interface that receives location reports.
class CLocationCallback : public ILocationEvents
{
public:
CLocationCallback() : _cRef(1), _hDataEvent(::CreateEvent(
NULL, // Default security attributes.
FALSE, // Auto-reset event.
FALSE, // Initial state is nonsignaled.
NULL)) // No event name.
{
}
virtual ~CLocationCallback()
{
if (_hDataEvent)
{
::CloseHandle(_hDataEvent);
}
}
IFACEMETHODIMP QueryInterface(REFIID riid, void **ppv)
{
if ((riid == IID_IUnknown) ||
(riid == IID_ILocationEvents))
{
*ppv = static_cast<ILocationEvents*>(this);
}
else
{
*ppv = NULL;
return E_NOINTERFACE;
}
AddRef();
return S_OK;
}
IFACEMETHODIMP_(ULONG) AddRef()
{
return InterlockedIncrement(&_cRef);
}
IFACEMETHODIMP_(ULONG) Release()
{
long cRef = InterlockedDecrement(&_cRef);
if (!cRef)
{
delete this;
}
return cRef;
}
// ILocationEvents
// This is called when there is a new location report.
IFACEMETHODIMP OnLocationChanged(REFIID /*reportType*/, ILocationReport* /*pLocationReport*/)
{
::SetEvent(_hDataEvent);
return S_OK;
}
// This is called when the status of a report type changes.
// The LOCATION_REPORT_STATUS enumeration is defined in LocApi.h in the SDK
IFACEMETHODIMP OnStatusChanged(REFIID /*reportType*/, LOCATION_REPORT_STATUS status)
{
if (REPORT_RUNNING == status)
{
::SetEvent(_hDataEvent);
}
return S_OK;
}
HANDLE GetEventHandle()
{
return _hDataEvent;
}
private:
long _cRef;
HANDLE _hDataEvent; // Data Event Handle
};
// Waits to receive a location report.
// This function waits for the callback object to signal when
// a report event or status event occurs, and then calls GetReport.
// Even if no report event or status event is received before the timeout,
// this function still queries for the last known report by calling GetReport.
// The last known report may be cached data from a location sensor that is not
// reporting events, or data from the default location provider.
//
// Returns S_OK if the location report has been returned
// or RPC_S_CALLPENDING if the timeout expired.
HRESULT WaitForLocationReport(
ILocation* pLocation, // Location object.
REFIID reportType, // Type of report to wait for.
DWORD dwTimeToWait, // Milliseconds to wait.
ILocationReport **ppLocationReport // Receives the location report.
)
{
*ppLocationReport = NULL;
CLocationCallback *pLocationCallback = new(std::nothrow) CLocationCallback();
HRESULT hr = pLocationCallback ? S_OK : E_OUTOFMEMORY;
if (SUCCEEDED(hr))
{
HANDLE hEvent = pLocationCallback->GetEventHandle();
hr = hEvent ? S_OK : E_FAIL;
if (SUCCEEDED(hr))
{
// Tell the Location API that we want to register for a report.
hr = pLocation->RegisterForReport(pLocationCallback, reportType, 0);
if (SUCCEEDED(hr))
{
DWORD dwIndex;
HRESULT hrWait = CoWaitForMultipleHandles(0, dwTimeToWait, 1, &hEvent, &dwIndex);
if ((S_OK == hrWait) || (RPC_S_CALLPENDING == hrWait))
{
// Even if there is a timeout indicated by RPC_S_CALLPENDING
// attempt to query the report to return the last known report.
hr = pLocation->GetReport(reportType, ppLocationReport);
if (FAILED(hr) && (RPC_S_CALLPENDING == hrWait))
{
// Override hr error if the request timed out and
// no data is available from the last known report.
hr = hrWait; // RPC_S_CALLPENDING
}
}
// Unregister from reports from the Location API.
pLocation->UnregisterForReport(reportType);
}
}
pLocationCallback->Release();
}
return hr;
}
Requisitos
| Cliente mínimo compatible | Windows 7 [solo aplicaciones de escritorio],Windows 7 |
| Servidor mínimo compatible | No se admite ninguno |
| Plataforma de destino | Windows |
| Encabezado | locationapi.h |
| Archivo DLL | LocationAPI.dll |