Windows 8.1 用位置センサー ドライバーの作成

  • [アーティクル]

重要

このドキュメントと Windows 8.1 用位置情報ドライバーのサンプルは非推奨になっています。

センサーと位置情報プラットフォームは、ソフトウェア開発者がアプリケーションに位置情報機能を追加できるようにする Windows Location API を提供します。 位置センサーのドライバーを作成する場合は、ドライバーに Location API との互換性を持たせる方法を理解し、「電力とパフォーマンスに関する位置情報ドライバーのガイドライン」に従う必要があります。

Windows ハードウェア認定プログラムの要件

Windows ハードウェア認定プログラムを使用すると、ハードウェアの製造元は、デバイスが Windows を操作するために必要な規準を満たしているという認定を受けられます。 認定プログラムでは、位置センサーとその他の種類のセンサーの要件について説明されています。 位置センサー ドライバーが、すべての認定プログラム要件に準拠している必要があります。 これらの要件を次に示します。

  • 位置センサーは、必要なデータとセンサーのプロパティのセットをサポートする必要があります。

  • 位置センサーは、少なくとも 1 つの組み込みデータ レポートの種類に必要なデータ フィールドをサポートする必要があります。

この WDK ドキュメントの推奨事項は、総じて認定プログラムの要件と一致します。 ただし、承認を受けるために提出するセンサー ドライバーを作成するときは、認定プログラムの公式ドキュメントを確認する必要があります。 Windows ハードウェア認定プログラムの詳細については、Windows Hardware Developer Central の Web サイトを参照してください。

Location API の要件

位置センサー用のドライバーは、他のカテゴリのセンサーと同じドライバー モデルとクラス拡張機能を使用して作成します。 位置センサーとして機能するには、ドライバーは少なくとも次の操作を行う必要があります。

  • 位置センサーが位置カテゴリに属していることを識別します。

  • センサーの種類を位置センサーの種類のいずれかに設定します。

  • センサーが提供する位置情報レポート データ フィールドを特定します。

  • 必須プロパティをサポートします。

  • 要求時にデータを提供します。

  • 状態遷移を管理します。

  • データ更新イベントと状態変更イベントを発生させます。

このセクションの残りの部分では、これらの最小要件について説明します。

カテゴリの識別

ISensorDriver::OnGetProperties を介して呼び出される場合は、WPD_FUNCTIONAL_OBJECT_CATEGORY プロパティの値を SENSOR_CATEGORY_LOCATION に設定します。 次のコード例は、pValues という名前の IPortableDeviceValues へのポインターを使用して、この定数を設定する方法を示しています。

hr = pValues->SetGuidValue(WPD_FUNCTIONAL_OBJECT_CATEGORY, SENSOR_CATEGORY_LOCATION);

位置センサーの種類の設定

ISensorDriver::OnGetProperties を介して呼び出される場合は、SENSOR_PROPERTY_TYPE プロパティの値を正しい値に設定します。 次のコード例は、pValues という名前の IPortableDeviceValues へのポインターを介して SENSOR_TYPE_LOCATION_GPS 定数を使用することで、センサーの種類を設定する方法を示しています。

hr = pValues->SetGuidValue(SENSOR_PROPERTY_TYPE, SENSOR_TYPE_LOCATION_GPS);

サポートされているデータ フィールドの識別

Location API は、2 種類の位置情報レポートを定義します。 これらは、位置情報データを整理するオブジェクトです。 LatLong レポートには、緯度、経度、高度のデータ フィールドと、エラー範囲情報を含むデータ フィールドが含まれます。 市民住所レポートには、市区町村や郵便番号などの住所データ フィールドが含まれています。 位置情報ドライバーは、この 2 種類のデータ レポートの少なくとも 1 つに必要なデータ フィールドをサポートする必要があります。

LatLong レポートをサポートするには、次のデータ フィールドが必要です。

  • SENSOR_DATA_TYPE_LATITUDE_DEGREES

  • SENSOR_DATA_TYPE_LONGITUDE_DEGREES

  • SENSOR_DATA_TYPE_ERROR_RADIUS_METERS

市民住所レポートをサポートするには、次のデータ フィールドの少なくとも 1 つが必要です。

  • SENSOR_DATA_TYPE_COUNTRY_REGION

プラットフォーム定義の位置情報データ フィールドの完全なセットを表示するには、「Windows センサー リファレンス」セクションの「SENSOR_CATEGORY_LOCATION」を参照してください。

ISensorDriver::OnGetSupportedDataFields を介して呼び出される場合は、ppSupportedDataFields パラメーターを介して返す IPortableDeviceKeyCollection に、サポートされているデータ フィールドのプロパティ キー定数を追加します。 次のコード例は、pKeyCollection という名前の変数を介して、郵便番号データ フィールドを IPortableDeviceKeyCollection に追加する方法を示しています。

pKeyCollection->Add(SENSOR_DATA_TYPE_POSTALCODE);

