为 Windows 8.1 编写位置传感器驱动程序
重要
本文档和 Windows 8.1的地理位置驱动程序示例已弃用。
传感器和位置平台提供 Windows 位置 API，使软件开发人员能够将定位功能添加到其应用程序中。 如果要为位置传感器编写驱动程序，则必须了解如何使驱动程序与位置 API 兼容，并遵循位置驱动程序功率和性能指南准则。
Windows 硬件认证计划要求
Windows 硬件认证计划使硬件制造商能够获得认证，证明其设备符合使用 Windows 所需的标准。 认证计划描述了位置传感器和其他类型的传感器的要求。 应使位置传感器驱动程序符合所有认证计划要求。 这些要求包括以下内容：
位置传感器必须支持所需的数据集和传感器属性。
位置传感器必须至少支持一种内置数据报表类型的所需数据字段。
一般来说，本 WDK 文档中的建议符合认证计划的要求。 但是，创建要提交的传感器驱动程序以供审批时，必须查阅官方认证计划文档。 有关 Windows 硬件认证计划的详细信息，请参阅 Windows 硬件开发人员中心网站。
位置 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);
标识支持的数据字段
位置 API 定义两种类型的位置报告。 这些是组织位置数据的对象。 LatLong 报表包含纬度、经度和海拔数据字段，以及包含错误范围信息的数据字段。 公民地址报告包含街道地址数据字段，例如城市和邮政编码。 位置驱动程序必须至少支持这两种数据报表类型的一种所需的数据字段。
若要支持 LatLong 报表，需要以下数据字段：
SENSOR_DATA_TYPE_LATITUDE_DEGREES
SENSOR_DATA_TYPE_LONGITUDE_DEGREES
SENSOR_DATA_TYPE_ERROR_RADIUS_METERS
若要支持公民地址报告，至少需要以下数据字段之一：
- 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 提供值。
不要报告 SENSOR_DATA_TYPE_ERROR_RADIUS_METERS 的值为零或更小。
将 SENSOR_DATA_TYPE_COUNTRY_REGION 的值设置为有效的 ISO 3166 1-alpha-2 国家/地区代码。
如果驱动程序同时支持纬度/经度和公民地址报告，则这些报表中的位置数据应对应于相同的物理位置。
下表介绍了与位置 API 数据报告字段相对应的传感器数据字段。 当为某个位置提供数据报告时，请使用这些数据字段常量。
管理状态转换
在任何时候，传感器驱动程序都可以处于多种状态之一。 传感器状态由 SensorState 枚举定义。 若要正确使用位置 API，位置传感器必须遵循这些规则来处理状态转换。
始终在 SENSOR_STATE_INITIALIZING 状态下启动，但在启动时不要引发状态更改事件。
当数据可用时，驱动程序应从 SENSOR_STATE_INITIALIZING 转换到 SENSOR_STATE_READY。
当驱动器没有当前数据要报告时，驱动器应转换回 SENSOR_STATE_INITIALIZING。 驱动程序应确定何时发生转换。 如果丢失了信号，但仍有方法提供有效数据，请保持 SENSOR_STATE_READY 状态。
始终按正确的顺序引发事件。 首先，确定数据可用。 然后，引发状态更改事件。 最后，引发数据更新事件。
当驱动程序的状态发生更改时，始终引发状态更改事件。
-位置 API 不使用处于以下状态的传感器的数据：SENSOR_STATE_NO_DATA、SENSOR_STATE_NOT_AVAILABLE、SENSOR_STATE_ERROR。
下表介绍了位置传感器驱动程序的各种传感器状态。
| 值 | 说明 | 位置 API 状态 |
|---|---|---|
| SENSOR_STATE_READY | 传感器驱动程序可以提供具有完整且准确数据的新位置报告。 例如，Wi-Fi 或手机网络提供商已连接且正常工作，或者 GPS 传感器有修补程序。 一个 GPS 驱动程序，它使用三角测量传感器中的数据来确定位置具有此状态。 | REPORT_RUNNING |
| SENSOR_STATE_INITIALIZING | 传感器驱动程序正在尝试获取修补程序。 锁定并跟踪修补程序后，传感器驱动程序应保留此状态以转换为 SENSOR_STATE_READY。 例如，Wi-Fi 提供商正在寻找 Internet 连接、手机网络提供商正在寻找无线电，或者 GPS 传感器正在获取修补程序。 GPS 传感器在尝试重新获取修补程序时应重新进入此状态。 | REPORT_INITIALIZING |
| SENSOR_STATE_NO_DATA | 位置提供程序可用，但无法提供位置数据。 例如，Wi-Fi 提供程序有权访问 Internet，但数据库没有位置数据。 | REPORT_ERROR |
| SENSOR_STATE_NOT_AVAILABLE | 位置提供程序用于获取数据的功能已禁用。 如果无线电关闭，GPS 传感器可能处于此状态。 | REPORT_ERROR |
| SENSOR_STATE_ERROR | 传感器遇到重大错误。 传感器可以从此状态恢复，但恢复的时间范围尚不清楚。 | REPORT_ERROR |
下图显示了位置传感器中如何发生状态转换。
引发数据更新和状态更改事件
位置 API 需要位置传感器（如 GPS 传感器），引发提供数据和状态更改信息的事件。 有关引发传感器事件的详细信息，请参阅关于传感器驱动程序事件。
引发这些事件时，位置驱动程序必须遵循以下规则：
通过调用传感器类扩展的 ISensorClassExtension::PostStateChange 方法引发状态更改事件。 不要调用 PostEvent 来引发状态更改事件。
通过调用 PostEvent 来引发数据更新事件。
仅当数据为最新且准确时，才引发数据更新事件。
不要两次引发数据更新事件。 这意味着不应使用缓存数据引发数据更新事件。 可以提供缓存数据，以响应数据同步请求。
通过事件发送纬度/经度报告时，始终包含所有必需数据字段。
当传感器准确度发生更改时，始终引发数据更新事件。
在引发事件或将 SENSOR_PROPERTY_STATE 的值更改为 SENSOR_STATE_READY 之前，报告 SENSOR_DATA_TYPE_ERROR_RADIUS_METERS 的有效值。
不要提供不完整的数据报告。
你可能没有所需数据字段的当前数据，例如当 GPS 传感器丢失修补程序时。 在这种情况下，你可能仍希望提供有关扩展数据字段（例如 SENSOR_DATA_TYPE_NMEA_SENTENCE）更新的通知。 若要提供此类通知，必须使用自定义事件类型，并仅引发自定义事件，直到所需数据字段的数据变为可用为止。 有关如何定义自定义类型的信息，请参阅为常量定义自定义值。