ILocation::RegisterForReport-Methode (locationapi.h)

[Die Win32-Standort-API ist für die Verwendung in den Betriebssystemen verfügbar, die im Abschnitt Anforderungen angegeben sind. Es kann in nachfolgenden Versionen geändert oder entfernt werden. Verwenden Sie stattdessen die Windows.Devices.Geolocation-API . ]

Fordert Standortberichtsereignisse an.

Syntax

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

Parameter

[in] pEvents

Zeiger auf die ILocationEvents-Rückrufschnittstelle , über die die angeforderten Ereignisbenachrichtigungen empfangen werden.

[in] reportType

GUID , die die Schnittstellen-ID des Berichtstyps angibt, für den Ereignisbenachrichtigungen empfangen werden sollen.

[in] dwRequestedReportInterval

DWORD , das die angeforderte verstrichene Zeit (in Millisekunden) zwischen Ereignisbenachrichtigungen für den angegebenen Berichtstyp angibt. Wenn dwRequestedReportInterval null ist, wird kein Mindestintervall angegeben, und Ihre Anwendung fordert den Empfang von Ereignissen im Standardintervall des Standortsensors an. Siehe Hinweise.

Rückgabewert

Die Methode gibt ein HRESULT zurück. Mögliches Werte (aber nicht die Einzigen) sind die in der folgenden Tabelle.

Rückgabecode	BESCHREIBUNG
S_OK	Die Methode wurde erfolgreich ausgeführt.
HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED)	reportType ist nicht IID_ILatLongReport oder IID_ICivicAddressReport.
HRESULT_FROM_WIN32(ERROR_ALREADY_REGISTERED)	reportType ist bereits registriert.

Hinweise

Das Intervall, das Sie mithilfe des dwRequestedReportInterval-Parameters anfordern, stellt die kürzeste Zeitspanne zwischen Ereignissen dar. Dies bedeutet, dass Sie den Empfang von Ereignisbenachrichtigungen nicht häufiger als angegeben anfordern, aber die verstrichene Zeit kann erheblich länger sein. Verwenden Sie den dwRequestedReportInterval-Parameter , um sicherzustellen, dass Ereignisbenachrichtigungen nicht mehr Prozessorressourcen als erforderlich verwenden.

Der Standortanbieter muss keine Berichte in dem von Ihnen angeforderten Intervall bereitstellen. Rufen Sie GetReportInterval auf, um die richtige Berichtsintervalleinstellung zu ermitteln.

Anwendungen, die nur einmal Standortdaten abrufen müssen, um ein Formular auszufüllen oder den Standort des Benutzers auf einer Karte zu platzieren, sollten sich für Ereignisse registrieren und auf das erste Berichtsereignis warten, wie unter Warten auf einen Standortbericht beschrieben.

Beispiele

Im folgenden Beispiel wird RegisterForReport aufgerufen, um Ereignisse zu abonnieren.

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

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 7 [nur Desktop-Apps],Windows 7
Unterstützte Mindestversion (Server)	Nicht unterstützt
Zielplattform	Windows
Kopfzeile	locationapi.h
DLL	LocationAPI.dll

Weitere Informationen

ILocation

ILocationEvents