Metodo ILocation::RegisterForReport (locationapi.h)

[L'API Location Win32 è disponibile per l'uso nei sistemi operativi specificati nella sezione Requisiti. È possibile che in versioni successive sia stata modificata o non sia più disponibile. Usare invece l'API Windows.Devices.Geolocation . ]

Richiede eventi del report sulla posizione.

Sintassi

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

Parametri

[in] pEvents

Puntatore all'interfaccia di callback ILocationEvents tramite cui verranno ricevute le notifiche degli eventi richieste.

[in] reportType

GUID che specifica l'ID interfaccia del tipo di report per cui ricevere le notifiche degli eventi.

[in] dwRequestedReportInterval

DWORD che specifica il tempo trascorso richiesto, in millisecondi, tra le notifiche degli eventi per il tipo di report specificato. Se dwRequestedReportInterval è zero, non viene specificato alcun intervallo minimo e l'applicazione richiede di ricevere eventi all'intervallo predefinito del sensore di posizione. Vedere la sezione Osservazioni.

Valore restituito

Il metodo restituisce un valore HRESULT. I valori possibili includono, ma non sono limitati a, quelli indicati nella tabella seguente.

Codice restituito	Descrizione
S_OK	Il metodo è riuscito.
HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED)	reportType è diverso da IID_ILatLongReport o IID_ICivicAddressReport.
HRESULT_FROM_WIN32(ERROR_ALREADY_REGISTERED)	reportType è già registrato.

Commenti

L'intervallo richiesto tramite il parametro dwRequestedReportInterval rappresenta la quantità di tempo più breve tra gli eventi. Ciò significa che si richiede di ricevere notifiche degli eventi non più frequentemente di quanto specificato, ma il tempo trascorso potrebbe essere notevolmente più lungo. Usare il parametro dwRequestedReportInterval per garantire che le notifiche degli eventi non usino più risorse del processore rispetto alle esigenze.

Il provider di percorsi non è necessario per fornire report a intervalli richiesti. Chiamare GetReportInterval per individuare l'impostazione dell'intervallo di report reale.

Le applicazioni che devono ottenere i dati sulla posizione una sola volta, per compilare una maschera o inserire la posizione dell'utente in una mappa, devono registrarsi per gli eventi e attendere il primo evento del report, come descritto in Waiting For a Location Report.

Esempio

Nell'esempio seguente viene chiamato RegisterForReport per sottoscrivere gli eventi.

#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;
}

Requisiti

Requisito	Valore
Client minimo supportato	Windows 7 [solo app desktop],Windows 7
Server minimo supportato	Nessuno supportato
Piattaforma di destinazione	Windows
Intestazione	locationapi.h
DLL	LocationAPI.dll

Vedi anche

ILocation

ILocationEvents