Método ILocationReport::GetValue (locationapi.h)

Artigo
03/14/2023

[A API de Localização do Win32 está disponível para uso nos sistemas operacionais especificados na seção Requisitos. Ele poderá ser alterado ou ficar indisponível em versões subsequentes. Em vez disso, use a API Windows.Devices.Geolocation . ]

Recupera um valor de propriedade do relatório de localização.

Sintaxe

HRESULT GetValue(
  [in]  REFPROPERTYKEY pKey,
  [out] PROPVARIANT    *pValue
);

Parâmetros

[in] pKey

REFPROPERTYKEY que especifica o nome da propriedade a ser recuperada.

[out] pValue

Endereço de um PROPVARIANT que recebe o valor da propriedade.

Retornar valor

Se o método for bem-sucedido, ele retornará S_OK. Caso contrário, ele retornará um código de erro HRESULT.

Comentários

As propriedades podem ser definidas pela plataforma ou pelo fabricante.

Os valores PROPERTYKEY definidos pela plataforma para sensores de localização são definidos na seção tipos de dados do sensor de localização de sensors.h.

Veja a seguir uma tabela de algumas propriedades definidas pela plataforma que normalmente são associadas a relatórios de localização. Essas chaves de propriedade têm um campo fmtid igual a SENSOR_DATA_TYPE_LOCATION_GUID. Propriedades adicionais podem ser encontradas em sensors.h. Se você estiver implementando seu próprio relatório de localização para passar para SetReport, esta tabela indicará quais valores devem ser fornecidos na implementação de GetValue do objeto de relatório.

Nome e tipo da chave de propriedade	Descrição
SENSOR_DATA_TYPE_LATITUDE VT_R8	Graus de latitude onde Norte é positivo. Nota Um objeto de relatório de latitude/longitude que é passado para SetReport deve fornecer esse valor em sua implementação de GetValue.
VT_R8 SENSOR_DATA_TYPE_LONGITUDE	Graus longitude onde Leste é positivo. Nota Um objeto de relatório de latitude/longitude que é passado para SetReport deve fornecer esse valor em sua implementação de GetValue.
SENSOR_DATA_TYPE_ALTITUDE_SEALEVEL_METERS VT_R8	Altitude em relação ao nível do mar, em metros.
SENSOR_DATA_TYPE_ALTITUDE_ELLIPSOID_METERS VT_R8	Altitude em relação ao elipsoide de referência, em metros.
SENSOR_DATA_TYPE_SPEED_KNOTS VT_R8	Velocidade medida em nós.
SENSOR_DATA_TYPE_TRUE_HEADING_DEGREES VT_R8	Indo em relação ao norte verdadeiro em graus.
SENSOR_DATA_TYPE_MAGNETIC_HEADING_DEGREES VT_R8	Indo em relação ao norte magnético em graus.
SENSOR_DATA_TYPE_MAGNETIC_VARIATION VT_R8	Variação magnética. Leste é positivo.
SENSOR_DATA_TYPE_ERROR_RADIUS_METERS VT_R8	Raio de erro que indica a precisão da latitude e da longitude em metros. Nota Um objeto de relatório de latitude/longitude que é passado para SetReport deve fornecer esse valor em sua implementação de GetValue.
SENSOR_DATA_TYPE_ADDRESS1 VT_LPWSTR	Primeira linha do endereço em um relatório de endereço cívico. Nota Se um objeto de relatório de endereço cívico passado para SetReport contiver esses dados, ele deverá fornecer esse valor em sua implementação de GetValue.
SENSOR_DATA_TYPE_ADDRESS2 VT_LPWSTR	Segunda linha do endereço em um relatório de endereço cívico. Nota Se um objeto de relatório de endereço cívico passado para SetReport contiver esses dados, ele deverá fornecer esse valor em sua implementação de GetValue.
SENSOR_DATA_TYPE_CITY VT_LPWSTR	Campo da cidade em um relatório de endereço cívico. Nota Se um objeto de relatório de endereço cívico passado para SetReport contiver esses dados, ele deverá fornecer esse valor em sua implementação de GetValue.
SENSOR_DATA_TYPE_STATE_PROVINCE VT_LPWSTR	Campo estado/província em um relatório de endereço cívico. Nota Se um objeto de relatório de endereço cívico passado para SetReport contiver esses dados, ele deverá fornecer esse valor em sua implementação de GetValue.
SENSOR_DATA_TYPE_POSTALCODE VT_LPWSTR	Campo cep em um relatório de endereço cívico. Nota Se um objeto de relatório de endereço cívico passado para SetReport contiver esses dados, ele deverá fornecer esse valor em sua implementação de GetValue.
SENSOR_DATA_TYPE_COUNTRY_REGION VT_LPWSTR	Código de país/região em um relatório de endereço cívico. O valor deve ser um código de país ISO 3166 de duas ou três letras. Nota Um objeto de relatório de endereço cívico passado para SetReport deve fornecer esse valor em sua implementação de GetValue.
SENSOR_DATA_TYPE_ALTITUDE_ELLIPSOID_ERROR_METERS VT_R8	Erro de altitude em relação ao elipsoide de referência, em metros.
SENSOR_DATA_TYPE_ALTITUDE_SEALEVEL_ERROR_METERS VT_R8	Erro de altitude em relação ao nível do mar, em metros.

