ILocationReport：：GetValue 方法 (locationapi.h)
[Win32 位置 API 可用于“要求”部分中指定的操作系统。 它可能在后续版本中变更或不可用。 请改用 Windows.Devices.Geolocation API。 ]
从位置报表中检索属性值。
语法
HRESULT GetValue(
[in] REFPROPERTYKEY pKey,
[out] PROPVARIANT *pValue
);
参数
[in] pKey
REFPROPERTYKEY ，指定要检索的属性的名称。
[out] pValue
接收属性值的 PROPVARIANT 的地址。
返回值
如果该方法成功，则返回 S_OK。 否则，将返回 HRESULT 错误代码。
注解
属性可以是平台定义的，也可以是制造商定义的。
位置传感器的平台定义的 PROPERTYKEY 值在 sensors.h 的位置传感器数据类型部分中定义。
下面是一些平台定义的属性的表，这些属性通常与位置报告相关联。 这些属性键具有等于 SENSOR_DATA_TYPE_LOCATION_GUID 的 fmtid 字段。 可以在 sensors.h 中找到其他属性。 如果要实现自己的位置报表以传递到 SetReport，此表指示必须在报表对象的 GetValue 实现中提供哪些值。
| 属性键名称和类型 | 说明 |
|---|---|
| SENSOR_DATA_TYPE_LATITUDE VT_R8 | 北为正的纬度。
注意 传递给 SetReport 的纬度/经度报表对象必须在其 GetValue 的实现中提供此值。
|
| SENSOR_DATA_TYPE_LONGITUDE VT_R8 | 以东为正的度经度。
注意 传递给 SetReport 的纬度/经度报表对象必须在其 GetValue 的实现中提供此值。
|
| SENSOR_DATA_TYPE_ALTITUDE_SEALEVEL_METERS VT_R8 | 相对于海平面的海拔高度（以米为单位）。 |
| SENSOR_DATA_TYPE_ALTITUDE_ELLIPSOID_METERS VT_R8 | 相对于参考椭圆形的高度，以米为单位。 |
| SENSOR_DATA_TYPE_SPEED_KNOTS VT_R8 | 以结为单位的速度。 |
| SENSOR_DATA_TYPE_TRUE_HEADING_DEGREES VT_R8 | 相对于正北方向（以度为单位）。 |
| SENSOR_DATA_TYPE_MAGNETIC_HEADING_DEGREES VT_R8 | 相对于磁北的方向（以度为单位）。 |
| SENSOR_DATA_TYPE_MAGNETIC_VARIATION VT_R8 | 磁变。 东部是积极的。 |
| SENSOR_DATA_TYPE_ERROR_RADIUS_METERS VT_R8 | 指示纬度和经度精度（以米为单位）的误差半径。
注意 传递给 SetReport 的纬度/经度报表对象必须在其 GetValue 的实现中提供此值。
|
| SENSOR_DATA_TYPE_ADDRESS1 VT_LPWSTR | 市政地址报告中地址的第一行。
注意 如果传递给 SetReport 的市政地址报告对象包含此数据，则应在其 GetValue 的实现中提供此值。
|
| SENSOR_DATA_TYPE_ADDRESS2 VT_LPWSTR | 市政地址报告中地址的第二行。 注意 如果传递给 SetReport 的市政地址报告对象包含此数据，则应在其 GetValue 的实现中提供此值。
|
| SENSOR_DATA_TYPE_CITY VT_LPWSTR | 市政地址报告中的“城市”字段。 注意 如果传递给 SetReport 的市政地址报告对象包含此数据，则应在其 GetValue 的实现中提供此值。
|
| SENSOR_DATA_TYPE_STATE_PROVINCE VT_LPWSTR | 市政地址报告中的州/省字段。 注意 如果传递给 SetReport 的市政地址报告对象包含此数据，则应在其 GetValue 的实现中提供此值。
|
| SENSOR_DATA_TYPE_POSTALCODE VT_LPWSTR | 市政地址报表中的邮政编码字段。 注意 如果传递给 SetReport 的市政地址报告对象包含此数据，则应在其 GetValue 的实现中提供此值。
|
| SENSOR_DATA_TYPE_COUNTRY_REGION VT_LPWSTR | 市政地址报告中的国家/地区代码。 该值必须是两个字母或三个字母的 ISO 3166 国家/地区代码。
注意 传递给 SetReport 的市政地址报告对象必须在其 GetValue 的实现中提供此值。
|
| SENSOR_DATA_TYPE_ALTITUDE_ELLIPSOID_ERROR_METERS VT_R8 | 与参考椭圆体相关的海拔高度误差（以米为单位）。 |
| SENSOR_DATA_TYPE_ALTITUDE_SEALEVEL_ERROR_METERS VT_R8 | 海平面的海拔误差（以米为单位）。 |
下面是其他平台定义属性的表，这些属性可能出现在位置报告中，但不特定于位置。 这些属性键的 fmtid 字段 SENSOR_PROPERTY_COMMON_GUID。
| 属性键名称和类型 | 说明 |
|---|---|
| SENSOR_PROPERTY_ACCURACY VT_UNKNOWN | 包含传感器数据类型名称及其关联准确性的 IPortableDeviceValues 对象。 准确性值表示与 true 值可能的变化。
准确度值使用与数据字段相同的单位表示，除非另有说明。 |
| SENSOR_PROPERTY_CHANGE_SENSITIVITY VT_UNKNOWN |
包含传感器数据类型名称及其关联的更改敏感度值的 IPortableDeviceValues 对象。 更改敏感度值表示在引发SENSOR_EVENT_DATA_UPDATED事件之前数据字段必须更改的量。
敏感度值使用与数据字段相同的单位表示，除非另有说明。 例如，SENSOR_DATA_TYPE_TEMPERATURE_CELSIUS的更改敏感度值为 2 表示正负 2 摄氏度的敏感度。 |
| SENSOR_PROPERTY_CURRENT_CONNECTION_TYPE VT_UI4 | 包含当前连接类型的 SensorConnectionType 值。 |
| SENSOR_PROPERTY_CURRENT_REPORT_INTERVAL VT_UI4 |
传感器数据报告生成的当前运行时间（以毫秒为单位）。
将值设置为零会指示驱动程序使用其默认报告间隔。 在收到此属性的零值后，驱动程序在查询时必须返回其默认报告间隔，而不是零。 应用程序可以设置此值以请求特定的报告间隔，但多个应用程序可能使用同一驱动程序。 因此，驱动程序确定基于内部逻辑的真实报告间隔。 例如，驱动程序可能始终使用调用方请求的最短报告间隔。 |
| SENSOR_PROPERTY_DESCRIPTION VT_LPWSTR | 传感器说明字符串。 |
| SENSOR_PROPERTY_DEVICE_PATH VT_LPWSTR |
唯一标识与传感器关联的设备实例。 可以使用此属性来确定设备是否包含多个传感器。
设备驱动程序不必支持此属性，因为平台在不查询驱动程序的情况下向应用程序提供此值。 |
| SENSOR_PROPERTY_FRIENDLY_NAME VT_LPWSTR | 设备的友好名称。 |
| SENSOR_PROPERTY_LOCATION_DESIRED_ACCURACY VT_UI4 | 一个枚举值，指示客户端应用程序请求的准确度处理类型。LOCATION_DESIRED_ACCURACY_DEFAULT (0) 指示传感器应使用可优化电源使用和其他成本考虑的准确度。
LOCATION_DESIRED_ACCURACY_HIGH (1) 指示传感器应尽可能提供最准确的报告。 这包括使用可能收费的服务或消耗更高级别的电池电量或连接带宽。 |
| SENSOR_PROPERTY_MANUFACTURER VT_LPWSTR | 制作者类的名称。 |
| SENSOR_PROPERTY_MIN_REPORT_INTERVAL VT_UI4 | 硬件支持生成传感器数据报表的最短运行时间设置（以毫秒为单位）。 |
| SENSOR_PROPERTY_MODEL VT_LPWSTR | 传感器模型名称。 |
| SENSOR_PROPERTY_PERSISTENT_UNIQUE_ID VT_CLSID | 标识传感器的 GUID 。 此值对于设备上的每个传感器都必须是唯一的，或者对于计算机上枚举的相同型号的设备。 |
| SENSOR_PROPERTY_RANGE_MAXIMUM VT_UKNOWN | 包含传感器数据字段名称及其关联的最大值的 IPortableDeviceValues 对象。 |
| SENSOR_PROPERTY_RANGE_MINIMUM VT_UKNOWN | 包含传感器数据字段名称及其关联的最小值的 IPortableDeviceValues 对象。 |
| SENSOR_PROPERTY_RESOLUTION VT_UKNOWN | 包含传感器数据字段名称及其关联分辨率的 IPortableDeviceValues 对象。 分辨率值表示数据字段中更改的敏感度。
分辨率值使用与数据字段相同的单位表示，除非另有说明。 |
| SENSOR_PROPERTY_SERIAL_NUMBER VT_LPWSTR | 传感器序列号。 |
| SENSOR_PROPERTY_STATE VT_UI4 | 包含当前传感器状态的 SensorState 值。 |
| SENSOR_PROPERTY_TYPE VT_CLSID | 标识传感器类型的 GUID 。 平台定义的传感器类型在 Sensors.h 中定义。 |
示例
以下示例演示如何调用 GetValue 来获取属性值。 必须包含 sensors.h 才能使用示例中的 常量。
PROPVARIANT pv;
HRESULT hr = spLatLongReport->GetValue(SENSOR_DATA_TYPE_LATITUDE_DEGREES, &pv);
以下示例演示如何在你自己的报表对象中实现 GetValue 。 此实现允许调用方获取多个位置报告字段的值。 此代码要求包含 sensors.h 和 provarutil.h。
STDMETHODIMP CLocationReport::GetValue(REFPROPERTYKEY pKey, PROPVARIANT *pValue)
{
HRESULT hr = S_OK;
if (pKey.fmtid == SENSOR_DATA_TYPE_LOCATION_GUID)
{
// properties for civic address reports
if (pKey.pid == SENSOR_DATA_TYPE_ADDRESS1.pid)
{
hr = InitPropVariantFromString(m_address1, pValue);
}
else if (pKey.pid == SENSOR_DATA_TYPE_ADDRESS2.pid)
{
hr = InitPropVariantFromString(m_address2, pValue);
}
else if (pKey.pid == SENSOR_DATA_TYPE_CITY.pid)
{
hr = InitPropVariantFromString(m_city, pValue);
}
else if (pKey.pid == SENSOR_DATA_TYPE_STATE_PROVINCE.pid)
{
hr = InitPropVariantFromString(m_stateprovince, pValue);
}
else if (pKey.pid == SENSOR_DATA_TYPE_POSTALCODE.pid)
{
hr = InitPropVariantFromString(m_postalcode, pValue);
}
else if (pKey.pid == SENSOR_DATA_TYPE_COUNTRY_REGION.pid)
{
hr = InitPropVariantFromString(m_countryregion, pValue);
}
// properties for latitude/longitude reports
else if (pKey.pid == SENSOR_DATA_TYPE_LATITUDE_DEGREES.pid)
{
hr = InitPropVariantFromDouble(m_latitude, pValue);
}
else if (pKey.pid == SENSOR_DATA_TYPE_LONGITUDE_DEGREES.pid)
{
hr = InitPropVariantFromDouble(m_longitude, pValue);
}
else if (pKey.pid == SENSOR_DATA_TYPE_ERROR_RADIUS_METERS.pid)
{
hr = InitPropVariantFromDouble(m_errorradius, pValue);
}
else
{
hr = HRESULT_FROM_WIN32(ERROR_NO_DATA);
PropVariantInit(pValue);
}
}
return hr;
}
要求
| 要求 | 值 |
|---|---|
| 最低受支持的客户端 | Windows 7 [仅限桌面应用]，Windows 7 |
| 最低受支持的服务器 | 无受支持的版本 |
| 目标平台 | Windows |
| 标头 | locationapi.h |
| DLL | LocationAPI.dll |