ILocation

位置(ロケーション)レポート、イベント登録、センサーのアクセス許可を管理するためのメソッドを提供します。

ILocation オブジェクトを作成するために CoCreateInstance を呼び出したとき、それがアプリケーションによる位置(ロケーション)の最初の使用である場合は、タスクバーに通知が表示され、イベントビューアーに Location Activity イベントが記録されることがあります。

位置(ロケーション)レポートイベントを要求します。

このメソッドは HRESULT を返します。取り得る値には以下の表に示すものが含まれますが、これらに限定されません。

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

指定したレポート種別のイベント通知を停止します。

このメソッドは HRESULT を返します。取り得る値には以下の表に示すものが含まれますが、これらに限定されません。

位置(ロケーション)レポートを取得します。

このメソッドは HRESULT を返します。取り得る値には以下の表に示すものが含まれますが、これらに限定されません。

ILocationReport は、個々の位置(ロケーション)レポート種別の基底インターフェイスです。 正しいレポート種別へのポインターを取得するには、QueryInterface を呼び出してください。

GetReport を呼び出したとき、それがアプリケーションによる位置(ロケーション)の最初の使用である場合は、タスクバーに通知が表示され、イベントビューアーに Location Activity イベントが記録されることがあります。

例

次の例では、緯度/経度レポートに対して GetReport を呼び出し、指定したレポート種別へのポインターを取得するために QueryInterface を呼び出す方法を示します。

CComPtr<ILocationReport> spLocationReport; // This is our location report object
CComPtr<ILatLongReport> spLatLongReport; // This is our LatLong report object

// Get the current latitude/longitude location report,
hr = spLocation->GetReport(IID_ILatLongReport, &spLocationReport);
// then get a pointer to the ILatLongReport interface by calling QueryInterface
if (SUCCEEDED(hr))
{
    hr = spLocationReport->QueryInterface(&spLatLongReport);
}

指定したレポート種別の状態を取得します。

このメソッドは HRESULT を返します。取り得る値には以下の表に示すものが含まれますが、これらに限定されません。

このメソッドは、新しいレポートのレポート状態を取得します。このメソッドが報告する状態にかかわらず、最新のレポートは ILocation::GetReport を通じて引き続き利用できます。

既知の問題

そのため、GetReportStatus が REPORT_RUNNING という状態を示していても、GetReport の最初の呼び出しではエラー(ERROR_NO_DATA)や、期待する位置(ロケーション)センサー由来ではない値が返されます。これは次のような場合に発生することがあります:

1. アプリケーションが、REPORT_RUNNING というレポート状態が返されるまで GetReportStatus を使用して状態をポーリングし、その後 GetReport を呼び出す場合。
2. アプリケーションの起動時に GetReportStatus が呼び出される場合。これは位置(ロケーション)オブジェクトの作成後、または RequestPermissions の呼び出し後に発生することがあります。

アプリケーションは、次の回避策を実装することでこの問題を緩和できます。この回避策では、位置(ロケーション)レポートイベントを購読します。

回避策: イベントの購読

次の例は、ILatLongReport 型の位置(ロケーション)レポートを待機するアプリケーションを示します。指定した時間内にレポートが正常に取得された場合は、データを受信したことを示すメッセージを出力します。

次のコード例は、イベントに登録して最初の位置(ロケーション)レポートを待機する WaitForLocationReport という名前の関数をアプリケーションが呼び出す方法を示します。WaitForLocationReport は、コールバックオブジェクトによって設定されるイベントを待機します。WaitForLocationReport 関数とコールバックオブジェクトは、この後に続く例で定義されています。

// main.cpp
// An application that demonstrates how to wait for a location report.
// This sample waits for latitude/longitude reports but can be modified
// to wait for civic address reports by replacing IID_ILatLongReport 
// with IID_ICivicAddressReport in the following code.

#include "WaitForLocationReport.h"

#define DEFAULT_WAIT_FOR_LOCATION_REPORT 500 // Wait for half a second.

