Метод ILocation::RegisterForReport (locationapi.h)

[API расположения Win32 доступен для использования в операционных системах, указанных в разделе Требования. В последующих версиях он может быть изменен или недоступен. Вместо этого используйте API Windows.Devices.Geolocation . ]

Запрашивает события отчета о расположении.

Синтаксис

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

Параметры

[in] pEvents

Указатель на интерфейс обратного вызова ILocationEvents , через который будут получены запрошенные уведомления о событиях.

[in] reportType

GUID , указывающий идентификатор интерфейса для типа отчета, для которого будут получаться уведомления о событиях.

[in] dwRequestedReportInterval

DWORD , указывающий запрошенное затраченное время (в миллисекундах) между уведомлениями о событиях для указанного типа отчета. Если параметр dwRequestedReportInterval равен нулю, минимальный интервал не указан, и приложение запрашивает получение событий в интервале по умолчанию датчика расположения. См. заметки.

Возвращаемое значение

Метод возвращает HRESULT. Допустимые значения включают, но не ограничиваются, значения, приведенные в следующей таблице.

Код возврата	Описание
S_OK	Метод выполнен успешно.
HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED)	параметр reportType отличается от IID_ILatLongReport или IID_ICivicAddressReport.
HRESULT_FROM_WIN32(ERROR_ALREADY_REGISTERED)	reportType уже зарегистрирован.

Комментарии

Интервал, запрашиваемый с помощью параметра dwRequestedReportInterval , представляет собой кратчайший промежуток времени между событиями. Это означает, что вы запрашиваете уведомления о событиях не чаще, чем указано, но затраченное время может быть значительно больше. Используйте параметр dwRequestedReportInterval , чтобы уведомления о событиях не использовали больше ресурсов процессора, чем необходимо.

Поставщику расположения не требуется предоставлять отчеты в запрашиваемом интервале. Вызовите Метод GetReportInterval , чтобы обнаружить истинный параметр интервала отчета.

Приложения, которым необходимо получить данные о расположении только один раз, чтобы заполнить форму или разместить расположение пользователя на карте, должны зарегистрироваться для получения событий и дождаться первого события отчета, как описано в разделе Ожидание отчета о расположении.

Примеры

В следующем примере вызывается метод RegisterForReport для подписки на события.

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

Требования

Требование	Значение
Минимальная версия клиента	Windows 7 [только классические приложения],Windows 7
Минимальная версия сервера	Ни одна версия не поддерживается
Целевая платформа	Windows
Header	locationapi.h
DLL	LocationAPI.dll

См. также раздел

ILocation

События ILocationEvents