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

[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 . ]

Solicita eventos de relatório de localização.

Sintaxe

HRESULT RegisterForReport(
  [in] ILocationEvents *pEvents,
  [in] REFIID          reportType,
  [in] DWORD           dwRequestedReportInterval
);

Parâmetros

[in] pEvents

Ponteiro para a interface de retorno de chamada ILocationEvents por meio da qual as notificações de evento solicitadas serão recebidas.

[in] reportType

GUID que especifica a ID da interface do tipo de relatório para o qual receber notificações de evento.

[in] dwRequestedReportInterval

DWORD que especifica o tempo decorrido solicitado, em milissegundos, entre notificações de evento para o tipo de relatório especificado. Se dwRequestedReportInterval for zero, nenhum intervalo mínimo será especificado e seu aplicativo solicitará o recebimento de eventos no intervalo padrão do sensor de localização. Consulte Observações.

Valor retornado

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

Comentários

O intervalo solicitado usando o parâmetro dwRequestedReportInterval representa a menor quantidade de tempo entre os eventos. Isso significa que você solicita receber notificações de evento não com mais frequência do que o especificado, mas o tempo decorrido pode ser significativamente maior. Use o parâmetro dwRequestedReportInterval para ajudar a garantir que as notificações de evento não usem mais recursos de processador do que o necessário.

O provedor de localização não é necessário para fornecer relatórios no intervalo solicitado. Chame GetReportInterval para descobrir a configuração de intervalo de relatório verdadeiro.

Os aplicativos que precisam obter dados de localização apenas uma vez, para preencher um formulário ou colocar a localização do usuário em um mapa, devem se registrar para eventos e aguardar o primeiro evento de relatório, conforme descrito em Aguardando um Relatório de Localização.

Exemplos

O exemplo a seguir chama RegisterForReport para assinar eventos.

#include <windows.h>
#include <atlbase.h>
#include <atlcom.h>
#include <LocationApi.h> // This is the main Location API header
#include "LocationCallback.h" // This is our callback interface that receives Location reports.

class CInitializeATL : public CAtlExeModuleT<CInitializeATL>{};
CInitializeATL g_InitializeATL; // Initializes ATL for this application. This also does CoInitialize for us

int wmain()
{
    HRESULT hr = CoInitializeEx(NULL, COINIT_MULTITHREADED | COINIT_DISABLE_OLE1DDE);;
    if (SUCCEEDED(hr))
    {
        CComPtr<ILocation> spLocation; // This is the main Location interface
        CComObject<CLocationEvents>* pLocationEvents = NULL; // This is our callback object for location reports
        IID REPORT_TYPES[] = { IID_ILatLongReport }; // Array of report types of interest. Other ones include IID_ICivicAddressReport

        hr = spLocation.CoCreateInstance(CLSID_Location); // Create the Location object

        if (SUCCEEDED(hr))
        {
            hr = CComObject<CLocationEvents>::CreateInstance(&pLocationEvents); // Create the callback object
            if (NULL != pLocationEvents)
            {
                pLocationEvents->AddRef();
            }
        }

        if (SUCCEEDED(hr))
        {
            // Request permissions for this user account to receive location data for all the
            // types defined in REPORT_TYPES (which is currently just one report)
            if (FAILED(spLocation->RequestPermissions(NULL, REPORT_TYPES, ARRAYSIZE(REPORT_TYPES), FALSE))) // FALSE means an asynchronous request
            {
                wprintf(L"Warning: Unable to request permissions.\n");
            }

            // Tell the Location API that we want to register for reports (which is currently just one report)
            for (DWORD index = 0; index < ARRAYSIZE(REPORT_TYPES); index++)
            {
                hr = spLocation->RegisterForReport(pLocationEvents, REPORT_TYPES[index], 0);
            }
        }

        if (SUCCEEDED(hr))
        {
            // Wait until user presses a key to exit app. During this time the Location API
            // will send reports to our callback interface on another thread.
            system("pause");

            // Unregister from reports from the Location API
            for (DWORD index = 0; index < ARRAYSIZE(REPORT_TYPES); index++)
            {
                spLocation->UnregisterForReport(REPORT_TYPES[index]);
            }
        }

        // Cleanup
        if (NULL != pLocationEvents)
        {
            pLocationEvents->Release();
            pLocationEvents = NULL;
        }

        CoUninitialize();
    }

    return 0;
}

Requisitos

Confira também

ILocation

ILocationEvents