Método ILocation::GetReportStatus (locationapi.h)

Artigo
08/24/2023

[A API de Localização do Win32 está disponível para uso nos sistemas operacionais especificados na seção Requisitos. Ele poderá ser alterado ou ficar indisponível em versões subsequentes. Em vez disso, use a API Windows.Devices.Geolocation . ]

Recupera o status para o tipo de relatório especificado.

Sintaxe

HRESULT GetReportStatus(
  [in]  REFIID                 reportType,
  [out] LOCATION_REPORT_STATUS *pStatus
);

Parâmetros

[in] reportType

REFIID que especifica o tipo de relatório para o qual obter o intervalo.

[out] pStatus

Endereço de um LOCATION_REPORT_STATUS que recebe a status atual para o relatório especificado.

Valor retornado

O método retorna um HRESULT. Os possíveis valores incluem, mas sem limitação, aqueles na tabela a seguir.

Código de retorno	Descrição
S_OK	O método foi bem-sucedido.
HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED)	reportType é diferente de IID_ILatLongReport ou IID_ICivicAddressReport.
E_INVALIDARG	pStatus é NULL.

Comentários

Esse método recupera status de relatório para novos relatórios. Os relatórios mais recentes permanecem disponíveis por meio de ILocation::GetReport, independentemente do status relatado por esse método.

Problemas conhecidos

Quando um aplicativo é iniciado pela primeira vez ou quando um novo sensor de localização está habilitado, GetReportStatus pode relatar uma status de REPORT_RUNNING pouco antes do relatório de localização estar disponível.

Portanto, uma chamada inicial para GetReport retornará um erro (ERROR_NO_DATA) ou um valor que não é do sensor de localização esperado, mesmo que GetReportStatus indique um status de REPORT_RUNNING. Isso pode ocorrer nos seguintes casos:

O aplicativo sonda status usando GetReportStatus até que um relatório status de REPORT_RUNNING seja retornado e, em seguida, chama GetReport.
GetReportStatus é chamado quando o aplicativo é iniciado. Isso pode ocorrer após a criação do objeto location ou depois de chamar RequestPermissions.

Um aplicativo pode atenuar o problema implementando a solução alternativa a seguir. A solução alternativa envolve assinar eventos de relatório de localização.

Solução alternativa: assinando eventos

O aplicativo pode assinar eventos de relatório e aguardar o relatório do evento OnLocationChanged ou do evento OnStatusChanged . O aplicativo deve aguardar um período de tempo finito especificado.

O exemplo a seguir mostra um aplicativo que aguarda um relatório de localização do tipo ILatLongReport. Se um relatório for recuperado com êxito dentro do tempo especificado, ele imprimirá uma mensagem indicando que os dados foram recebidos.

O código de exemplo a seguir demonstra como um aplicativo pode chamar uma função chamada WaitForLocationReport que registra eventos e aguarda o primeiro relatório de localização. WaitForLocationReport aguarda um evento definido por um objeto de retorno de chamada. A função WaitForLocationReport e o objeto de retorno de chamada são definidos nos exemplos que seguem 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;
}

O código de exemplo a seguir é separado em WaitForLocationReport.h e WaitForLocationReport.cpp. WaitForLocationReport.h contém o cabeçalho da função WaitForLocationReport . WaitForLocationReport.cpp contém a definição da função WaitForLocationReport e a definição do objeto de retorno de chamada que ele usa. O objeto de retorno de chamada fornece implementações dos métodos de retorno de chamada OnLocationChanged e OnStatusChanged . Dentro desses métodos, ele define um evento que sinaliza quando um relatório está disponível.

// 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 com suporte	Windows 7 [somente aplicativos da área de trabalho], Windows 7
Servidor mínimo com suporte	Nenhum compatível
Plataforma de Destino	Windows
Cabeçalho	locationapi.h
DLL	LocationAPI.dll

Confira também

ILocation

Compartilhar via

Método ILocation::GetReportStatus (locationapi.h)

Sintaxe

Parâmetros

Valor retornado

Comentários

Problemas conhecidos

Solução alternativa: assinando eventos

Requisitos

Confira também

Comentários

Recursos adicionais