Método ILocation::RegisterForReport (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 . ]

Solicita eventos de informe de ubicación.

Sintaxis

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

Parámetros

[in] pEvents

Puntero a la interfaz de devolución de llamada ILocationEvents a través de la cual se recibirán las notificaciones de eventos solicitadas.

[in] reportType

GUID que especifica el identificador de interfaz del tipo de informe para el que se van a recibir notificaciones de eventos.

[in] dwRequestedReportInterval

DWORD que especifica el tiempo transcurrido solicitado, en milisegundos, entre las notificaciones de eventos para el tipo de informe especificado. Si dwRequestedReportInterval es cero, no se especifica ningún intervalo mínimo y la aplicación solicita recibir eventos en el intervalo predeterminado del sensor de ubicación. Vea la sección Comentarios.

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.

Comentarios

El intervalo que solicita mediante el parámetro dwRequestedReportInterval representa la menor cantidad de tiempo entre eventos. Esto significa que solicita recibir notificaciones de eventos no con más frecuencia de lo especificado, pero el tiempo transcurrido puede ser significativamente más largo. Use el parámetro dwRequestedReportInterval para garantizar que las notificaciones de eventos no usen más recursos de procesador de los necesarios.

El proveedor de ubicación no es necesario para proporcionar informes en el intervalo que solicite. Llame a GetReportInterval para detectar la configuración del intervalo de informe verdadero.

Las aplicaciones que necesitan obtener datos de ubicación una sola vez, para rellenar un formulario o colocar la ubicación del usuario en un mapa, deben registrarse para eventos y esperar al primer evento de informe, tal como se describe en Waiting For a Location Report.

Ejemplos

En el ejemplo siguiente se llama a RegisterForReport para suscribirse a 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

Consulte también

ILocation

ILocationEvents