必須プロパティのサポート

他のセンサー ドライバーと同様に、位置情報ドライバーは、一連のプロパティを通じてセンサー自体に関する情報を提供します。 Windows ハードウェア認定プログラムは、位置センサーがサポートする必要があるプロパティの最小必須セットを指定します。 センサーのプロパティ、その意味、センサー ドライバーに必要なプロパティの詳細については、「センサーのプロパティ」を参照してください。 次の一覧には、必須プロパティが含まれています。

  • WPD_FUNCTIONAL_OBJECT_CATEGORY

  • SENSOR_PROPERTY_TYPE

  • SENSOR_PROPERTY_STATE

  • SENSOR_PROPERTY_PERSISTENT_UNIQUE_ID

  • SENSOR_PROPERTY_MANUFACTURER

  • SENSOR_PROPERTY_MODEL

  • SENSOR_PROPERTY_SERIAL_NUMBER

  • SENSOR_PROPERTY_FRIENDLY_NAME

  • SENSOR_PROPERTY_MIN_REPORT_INTERVAL

  • SENSOR_PROPERTY_CURRENT_REPORT_INTERVAL

  • SENSOR_PROPERTY_LOCATION_DESIRED_ACCURACY

データの提供

位置情報ドライバーは、他のセンサー ドライバーと同じメカニズムを介してデータを提供します。 つまり、センサー クラス拡張機能は ISensorDriver::OnGetDataFields を介してドライバーを呼び出し、ドライバーは ppDataValues パラメーターを介して値を返します。

位置センサーからのデータの提供には、次の要件が適用されます。

  • 同期要求とイベントの発生の両方を通じてデータを提供します。

  • 最新のデータ レポートのコピーを保持します。 要求時に新しいデータを使用できない場合は、キャッシュされたレポートを返します。 タイム スタンプは更新しません。

  • 現実世界の緯度と経度の範囲外にある SENSOR_DATA_TYPE_LATITUDE_DEGREES と SENSOR_DATA_TYPE_LONGITUDE_DEGREES の値は提供しません。

  • 0 以下の SENSOR_DATA_TYPE_ERROR_RADIUS_METERS の値は報告しません。

  • SENSOR_DATA_TYPE_COUNTRY_REGION の値を有効な ISO 3166 1-alpha-2 国コードに設定します。

  • ドライバーが緯度/経度と市民住所レポートの両方をサポートしている場合、これらのレポートの位置情報データは同じ物理的な場所に対応している必要があります。

次の表では、Location API データ レポート フィールドに対応するセンサー データ フィールドについて説明します。 場所についてのデータ レポートを提供する場合は、これらのデータ フィールド定数を使用します。

センサー定数 Location API のメソッドとプロパティ
SENSOR_DATA_TYPE_ADDRESS1 ICivicAddressReport::GetAddressLine1

LocationDisp.DispCivicAddressReport.AddressLine1
SENSOR_DATA_TYPE_ADDRESS2 ICivicAddressReport::GetAddressLine2

LocationDisp.DispCivicAddressReport.AddressLine2
SENSOR_DATA_TYPE_ALTITUDE_ELLIPSOID_ERROR_METERS ILatLongReport::GetAltitudeError

LocationDisp.DispLatLongReport.AltitudeError
SENSOR_DATA_TYPE_ALTITUDE_ELLIPSOID_METERS ILatLongReport::GetAltitude

LocationDisp.DispLatLongReport.Altitude
SENSOR_DATA_TYPE_CITY ICivicAddressReport::GetCity

LocationDisp.DispCivicAddressReport.City

Windows.Devices. Geolocation.CivicAddress
SENSOR_DATA_TYPE_COUNTRY_REGION ICivicAddressReport::GetCountryRegion

LocationDisp.DispCivicAddressReport.CountryRegion
SENSOR_DATA_TYPE_ERROR_RADIUS_METERS ILatLongReport::GetErrorRadius

LocationDisp.DispLatLongReport.ErrorRadius
SENSOR_DATA_TYPE_LATITUDE_DEGREES ILatLongReport::GetLatitude

LocationDisp.DispLatLongReport.Latitude
SENSOR_DATA_TYPE_LONGITUDE_DEGREES ILatLongReport::GetLongitude

LocationDisp.DispLatLongReport.Longitude
SENSOR_DATA_TYPE_POSTALCODE ICivicAddressReport::GetPostalCode

LocationDisp.DispCivicAddressReport.PostalCode
SENSOR_DATA_TYPE_STATE_PROVINCE ICivicAddressReport::GetStateProvince

LocationDisp.DispCivicAddressReport.StateProvince

状態遷移の管理

