为 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);

标识支持的数据字段

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

传感器常量 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。设备。 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状态。

  • 始终按正确的顺序引发事件。 首先,确定数据可用。 然后,引发状态更改事件。 最后,引发更新的数据事件。

  • 当驱动程序的状态发生更改时,始终引发状态更改事件。

-Location 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

下图显示了位置传感器中可能发生状态转换的方式。state transitions.

引发数据更新和状态更改事件

位置 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。 若要提供此类通知,必须使用自定义事件类型并仅引发自定义事件,直到所需数据字段的数据变为可用为止。 有关如何定义自定义类型的信息,请参阅 为常量定义自定义值

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