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

[L’API d’emplacement Win32 est disponible pour une utilisation dans les systèmes d’exploitation spécifiés dans la section Configuration requise. Il sera peut-être modifié ou indisponible dans les versions ultérieures. Utilisez plutôt l’API Windows.Devices.Geolocation . ]

Demande des événements de rapport d’emplacement.

Syntaxe

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

Paramètres

[in] pEvents

Pointeur vers l’interface de rappel ILocationEvents via laquelle les notifications d’événements demandées seront reçues.

[in] reportType

GUID qui spécifie l’ID d’interface du type de rapport pour lequel recevoir des notifications d’événement.

[in] dwRequestedReportInterval

DWORD qui spécifie le temps écoulé demandé, en millisecondes, entre les notifications d’événements pour le type de rapport spécifié. Si dwRequestedReportInterval est égal à zéro, aucun intervalle minimal n’est spécifié et votre application demande de recevoir des événements à l’intervalle par défaut du capteur d’emplacement. Consultez la section Notes.

Valeur de retour

Cette méthode retourne un code HRESULT. Les valeurs possibles sont notamment celles figurant dans le tableau suivant.

Code de retour	Description
S_OK	S_OK
HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED)	reportType n’est pas IID_ILatLongReport ou IID_ICivicAddressReport.
HRESULT_FROM_WIN32(ERROR_ALREADY_REGISTERED)	reportType est déjà inscrit.

Remarques

L’intervalle que vous demandez à l’aide du paramètre dwRequestedReportInterval représente la durée la plus courte entre les événements. Cela signifie que vous demandez à recevoir des notifications d’événements pas plus fréquemment que spécifié, mais que le temps écoulé peut être considérablement plus long. Utilisez le paramètre dwRequestedReportInterval pour vous assurer que les notifications d’événements n’utilisent pas plus de ressources de processeur que nécessaire.

Le fournisseur d’emplacement n’est pas tenu de fournir des rapports à l’intervalle que vous demandez. Appelez GetReportInterval pour découvrir le paramètre d’intervalle de rapport réel.

Les applications qui n’ont besoin d’obtenir des données de localisation qu’une seule fois, pour remplir un formulaire ou placer l’emplacement de l’utilisateur sur une carte, doivent s’inscrire aux événements et attendre le premier événement de rapport, comme décrit dans En attente d’un rapport de localisation.

Exemples

L’exemple suivant appelle RegisterForReport pour s’abonner aux événements.

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

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 7 [applications de bureau uniquement],Windows 7
Serveur minimal pris en charge	Aucun pris en charge
Plateforme cible	Windows
En-tête	locationapi.h
DLL	LocationAPI.dll

Voir aussi

ILocation

ILocationEvents