int wmain()
{
    // You may use the flags COINIT_MULTITHREADED | COINIT_DISABLE_OLE1DDE
    // to specify the multi-threaded concurrency model.
    HRESULT hr = ::CoInitializeEx(NULL,
        COINIT_APARTMENTTHREADED | COINIT_DISABLE_OLE1DDE); 
    if (SUCCEEDED(hr))
    {
        int args;
        PWSTR *pszArgList = ::CommandLineToArgvW(::GetCommandLineW(), &args);

        DWORD const dwTimeToWait = 
            (2 == args) ? static_cast<DWORD>(_wtoi(pszArgList[1])) : DEFAULT_WAIT_FOR_LOCATION_REPORT;

        ::LocalFree(pszArgList);

        wprintf_s(L"Wait time set to %lu\n", dwTimeToWait);

        ILocation *pLocation; // This is the main Location interface.
        hr = CoCreateInstance(CLSID_Location, NULL, CLSCTX_INPROC, IID_PPV_ARGS(&pLocation));
        if (SUCCEEDED(hr))
        {
            // Array of report types to listen for.
            // Replace IID_ILatLongReport with IID_ICivicAddressReport
            // for civic address reports.
            IID REPORT_TYPES[] = { IID_ILatLongReport }; 

            // Request permissions for this user account to receive location data for all the
            // types defined in REPORT_TYPES (which is currently just one report)
            // TRUE means a synchronous request.
            if (FAILED(pLocation->RequestPermissions(NULL, REPORT_TYPES, ARRAYSIZE(REPORT_TYPES), TRUE))) 
            {
                wprintf_s(L"Warning: Unable to request permissions.\n");
            }

            ILocationReport *pLocationReport; // This is our location report object
            // Replace IID_ILatLongReport with IID_ICivicAddressReport for civic address reports
            hr = ::WaitForLocationReport(pLocation, IID_ILatLongReport, dwTimeToWait, &pLocationReport);
            if (SUCCEEDED(hr))
            {
                wprintf_s(L"Successfully received data via GetReport().\n");
                pLocationReport->Release();
            }
            else if (RPC_S_CALLPENDING == hr)
            {
                wprintf_s(L"No LatLong data received.  Wait time of %lu elapsed.\n", dwTimeToWait);
            }
            pLocation->Release();
        }

        ::CoUninitialize();
    }

    return 0;
}

次のコード例は、WaitForLocationReport.h と WaitForLocationReport.cpp に分かれています。WaitForLocationReport.h には WaitForLocationReport 関数のヘッダーが含まれます。WaitForLocationReport.cpp には WaitForLocationReport 関数の定義と、それが使用するコールバックオブジェクトの定義が含まれます。このコールバックオブジェクトは、OnLocationChanged および OnStatusChanged の各コールバックメソッドの実装を提供します。これらのメソッド内で、レポートが利用可能になったことを知らせるイベントを設定します。

// WaitForLocationReport.h
// Header for the declaration of the WaitForLocationReport function.

#pragma once

#include <windows.h>
#include <LocationApi.h>
#include <wchar.h>

HRESULT WaitForLocationReport(
    ILocation* pLocation,              // Location object.
    REFIID reportType,                 // Type of report.
    DWORD dwTimeToWait,                // Milliseconds to wait.
    ILocationReport** ppLocationReport // Receives the location report.
);

// WaitForLocationReport.cpp
// Contains definitions of the WaitForLocationReport function and
// the callback object that it uses.

#include "WaitForLocationReport.h"
#include <shlwapi.h>
#include <new>

// Implementation of the callback interface that receives location reports.
class CLocationCallback : public ILocationEvents
{
public:
    CLocationCallback() : _cRef(1), _hDataEvent(::CreateEvent(
        NULL,  // Default security attributes.
        FALSE, // Auto-reset event.
        FALSE, // Initial state is nonsignaled.
        NULL)) // No event name.
    {
    }

    virtual ~CLocationCallback()
    {
        if (_hDataEvent)
        {
            ::CloseHandle(_hDataEvent);
        }
    }

    IFACEMETHODIMP QueryInterface(REFIID riid, void **ppv)
    {
        if ((riid == IID_IUnknown) || 
            (riid == IID_ILocationEvents))
        {
            *ppv = static_cast<ILocationEvents*>(this);
        }
        else
        {
            *ppv = NULL;
            return E_NOINTERFACE;
        }
        AddRef();
        return S_OK;
    }

    IFACEMETHODIMP_(ULONG) AddRef()
    {
        return InterlockedIncrement(&_cRef);
    }

    IFACEMETHODIMP_(ULONG) Release()
    {
        long cRef = InterlockedDecrement(&_cRef);
        if (!cRef)
        {
            delete this;
        }
        return cRef;
    }

    // ILocationEvents

    // This is called when there is a new location report.
    IFACEMETHODIMP OnLocationChanged(REFIID /*reportType*/, ILocationReport* /*pLocationReport*/)
    {
        ::SetEvent(_hDataEvent);
        return S_OK;
    }

    // This is called when the status of a report type changes.
    // The LOCATION_REPORT_STATUS enumeration is defined in LocApi.h in the SDK
    IFACEMETHODIMP OnStatusChanged(REFIID /*reportType*/, LOCATION_REPORT_STATUS status)
    {
        if (REPORT_RUNNING == status)
        {
            ::SetEvent(_hDataEvent);
        }
        return S_OK;
    }

    HANDLE GetEventHandle()
    {
        return _hDataEvent;
    }

private:
    long _cRef;
    HANDLE _hDataEvent;    // Data Event Handle
};