センサー ドライバーは、常にいくつかの状態のいずれかになります。 センサーの状態は、SensorState 列挙型によって定義されます。 Location API を正しく操作するには、位置センサーが状態遷移を処理するためにこれらの規則に従う必要があります。

  • 常に SENSOR_STATE_INITIALIZING 状態で開始しますが、開始時には状態変更イベントを発生させません。

  • ドライバーは、データが使用可能な場合に SENSOR_STATE_INITIALIZING から SENSOR_STATE_READY に切り替わる必要があります。

  • レポートする現在のデータがない場合、ドライバーは SENSOR_STATE_INITIALIZING に戻る必要があります。 ドライバーは、その遷移が発生するタイミングを決定する必要があります。 シグナルを失ったが、有効なデータを提供する手段がある場合は、SENSOR_STATE_READY 状態を維持します。

  • 常に正しい順序でイベントを発生させます。 初めに、データが使用可能であることを確認します。 次に、状態変更イベントを発生させます。 最後に、データ更新イベントを発生させます。

  • ドライバーの状態が変わった場合は、常に状態変更イベントを発生させます。

-Location API は、状態が SENSOR_STATE_NO_DATA、SENSOR_STATE_NOT_AVAILABLE、SENSOR_STATE_ERROR のセンサーからのデータは使用しません。

次の表では、位置センサー ドライバーのさまざまなセンサーの状態について説明します。

値 説明 Location API の状態
SENSOR_STATE_READY センサー ドライバーは、完全で正確なデータを持つ新しい位置情報レポートを提供できます。 たとえば、Wi-Fi または携帯ネットワーク プロバイダーが接続されて動作している場合や、GPS センサーが修正された場合などが含まれます。 三角測量センサーからのデータを使用して位置を特定した GPS ドライバーは、この状態になります。 REPORT_RUNNING
SENSOR_STATE_INITIALIZING センサー ドライバーが修正を取得しようとしています。 センサー ドライバーは、修正がロックされ、追跡された後、この状態から SENSOR_STATE_READY に遷移する必要があります。 たとえば、Wi-Fi プロバイダーがインターネット接続を探している場合、携帯ネットワーク プロバイダーが無線を探している場合、GPS センサーが修正を取得している場合などが含まれます。 GPS センサーは、修正を再取得しようとする場合に、この状態に戻る必要があります。 REPORT_INITIALIZING
SENSOR_STATE_NO_DATA 位置情報プロバイダーは使用できますが、位置情報データを提供できません。 たとえば、Wi-Fi プロバイダーはインターネットにアクセスできますが、データベースに位置情報データがない場合などが含まれます。 REPORT_ERROR
SENSOR_STATE_NOT_AVAILABLE 位置情報プロバイダーがデータの取得に使用する機能が無効です。 無線がオフの場合、GPS センサーはこの状態になる可能性があります。 REPORT_ERROR
SENSOR_STATE_ERROR センサーで大きなエラーが発生しました。 センサーはこの状態から復旧できますが、復旧の期間は不明です。 REPORT_ERROR

次の図は、位置センサーで状態遷移がどのように発生するかを示しています。状態遷移。

データ更新イベントと状態変更イベントを発生させる

Location API は、データと状態変更情報を提供するイベントを発生させるために、GPS センサーなどの位置情報センサーを必要とします。 センサー イベントの発生の詳細については、「センサー ドライバーのイベントについて」を参照してください。

これらのイベントを発生させる場合、位置情報ドライバーは次の規則に従う必要があります。

  • センサー クラス拡張機能の ISensorClassExtension::PostStateChange メソッドを呼び出すことによって、状態変更イベントを発生させます。 PostEvent を呼び出して状態変更イベントを発生させてはなりません。

  • PostEvent を呼び出して、データ更新イベントを発生させます。

  • データが最新で正確な場合にのみ、データ更新イベントを発生させます。

  • データ更新イベントは 2 回発生させてはなりません。 つまり、キャッシュされたデータを使用してデータ更新イベントを発生させないようにします。 データの同期要求に応答して、キャッシュされたデータを提供することはできます。

  • イベントを通じて緯度/経度レポートを送信する場合は、常にすべての必須データ フィールドを含めます。

  • センサーの精度が変わったら、常にデータ更新イベントを発生させます。

  • イベントを発生させる前、または SENSOR_PROPERTY_STATE の値を SENSOR_STATE_READY に変更する前に、SENSOR_DATA_TYPE_ERROR_RADIUS_METERS の有効な値を報告します。

  • 不完全なデータ レポートを提供しないようにします。

  • GPS センサーの修正が失われた場合など、必要なデータ フィールドに現在のデータがない可能性があります。 この場合でも、SENSOR_DATA_TYPE_NMEA_SENTENCE など、拡張データ フィールドの更新に関する通知を提供する必要があることがあります。 このような通知を提供するには、必要なデータ フィールドのデータが使用可能になるまで、カスタム イベントの種類を使用し、カスタム イベントのみを発生させる必要があります。 カスタム型を定義する方法については、「定数のカスタム値の定義」を参照してください。

電力とパフォーマンスに関する位置情報ドライバーのガイドライン