位置センサー ドライバーの作成
注 ここでは、位置データを提供するデバイスのドライバーの作成に関する具体的なガイダンスを示します。このセクションに記載されている情報以外に、位置ドライバーの作成者は、「センサー デバイス ドライバーの作成」で説明されている情報も理解して活用する必要があります。
Sensor and Location プラットフォームには Windows Location API が用意されており、この API を使用することで、アプリケーション開発者は位置機能をプログラムに簡単に追加できます。位置センサーのドライバーを作成する場合、ドライバーを Location API と互換性があるようにする方法を理解することが重要です。
Windows ロゴ プログラムの要件
Windows ロゴ プログラムでは、ハードウェア製造元は、自社のデバイスが Microsoft Windows を操作するために必要な標準を満たしているという証明を受けることができます。このプログラムでは、位置センサーに対する要件と、その他の種類のセンサーに対する要件の両方が提示されます。位置センサー ドライバーの開発者は、作成するドライバーがロゴ プログラムのすべての要件を満たすようにする必要があります。それらの要件は、以下のとおりです。
位置センサーは、必要なデータ プロパティとセンサー プロパティのセットをサポートしている必要があります。
位置センサーは、少なくとも 1 つの組み込みのデータ レポートの種類の必須データ フィールドをサポートしている必要があります。
この WDK ドキュメントに記載された推奨事項は、ロゴ プログラムの要件と概ね一致しています。しかし、証明を受けようとするセンサー ドライバーの作成時には、ロゴ プログラムの公式ドキュメントを必ず参照してください。Windows ロゴ プログラムの詳細については、Windows Hardware Developer Central の Web サイトを参照してください。
Location API の要件
位置センサーのドライバーを作成するには、他のカテゴリのセンサーの場合と同じドライバー モデルおよびクラス拡張を使用します。少なくとも、位置センサーとして機能するためには、ドライバーは次の処理を行う必要があります。
位置センサーを "位置" カテゴリに属していると特定します。
センサーの種類を、位置センサーの種類の 1 つに設定します。
センサーが提供する位置レポート データ フィールドを特定します。
必要なプロパティをサポートします。
要求があったときにデータを提供します。
状態遷移を管理します。
データ更新イベントと状態変更イベントを生成します。
このセクションの後半では、これらの最小要件について説明します。
カテゴリの特定
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 プロパティの値を正しい値に設定します。次のコード例は、定数 SENSOR_TYPE_LOCATION_GPS を使用することで、pValues という名前の IPortableDeviceValues へのポインターを通じてセンサーの種類を設定する方法を示しています。
hr = pValues->SetGuidValue(SENSOR_PROPERTY_TYPE, SENSOR_TYPE_LOCATION_GPS);
サポートされるデータ フィールドの特定
Location API は、2 種類の位置レポートを定義します。これらの位置レポートは、位置データを整理するオブジェクトです。緯度/経度レポートには、緯度、経度、および高度の各データ フィールドと、エラー範囲情報を格納するデータ フィールドがあります。住所レポートには、市区町村、郵便番号などの番地データ フィールドがあります。位置ドライバーは、この 2 つのデータ レポートの種類のうち少なくとも 1 つの必須データ フィールドをサポートしている必要があります。
緯度/経度レポートをサポートする場合、次のデータ フィールドはすべて必須です。
- SENSOR_DATA_TYPE_LATITUDE_DEGREES
- SENSOR_DATA_TYPE_LONGITUDE_DEGREES
- SENSOR_DATA_TYPE_ERROR_RADIUS_METERS
住所レポートをサポートする場合、次のデータ フィールドのうち少なくとも 1 つは必須です。
- SENSOR_DATA_TYPE_COUNTRY_REGION
- SENSOR_DATA_TYPE_POSTALCODE
(プラットフォーム定義の位置データ フィールドの完全なセットを表示するには、「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 には値を指定しません。
ゼロ以下の SENSOR_DATA_TYPE_ERROR_RADIUS_METERS の値は報告しません。
SENSOR_DATA_TYPE_COUNTRY_REGION の値を、有効な ISO 3166 1-alpha-2 国コードに設定します。
ドライバーが緯度/経度レポートと住所レポートの両方をサポートしている場合、これらのレポートの位置データは、同じ物理的な位置に対応している必要があります。
次の表は、Location API データ レポート フィールドに対応するセンサー データ フィールドを示しています。位置のデータ レポートを提供する場合は、次に示すデータ フィールド定数を使用します。
| センサー定数 | Location API のメソッドおよびプロパティ |
|---|---|
SENSOR_DATA_TYPE_ADDRESS1 |
|
SENSOR_DATA_TYPE_ADDRESS2 |
|
SENSOR_DATA_TYPE_ALTITUDE_ELLIPSOID_ERROR_METERS |
|
SENSOR_DATA_TYPE_ALTITUDE_ELLIPSOID_METERS |
|
SENSOR_DATA_TYPE_CITY |
|
SENSOR_DATA_TYPE_COUNTRY_REGION |
|
SENSOR_DATA_TYPE_ERROR_RADIUS_METERS |
|
SENSOR_DATA_TYPE_LATITUDE_DEGREES |
|
SENSOR_DATA_TYPE_LONGITUDE_DEGREES |
|
SENSOR_DATA_TYPE_POSTALCODE |
|
SENSOR_DATA_TYPE_STATE_PROVINCE |
状態遷移の管理
センサー ドライバーの特定の時点における状態は、次のいずれかです。センサーの状態は、SensorState 列挙型によって定義されます。位置センサーは、Location API で正しく機能するために状態遷移を処理する場合、次の項目に従う必要があります。
常に SENSOR_STATE_NO_DATA 状態で開始しますが、起動時には状態変更イベントを生成しません。
常に正しい順序でイベントを生成します。まずデータがあることを確認してから、状態変更イベントを生成し、最終的にデータ更新イベントを生成します。
ドライバーの状態が変更された場合、常に状態変更イベントを生成します。
Location API は、SENSOR_STATE_NO_DATA、SENSOR_STATE_NOT_AVAILABLE、および SENSOR_STATE_ERROR の状態のセンサーのデータを使用しません。
位置センサー ドライバーのさまざまなセンサー状態を次の表に示します。
| 値 | 意味 | Location API の状態 |
|---|---|---|
SENSOR_STATE_READY |
センサー ドライバーは、完全かつ正確なデータを含む新しい位置レポートを提供できます。 たとえば、WiFi プロバイダーまたは携帯電話プロバイダーが接続され稼働している、GPS センサーに修正プログラムがある、などの状態です。 |
REPORT_RUNNING |
SENSOR_STATE_INITIALIZING |
センサー ドライバーは現在、修正プログラムを取得しようとしています。センサー ドライバーには、有効なデータが既に存在しており、要求されたときにこのデータを提供する必要があります。修正プログラムがロックされ追跡が開始された後、センサー ドライバーはこの状態から SENSOR_STATE_READY に移行する必要があります。 たとえば、WiFi プロバイダーがインターネット接続を探している、携帯電話プロバイダーが無線を探している、GPS センサーが修正プログラムを取得している、などの状態です。 GPS センサーは、修正プログラムを再取得するときに再びこの状態に移行する必要があります。 |
REPORT_INITIALIZING |
SENSOR_STATE_NO_DATA |
位置プロバイダーは使用可能ですが、位置データを提供していません。 たとえば、WiFi プロバイダーにインターネットへのアクセス権があって、データベースに位置データがない状態などです。 |
REPORT_ERROR |
SENSOR_STATE_NOT_AVAILABLE |
位置プロバイダーが使用できません。 たとえば、WiFi プロバイダーにインターネットへのアクセス権がない状態などです。信号がない場合、GPS センサーはこの状態になる可能性があります。 |
REPORT_ERROR |
SENSOR_STATE_ERROR |
センサーで重大なエラーが発生しました。センサーはこの状態から回復できますが、回復の期間は不明です。 |
REPORT_ERROR |
データ更新イベントと状態変更イベントの生成
Location API では、データおよび状態変更情報を提供するイベントを生成するために、GPS センサーなどの位置センサーが必要です。センサー イベントの生成の詳細については、「センサー ドライバー イベントについて」を参照してください。
これらのイベントを生成する場合、位置ドライバーは次の規則に従う必要があります。
データが最新で正確な場合のみ、データ更新イベントを生成します。
データ更新イベントを 2 回生成することはありません。つまり、キャッシュされたデータを使用してデータ更新イベントを生成することはできません。データの同期要求に応じて、ユーザーはキャッシュされたデータを提供できます。
イベントを通じて緯度/経度レポートを送信する場合、常に必須データ フィールドをすべて含めます。
センサーの精度が変更された場合、常にデータ更新イベントを生成します。
イベントを生成する前、または SENSOR_PROPERTY_STATE から SENSOR_STATE_READY に値を変更する前に、SENSOR_DATA_TYPE_ERROR_RADIUS_METERS の有効な値を報告します。
不完全なデータ レポートを提供することはありません。
GPS センサーが修正プログラムを失った場合など、必須データ フィールドに最新のデータがない場合があります。この場合、拡張されたデータ フィールドの更新に関する通知 (SENSOR_DATA_TYPE_NMEA_SENTENCE など) を引き続き提供することもできます。このような通知を提供するには、カスタム イベント型を使用して、必須データ フィールドのデータが使用可能になるまでカスタム イベントのみを生成する必要があります。カスタム型を定義する方法の詳細については、「定数のカスタム値の定義」を参照してください。