为 Windows 8.1 编写位置传感器驱动程序

重要

本文档和适用于 Windows 8.1 的地理位置驱动程序示例已弃用。

传感器和位置平台提供 Windows 位置 API，使软件开发人员能够向其应用程序添加位置功能。 如果要为位置传感器编写驱动程序，则必须了解如何使驱动程序与位置 API 兼容，并遵循 电源和性能位置驱动程序指南中的准则。

Windows 硬件认证计划要求

Windows 硬件认证计划使硬件制造商能够获得认证，证明其设备符合使用 Windows 所需的标准。 认证计划描述了位置传感器和其他类型的传感器的要求。 应使位置传感器驱动程序符合所有认证计划要求。 这些要求包括：

• 位置传感器必须支持所需的数据和传感器属性集。

• 位置传感器必须支持至少一种内置数据报表类型的所需数据字段。

通常，此 WDK 文档中的建议符合认证计划要求。 但是，在创建要提交以供审批的传感器驱动程序时，必须查看官方认证计划文档。 有关 Windows 硬件认证计划的详细信息，请参阅 Windows Hardware Developer Central 网站。

位置 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 数据报告字段对应的传感器数据字段。 为某个位置提供数据报告时，请使用这些数据字段常量。

传感器常量	位置 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 枚举定义。 若要正确使用位置 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：:P ostStateChange 方法引发状态更改事件。 不要调用 PostEvent 来引发状态更改事件。

• 通过调用 PostEvent 引发数据更新事件。

• 仅当数据是最新且准确的时才引发数据更新事件。

• 不要两次引发数据更新事件。 这意味着不应使用缓存数据引发数据更新事件。 可以提供缓存数据以响应数据的同步请求。

• 通过事件发送纬度/经度报告时，始终包含所有必需的数据字段。

• 当传感器精度发生变化时，始终引发数据更新事件。

• 在引发事件或将SENSOR_PROPERTY_STATE的值更改为SENSOR_STATE_READY之前，报告SENSOR_DATA_TYPE_ERROR_RADIUS_METERS的有效值。

• 不要提供不完整的数据报告。

• 你可能没有所需数据字段的当前数据，例如当 GPS 传感器丢失其修补程序时。 在这种情况下，你可能仍希望向扩展数据字段（例如SENSOR_DATA_TYPE_NMEA_SENTENCE）提供有关更新的通知。 若要提供此类通知，必须使用自定义事件类型并仅引发自定义事件，直到所需数据字段的数据可用。 有关如何定义自定义类型的信息，请参阅 为常量定义自定义值。

相关主题

电源和性能位置驱动程序指南