Méthode ILocation::GetReportStatus (locationapi.h)
[L’API d’emplacement Win32 est disponible pour une utilisation dans les systèmes d’exploitation spécifiés dans la section Configuration requise. Il sera peut-être modifié ou indisponible dans les versions ultérieures. Utilisez plutôt l’API Windows.Devices.Geolocation . ]
Récupère le status pour le type de rapport spécifié.
Syntaxe
HRESULT GetReportStatus(
[in] REFIID reportType,
[out] LOCATION_REPORT_STATUS *pStatus
);
Paramètres
[in] reportType
REFIID qui spécifie le type de rapport pour lequel obtenir l’intervalle.
[out] pStatus
Adresse d’un LOCATION_REPORT_STATUS qui reçoit le status actuel pour le rapport spécifié.
Valeur retournée
Cette méthode retourne un code HRESULT. Les valeurs possibles sont notamment celles figurant dans le tableau suivant.
| Code de retour | Description |
|---|---|
|
S_OK |
|
reportType n’est pas IID_ILatLongReport ou IID_ICivicAddressReport. |
|
pStatus a la valeur NULL. |
Notes
Cette méthode récupère les status de rapport pour les nouveaux rapports. Les rapports les plus récents restent disponibles via ILocation::GetReport, quelle que soit la status signalée par cette méthode.
Problèmes connus
Lorsqu’une application démarre pour la première fois ou lorsqu’un nouveau capteur d’emplacement est activé, GetReportStatus peut signaler une status de REPORT_RUNNING peu de temps avant que le rapport d’emplacement ne soit disponible.Par conséquent, un appel initial à GetReport retourne une erreur (ERROR_NO_DATA) ou une valeur qui ne provient pas du capteur d’emplacement attendu, même si GetReportStatus indique une status de REPORT_RUNNING. Cela peut se produire dans les cas suivants :
- L’application interroge les status à l’aide de GetReportStatus jusqu’à ce qu’un rapport status de REPORT_RUNNING soit retourné, puis appelle GetReport.
- GetReportStatus est appelé au démarrage de l’application. Cela peut se produire après la création de l’objet location ou après l’appel de RequestPermissions.
Une application peut atténuer le problème en implémentant la solution de contournement suivante. La solution de contournement implique l’abonnement aux événements de rapport d’emplacement.
Solution de contournement : Abonnement aux événements
L’application peut s’abonner aux événements de rapport et attendre le rapport de l’événement OnLocationChanged ou de l’événement OnStatusChanged . L’application doit attendre une durée limitée spécifiée.L’exemple suivant montre une application qui attend un rapport d’emplacement de type ILatLongReport. Si un rapport est récupéré avec succès dans le délai spécifié, il imprime un message indiquant que les données ont été reçues.
L’exemple de code suivant montre comment une application peut appeler une fonction nommée WaitForLocationReport qui s’inscrit pour les événements et attend le premier rapport d’emplacement. WaitForLocationReport attend un événement défini par un objet de rappel. La fonction WaitForLocationReport et l’objet de rappel sont définis dans les exemples qui suivent celui-ci.
// 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;
}
L’exemple de code suivant est séparé en WaitForLocationReport.h et WaitForLocationReport.cpp. WaitForLocationReport.h contient l’en-tête de la fonction WaitForLocationReport . WaitForLocationReport.cpp contient la définition de la fonction WaitForLocationReport et la définition de l’objet de rappel qu’il utilise. L’objet de rappel fournit des implémentations des méthodes de rappel OnLocationChanged et OnStatusChanged . Dans ces méthodes, il définit un événement qui signale quand un rapport 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;
}
Spécifications
| Client minimal pris en charge | Windows 7 [applications de bureau uniquement],Windows 7 |
| Serveur minimal pris en charge | Aucun pris en charge |
| Plateforme cible | Windows |
| En-tête | locationapi.h |
| DLL | LocationAPI.dll |