ILocation：：RegisterForReport 方法 (locationapi.h)

[Win32 位置 API 可用于“要求”部分中指定的操作系统。 它可能在后续版本中变更或不可用。 请改用 Windows.Devices.Geolocation API。 ]

请求位置报告事件。

语法

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

参数

[in] pEvents

指向 ILocationEvents 回调接口的指针，通过该接口接收请求的事件通知。

[in] reportType

GUID ，指定要接收其事件通知的报表类型的接口 ID。

[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
标头	locationapi.h
DLL	LocationAPI.dll

另请参阅

ILocation

ILocationEvents