ILocation::RegisterForReport メソッド (locationapi.h)

[Win32 Location API は、[要件] セクションで指定されたオペレーティング システムで使用できます。 今後のバージョンでは変更されるか、利用できなくなる場合もあります。 代わりに、 Windows.Devices.Geolocation API を使用します。 ]

場所レポート イベントを要求します。

構文

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

パラメーター

[in] pEvents

要求されたイベント通知を受信する ILocationEvents コールバック インターフェイスへのポインター。

[in] reportType

イベント通知を受信するレポートの種類のインターフェイス ID を指定する GUID。

[in] dwRequestedReportInterval

指定したレポートの種類のイベント通知の間の要求された経過時間をミリ秒単位で指定する DWORD。 dwRequestedReportInterval が 0 の場合、最小間隔は指定されておらず、アプリケーションは場所センサーの既定の間隔でイベントを受信するように要求します。 「解説」を参照してください。

戻り値

このメソッドは HRESULT を返します。 有効な値を次の表に示しますが、これ以外にもあります。

注釈

dwRequestedReportInterval パラメーターを使用して要求する間隔は、イベント間の最短の時間を表します。 つまり、イベント通知の受信を要求する頻度は指定したよりも長くなりますが、経過時間が大幅に長くなる可能性があります。 イベント通知で必要以上のプロセッサ リソースが使用されないようにするには、 dwRequestedReportInterval パラメーターを使用します。

場所プロバイダーは、要求した間隔でレポートを提供する必要はありません。 GetReportInterval を呼び出して、真のレポート間隔の設定を検出します。

場所データを 1 回だけ取得する必要があるアプリケーションは、フォームに入力したり、ユーザーの場所をマップに配置したりするために、イベントを登録し、「 場所レポートを待機する」で説明されているように、最初のレポート イベントを待機する必要があります。

例

次の例では、 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;
}

要件

こちらもご覧ください

ILocation

ILocationEvents