Veja a seguir uma tabela de outras propriedades definidas pela plataforma que podem ocorrer em relatórios de localização, mas não são específicas do local. O campo fmtid dessas chaves de propriedade é SENSOR_PROPERTY_COMMON_GUID.

Nome e tipo da chave de propriedade	Descrição
SENSOR_PROPERTY_ACCURACY VT_UNKNOWN	Objeto IPortableDeviceValues que contém nomes de tipo de dados do sensor e suas precisões associadas. Os valores de precisão representam uma possível variação dos valores verdadeiros. Os valores de precisão são expressos usando as mesmas unidades que o campo de dados, exceto quando documentado de outra forma.
VT_UNKNOWN SENSOR_PROPERTY_CHANGE_SENSITIVITY	Objeto IPortableDeviceValues que contém nomes de tipo de dados do sensor e seus valores de confidencialidade de alteração associados. Os valores de confidencialidade de alteração representam a quantidade pela qual o campo de dados deve ser alterado antes que o evento SENSOR_EVENT_DATA_UPDATED seja acionado. Os valores de confidencialidade são expressos usando as mesmas unidades que o campo de dados, exceto quando documentado de outra forma. Por exemplo, um valor de confidencialidade de alteração de 2 para SENSOR_DATA_TYPE_TEMPERATURE_CELSIUS representaria uma sensibilidade de mais ou menos 2 graus Celsius.
SENSOR_PROPERTY_CURRENT_CONNECTION_TYPE VT_UI4	Valor SensorConnectionType que contém o tipo de conexão atual.
VT_UI4 SENSOR_PROPERTY_CURRENT_REPORT_INTERVAL	O tempo decorrido atual para a geração de relatórios de dados do sensor, em milissegundos. Definir um valor zero sinaliza que o driver use seu intervalo de relatório padrão. Depois de receber um valor zero para essa propriedade, um driver deve retornar seu intervalo de relatório padrão, não zero, quando consultado. Os aplicativos podem definir esse valor para solicitar um intervalo de relatório específico, mas vários aplicativos podem estar usando o mesmo driver. Portanto, os drivers determinam o intervalo de relatório verdadeiro baseado na lógica interna. Por exemplo, o driver sempre pode usar o intervalo de relatório mais curto solicitado pelo chamador.
SENSOR_PROPERTY_DESCRIPTION VT_LPWSTR	A cadeia de caracteres de descrição do sensor.
SENSOR_PROPERTY_DEVICE_PATH VT_LPWSTR	Identifica exclusivamente a instância do dispositivo à qual o sensor está associado. Você pode usar essa propriedade para determinar se um dispositivo contém vários sensores. Os drivers de dispositivo não precisam dar suporte a essa propriedade porque a plataforma fornece esse valor para aplicativos sem consultar drivers.
SENSOR_PROPERTY_FRIENDLY_NAME VT_LPWSTR	O nome amigável do dispositivo.
VT_UI4 SENSOR_PROPERTY_LOCATION_DESIRED_ACCURACY	Um valor enumerado que indica o tipo de tratamento de precisão solicitado por um aplicativo cliente. LOCATION_DESIRED_ACCURACY_DEFAULT (0) indica que o sensor deve usar a precisão para a qual pode otimizar o uso de energia e outras considerações de custo. LOCATION_DESIRED_ACCURACY_HIGH (1) indica que o sensor deve fornecer o relatório mais preciso possível. Isso inclui usar serviços que podem cobrar dinheiro ou consumir níveis mais altos de energia da bateria ou largura de banda da conexão.
SENSOR_PROPERTY_MANUFACTURER VT_LPWSTR	O nome do fabricante.
SENSOR_PROPERTY_MIN_REPORT_INTERVAL VT_UI4	A configuração de tempo decorrido mínima à qual o hardware dá suporte para a geração de relatórios de dados do sensor, em milissegundos.
SENSOR_PROPERTY_MODEL VT_LPWSTR	O nome do modelo do sensor.
SENSOR_PROPERTY_PERSISTENT_UNIQUE_ID VT_CLSID	Um GUID que identifica o sensor. Esse valor deve ser exclusivo para cada sensor em um dispositivo ou entre dispositivos do mesmo modelo que enumerados no computador.
SENSOR_PROPERTY_RANGE_MAXIMUM VT_UKNOWN	Objeto IPortableDeviceValues que contém nomes de campo de dados do sensor e seus valores máximos associados.
SENSOR_PROPERTY_RANGE_MINIMUM VT_UKNOWN	Objeto IPortableDeviceValues que contém nomes de campo de dados do sensor e seus valores mínimos associados.
SENSOR_PROPERTY_RESOLUTION VT_UKNOWN	Objeto IPortableDeviceValues que contém nomes de campo de dados do sensor e suas resoluções associadas. Os valores de resolução representam a sensibilidade à alteração no campo de dados. Os valores de resolução são expressos usando as mesmas unidades que o campo de dados, exceto quando documentado de outra forma.
SENSOR_PROPERTY_SERIAL_NUMBER VT_LPWSTR	O número de série do sensor.
VT_UI4 SENSOR_PROPERTY_STATE	Valor sensorState que contém o estado atual do sensor.
SENSOR_PROPERTY_TYPE VT_CLSID	Um GUID que identifica o tipo de sensor. Os tipos de sensor definidos pela plataforma são definidos em Sensors.h.

Exemplos

O exemplo a seguir demonstra como chamar GetValue para obter um valor de propriedade. Você deve incluir sensors.h para usar a constante no exemplo.


PROPVARIANT pv;				
HRESULT hr = spLatLongReport->GetValue(SENSOR_DATA_TYPE_LATITUDE_DEGREES, &pv);

O exemplo a seguir mostra como implementar GetValue em seu próprio objeto de relatório. Essa implementação permite que o chamador obtenha valores para vários campos de relatório de localização. Esse código exige que você inclua sensors.h e 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;
}

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 7 [somente aplicativos da área de trabalho], Windows 7
Servidor mínimo com suporte	Nenhum compatível
Plataforma de Destino	Windows
Cabeçalho	locationapi.h
DLL	LocationAPI.dll

Confira também

ILocationReport

Compartilhar via

Método ILocationReport::GetValue (locationapi.h)

Sintaxe

Parâmetros

Retornar valor

Comentários

Exemplos

Requisitos

Confira também

Comentários

Recursos adicionais