Метод ILocationReport::GetValue (locationapi.h)
[API расположения Win32 доступен для использования в операционных системах, указанных в разделе Требования. В последующих версиях он может быть изменен или недоступен. Вместо этого используйте API Windows.Devices.Geolocation . ]
Извлекает значение свойства из отчета о расположении.
Синтаксис
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 объекта отчета.
| Имя и тип ключа свойства | Описание |
|---|---|
| SENSOR_DATA_TYPE_LATITUDE VT_R8 | Градусы широты, где север положительный.
Примечание Объект отчета широты/долготы, передаваемый в SetReport , должен предоставлять это значение в своей реализации GetValue.
|
| VT_R8 SENSOR_DATA_TYPE_LONGITUDE | Градусы долготы, где восток положительный.
Примечание Объект отчета широты/долготы, передаваемый в SetReport , должен предоставлять это значение в своей реализации GetValue.
|
| VT_R8 SENSOR_DATA_TYPE_ALTITUDE_SEALEVEL_METERS | Высота по отношению к уровню моря, в метрах. |
| SENSOR_DATA_TYPE_ALTITUDE_ELLIPSOID_METERS VT_R8 | Высота по отношению к эталонной эллипсоиде, в метрах. |
| SENSOR_DATA_TYPE_SPEED_KNOTS VT_R8 | Скорость измеряется в узлах. |
| SENSOR_DATA_TYPE_TRUE_HEADING_DEGREES VT_R8 | Направление относительно истинного севера в градусах. |
| VT_R8 SENSOR_DATA_TYPE_MAGNETIC_HEADING_DEGREES | Направление относительно магнитного севера в градусах. |
| SENSOR_DATA_TYPE_MAGNETIC_VARIATION VT_R8 | Магнитные вариации. Восток является позитивным. |
| VT_R8 SENSOR_DATA_TYPE_ERROR_RADIUS_METERS | Радиус ошибки, указывающий точность широты и долготы в метрах.
Примечание Объект отчета широты/долготы, передаваемый в SetReport , должен предоставлять это значение в своей реализации GetValue.
|
| VT_LPWSTR SENSOR_DATA_TYPE_ADDRESS1 | Первая строка адреса в отчете о гражданских адресах.
Примечание Если объект отчета по гражданскому адресу, передаваемый в SetReport , содержит эти данные, он должен предоставить это значение в своей реализации GetValue.
|
| VT_LPWSTR SENSOR_DATA_TYPE_ADDRESS2 | Вторая строка адреса в гражданском адресном отчете. Примечание Если объект отчета по гражданскому адресу, передаваемый в SetReport , содержит эти данные, он должен предоставить это значение в своей реализации GetValue.
|
| SENSOR_DATA_TYPE_CITY VT_LPWSTR | Поле "Город" в отчете с гражданским адресом. Примечание Если объект отчета по гражданскому адресу, передаваемый в SetReport , содержит эти данные, он должен предоставить это значение в своей реализации GetValue.
|
| VT_LPWSTR SENSOR_DATA_TYPE_STATE_PROVINCE | Поле штата или провинции в отчете об обращении с гражданскими адресами. Примечание Если объект отчета по гражданскому адресу, передаваемый в SetReport , содержит эти данные, он должен предоставить это значение в своей реализации GetValue.
|
| VT_LPWSTR SENSOR_DATA_TYPE_POSTALCODE | Поле почтового индекса в отчете о гражданских адресах. Примечание Если объект отчета по гражданскому адресу, передаваемый в SetReport , содержит эти данные, он должен предоставить это значение в своей реализации GetValue.
|
| VT_LPWSTR SENSOR_DATA_TYPE_COUNTRY_REGION | Код страны или региона в отчете о гражданских адресах. Значение должно быть двухбуквенный или трехбуквенный код страны ISO 3166.
Примечание Объект отчета по гражданским адресам, передаваемый в SetReport , должен предоставлять это значение в своей реализации GetValue.
|
| VT_R8 SENSOR_DATA_TYPE_ALTITUDE_ELLIPSOID_ERROR_METERS | Погрешность высоты относительно ссылочного эллипсоида в метрах. |
| VT_R8 SENSOR_DATA_TYPE_ALTITUDE_SEALEVEL_ERROR_METERS | Погрешность высоты относительно уровня моря, в метрах. |
Ниже приведена таблица других определяемых платформой свойств, которые могут содержаться в отчетах о расположении, но не относятся к расположению. Поле fmtid этих ключей свойств SENSOR_PROPERTY_COMMON_GUID.
| Имя и тип ключа свойства | Описание |
|---|---|
| VT_UNKNOWN SENSOR_PROPERTY_ACCURACY | Объект IPortableDeviceValues, содержащий имена типов данных датчика и связанные с ними точность. Значения точности представляют собой возможные отклонения от истинных значений.
Значения точности выражаются с использованием той же единицы измерения, что и поле данных, за исключением случаев, когда задокументировано иное. |
| SENSOR_PROPERTY_CHANGE_SENSITIVITY VT_UNKNOWN |
Объект IPortableDeviceValues, содержащий имена типов данных датчика и связанные с ними значения конфиденциальности изменений. Значения конфиденциальности изменения представляют величину, на которую поле данных должно измениться до возникновения события SENSOR_EVENT_DATA_UPDATED.
Значения конфиденциальности выражаются с использованием тех же единиц, что и поле данных, за исключением случаев, когда иное задокументировано. Например, значение чувствительности изменения, равное 2 для SENSOR_DATA_TYPE_TEMPERATURE_CELSIUS, будет представлять чувствительность плюс или минус 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 |
Уникально идентифицирует экземпляр устройства, с которым связан датчик. Это свойство можно использовать, чтобы определить, содержит ли устройство несколько датчиков.
Драйверы устройств не должны поддерживать это свойство, так как платформа предоставляет это значение приложениям без запросов к драйверам. |
| VT_LPWSTR SENSOR_PROPERTY_FRIENDLY_NAME | Понятное имя устройства. |
| VT_UI4 SENSOR_PROPERTY_LOCATION_DESIRED_ACCURACY | Перечислимое значение, указывающее тип обработки точности, запрошенной клиентским приложением. LOCATION_DESIRED_ACCURACY_DEFAULT (0) означает, что датчик должен использовать точность, для которой он может оптимизировать энергопотребление, и другие аспекты затрат.
LOCATION_DESIRED_ACCURACY_HIGH (1) указывает, что датчик должен предоставлять наиболее точный отчет. Это касается использования услуг по взиманию средств, потребления высокого уровня мощности батарей или пропускной способности подключения. |
| SENSOR_PROPERTY_MANUFACTURER VT_LPWSTR | Имя производителя. |
| SENSOR_PROPERTY_MIN_REPORT_INTERVAL VT_UI4 | Параметр минимального затраченного времени, поддерживаемый оборудованием для создания отчетов о данных датчиков, в миллисекундах. |
| VT_LPWSTR SENSOR_PROPERTY_MODEL | Имя модели датчика. |
| VT_CLSID SENSOR_PROPERTY_PERSISTENT_UNIQUE_ID | GUID, идентифицирующий датчик. Это значение должно быть уникальным для каждого датчика на устройстве или на устройствах с той же моделью, что и на компьютере. |
| VT_UKNOWN SENSOR_PROPERTY_RANGE_MAXIMUM | Объект IPortableDeviceValues, содержащий имена полей данных датчика и связанные с ними максимальные значения. |
| VT_UKNOWN SENSOR_PROPERTY_RANGE_MINIMUM | Объект IPortableDeviceValues, содержащий имена полей данных датчика и связанные с ними минимальные значения. |
| VT_UKNOWN SENSOR_PROPERTY_RESOLUTION | Объект IPortableDeviceValues, содержащий имена полей данных датчика и связанные с ними разрешения. Значения разрешения представляют чувствительность к изменению в поле данных.
Значения разрешения выражаются с использованием той же единицы измерения, что и поле данных, за исключением случаев, когда задокументировано иное. |
| SENSOR_PROPERTY_SERIAL_NUMBER VT_LPWSTR | Серийный номер датчика. |
| VT_UI4 SENSOR_PROPERTY_STATE | Значение SensorState, содержащее текущее состояние датчика. |
| VT_CLSID SENSOR_PROPERTY_TYPE | 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 |
| Header | locationapi.h |
| DLL | LocationAPI.dll |