// Waits to receive a location report. 
// This function waits for the callback object to signal when
// a report event or status event occurs, and then calls GetReport.
// Even if no report event or status event is received before the timeout,
// this function still queries for the last known report by calling GetReport.
// The last known report may be cached data from a location sensor that is not
// reporting events, or data from the default location provider.
//
// Returns S_OK if the location report has been returned
// or RPC_S_CALLPENDING if the timeout expired.
HRESULT WaitForLocationReport(
    ILocation* pLocation,               // Location object.
    REFIID reportType,                 // Type of report to wait for.
    DWORD dwTimeToWait,                // Milliseconds to wait.
    ILocationReport **ppLocationReport // Receives the location report.
    )
{
    *ppLocationReport = NULL;

    CLocationCallback *pLocationCallback = new(std::nothrow) CLocationCallback();
    HRESULT hr = pLocationCallback ? S_OK : E_OUTOFMEMORY;
    if (SUCCEEDED(hr))
    {
        HANDLE hEvent = pLocationCallback->GetEventHandle();
        hr = hEvent ? S_OK : E_FAIL;
        if (SUCCEEDED(hr))
        {
            // Tell the Location API that we want to register for a report. 
            hr = pLocation->RegisterForReport(pLocationCallback, reportType, 0);
            if (SUCCEEDED(hr))
            {
                DWORD dwIndex;
                HRESULT hrWait = CoWaitForMultipleHandles(0, dwTimeToWait, 1, &hEvent, &dwIndex);
                if ((S_OK == hrWait) || (RPC_S_CALLPENDING == hrWait))
                {
                    // Even if there is a timeout indicated by RPC_S_CALLPENDING
                    // attempt to query the report to return the last known report.
                    hr = pLocation->GetReport(reportType, ppLocationReport);
                    if (FAILED(hr) && (RPC_S_CALLPENDING == hrWait))
                    {
                        // Override hr error if the request timed out and
                        // no data is available from the last known report.  
                        hr = hrWait;    // RPC_S_CALLPENDING
                    }
                }
                // Unregister from reports from the Location API.
                pLocation->UnregisterForReport(reportType);
            }
        }
        pLocationCallback->Release();
    }
    return hr;
}

レポートイベント間として要求されている時間をミリ秒単位で取得します。

このメソッドは HRESULT を返します。取り得る値には以下の表に示すものが含まれますが、これらに限定されません。

このメソッドを呼び出す前に、RegisterForReport を呼び出す必要があります。

例

次の例では、GetReportInterval を呼び出す方法を示します。

DWORD reportInterval = 0;
HRESULT hr = spLocation->GetReportInterval(IID_ILatLongReport, &reportInterval);

レポートイベント間として要求する最小時間をミリ秒単位で指定します。

このメソッドは HRESULT を返します。取り得る値には以下の表に示すものが含まれますが、これらに限定されません。

このメソッドで要求する間隔は、イベント間の最短時間を表します。つまり、指定した頻度を超えてイベント通知が送られることはないことを要求しますが、実際の経過時間はこれよりも大幅に長くなる場合があります。このメソッドを使用して、イベント通知が必要以上にプロセッサリソースを消費しないようにしてください。

特定のレポート間隔の要求が、位置(ロケーション)プロバイダーによって設定される保証はありません。実際のレポート間隔の設定を確認するには、GetReportInterval を呼び出してください。

レポート間隔が 0 の場合は、最小間隔が指定されていないことを意味し、アプリケーションは位置(ロケーション)センサーがイベントを送信する頻度でイベントを受け取ることがあります。

例

次の例では、SetReportInterval を呼び出す方法を示します。

// Set the latitude/longitude report interval to 1000 milliseconds
HRESULT hr = spLocation->SetReportInterval(IID_ILatLongReport, 1000);

現在要求されている精度の設定を取得します。

このメソッドは HRESULT を返します。取り得る値には以下の表に示すものが含まれますが、これらに限定されません。

使用する精度を指定します。

このメソッドは HRESULT を返します。取り得る値には以下の表に示すものが含まれますが、これらに限定されません。

位置(ロケーション)デバイスを有効にするためのユーザーのアクセス許可を要求するシステムダイアログボックスを開きます。

このメソッドは次のいずれかの値を返すことがあります。

次の表は、呼び出しが同期の場合の戻り値を説明します。

次の表は、呼び出しが非同期の場合の戻り値を説明します。

ユーザーが位置(ロケーション)サービスを有効にしないことを選択した場合、Windows はアクセス許可のダイアログボックスを再び表示しません。

例

次の例では、緯度/経度レポートのアクセス許可を要求するために RequestPermissions を呼び出す方法を示します。

             // Array of report types of interest. Other ones include IID_ICivicAddressReport
            IID REPORT_TYPES[] = { IID_ILatLongReport };

            // Request permissions for this user account to receive location data for all the
            // types defined in REPORT_TYPES (which is currently just one report type)
            // The last parameter is not used.
            if (FAILED(spLocation->RequestPermissions(
                  NULL, 
                  REPORT_TYPES, 
                  ARRAYSIZE(REPORT_TYPES), 
                  TRUE))) 
            {
                wprintf(L"Warning: Unable to request permissions.\n");
            }