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 的位置感測器數據類型區段中。
以下是一些平臺定義屬性的數據表，這些屬性通常與位置報表相關聯。 這些屬性索引鍵的 fmtid 字段等於 SENSOR_DATA_TYPE_LOCATION_GUID。 您可以在 sensors.h 中找到其他屬性。 如果您要實作自己的位置報表以傳遞至 SetReport，此數據表會指出報表物件的 GetValue 實作中必須提供哪些值。
| 屬性索引鍵名稱和類型 | Description |
|---|---|
| SENSOR_DATA_TYPE_LATITUDE VT_R8 | North 為正數的緯度。
注意 傳遞至 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 | 相對於 true 的標題，以度為單位。 |
| 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。
| 屬性索引鍵名稱和類型 | Description |
|---|---|
| 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 |