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 ，指定要接收事件通知之報表類型的介面標識碼。

[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