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

Artículo
03/14/2023

[La API de ubicación de Win32 está disponible para su uso en los sistemas operativos especificados en la sección Requisitos. En versiones posteriores podría modificarse o no estar disponible. En su lugar, use la API Windows.Devices.Geolocation . ]

Recupera un valor de propiedad del informe de ubicación.

Sintaxis

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

Parámetros

[in] pKey

REFPROPERTYKEY que especifica el nombre de la propiedad que se va a recuperar.

[out] pValue

Dirección de un PROPVARIANT que recibe el valor de la propiedad.

Valor devuelto

Si este método se realiza correctamente, devuelve S_OK. De lo contrario, devuelve un código de error de HRESULT.

Comentarios

Las propiedades pueden ser definidas por la plataforma o por el fabricante.

Los valores PROPERTYKEY definidos por la plataforma para los sensores de ubicación se definen en la sección de tipos de datos del sensor de ubicación de sensors.h.

A continuación se muestra una tabla de algunas propiedades definidas por la plataforma que suelen asociarse con informes de ubicación. Estas claves de propiedad tienen un campo fmtid igual a SENSOR_DATA_TYPE_LOCATION_GUID. Se pueden encontrar propiedades adicionales en sensors.h. Si va a implementar su propio informe de ubicación para pasar a SetReport, esta tabla indica qué valores se deben proporcionar en la implementación de GetValue del objeto de informe.

Nombre y tipo de clave de propiedad	Descripción
SENSOR_DATA_TYPE_LATITUDE VT_R8	Latitud de grados donde norte es positivo. Nota Un objeto de informe de latitud y longitud que se pasa a SetReport debe proporcionar este valor en su implementación de GetValue.
SENSOR_DATA_TYPE_LONGITUDE VT_R8	Longitud de grados donde Este es positivo. Nota Un objeto de informe de latitud y longitud que se pasa a SetReport debe proporcionar este valor en su implementación de GetValue.
SENSOR_DATA_TYPE_ALTITUDE_SEALEVEL_METERS VT_R8	Altitud con respecto al nivel del mar, en metros.
SENSOR_DATA_TYPE_ALTITUDE_ELLIPSOID_METERS VT_R8	Altitud con respecto al elipsoide de referencia, en metros.
SENSOR_DATA_TYPE_SPEED_KNOTS VT_R8	Velocidad medida en nudos.
SENSOR_DATA_TYPE_TRUE_HEADING_DEGREES VT_R8	Encabezado relativo al norte verdadero en grados.
SENSOR_DATA_TYPE_MAGNETIC_HEADING_DEGREES VT_R8	Encabezado relativo al norte magnético en grados.
SENSOR_DATA_TYPE_MAGNETIC_VARIATION VT_R8	Variación magnética. Este es positivo.
SENSOR_DATA_TYPE_ERROR_RADIUS_METERS VT_R8	Radio de error que indica la precisión de latitud y longitud en metros. Nota Un objeto de informe de latitud y longitud que se pasa a SetReport debe proporcionar este valor en su implementación de GetValue.
SENSOR_DATA_TYPE_ADDRESS1 VT_LPWSTR	Primera línea de la dirección en un informe de direcciones civiles. Nota Si un objeto de informe de dirección civil que se pasa a SetReport contiene estos datos, debe proporcionar este valor en su implementación de GetValue.
SENSOR_DATA_TYPE_ADDRESS2 VT_LPWSTR	Segunda línea de la dirección en un informe de direcciones civiles. Nota Si un objeto de informe de dirección civil que se pasa a SetReport contiene estos datos, debe proporcionar este valor en su implementación de GetValue.
SENSOR_DATA_TYPE_CITY VT_LPWSTR	Campo Ciudad en un informe de direcciones civiles. Nota Si un objeto de informe de dirección civil que se pasa a SetReport contiene estos datos, debe proporcionar este valor en su implementación de GetValue.
SENSOR_DATA_TYPE_STATE_PROVINCE VT_LPWSTR	Campo Estado o provincia en un informe de direcciones civiles. Nota Si un objeto de informe de dirección civil que se pasa a SetReport contiene estos datos, debe proporcionar este valor en su implementación de GetValue.
SENSOR_DATA_TYPE_POSTALCODE VT_LPWSTR	Campo de código postal en un informe de direcciones civiles. Nota Si un objeto de informe de dirección civil que se pasa a SetReport contiene estos datos, debe proporcionar este valor en su implementación de GetValue.
SENSOR_DATA_TYPE_COUNTRY_REGION VT_LPWSTR	Código de país o región en un informe de direcciones civiles. El valor debe ser un código de país ISO 3166 de dos letras o de tres letras. Nota Un objeto de informe de dirección civil que se pasa a SetReport debe proporcionar este valor en su implementación de GetValue.
SENSOR_DATA_TYPE_ALTITUDE_ELLIPSOID_ERROR_METERS VT_R8	Error de altitud con respecto al elipsoide de referencia, en metros.
SENSOR_DATA_TYPE_ALTITUDE_SEALEVEL_ERROR_METERS VT_R8	Error de altitud con respecto al nivel del mar, en metros.

A continuación se muestra una tabla de otras propiedades definidas por la plataforma que pueden producirse en los informes de ubicación, pero que no son específicas de la ubicación. El campo fmtid de estas claves de propiedad es SENSOR_PROPERTY_COMMON_GUID.

Nombre y tipo de clave de propiedad	Descripción
SENSOR_PROPERTY_ACCURACY VT_UNKNOWN	Objeto IPortableDeviceValues que contiene nombres de tipo de datos de sensor y sus precisiones asociadas. Los valores de precisión representan una posible variación de los valores true. Los valores de precisión se expresan utilizando las mismas unidades que el campo de datos, excepto cuando se documentan de otro modo.
SENSOR_PROPERTY_CHANGE_SENSITIVITY VT_UNKNOWN	Objeto IPortableDeviceValues que contiene nombres de tipo de datos de sensor y sus valores de confidencialidad de cambio asociados. Los valores de confidencialidad de cambio representan la cantidad por la que el campo de datos debe cambiar antes de que se genere el evento SENSOR_EVENT_DATA_UPDATED. Los valores de confidencialidad se expresan utilizando las mismas unidades que el campo de datos, excepto cuando se documentan de otro modo. Por ejemplo, un valor de sensibilidad de cambio de 2 para SENSOR_DATA_TYPE_TEMPERATURE_CELSIUS representaría una sensibilidad de más o menos 2 grados centígrados.
SENSOR_PROPERTY_CURRENT_CONNECTION_TYPE VT_UI4	Valor sensorConnectionType que contiene el tipo de conexión actual.
SENSOR_PROPERTY_CURRENT_REPORT_INTERVAL VT_UI4	Tiempo transcurrido actual para la generación de informes de datos del sensor, en milisegundos. Establecer un valor de cero indica al controlador que use su intervalo de informe predeterminado. Después de recibir un valor de cero para esta propiedad, un controlador debe devolver su intervalo de informe predeterminado, no cero, cuando se consulta. Las aplicaciones pueden establecer este valor para solicitar un intervalo de informe determinado, pero es posible que varias aplicaciones usen el mismo controlador. Por lo tanto, los controladores determinan el intervalo de informe verdadero que se basa en la lógica interna. Por ejemplo, el controlador siempre puede usar el intervalo de informe más corto solicitado por el autor de la llamada.
SENSOR_PROPERTY_DESCRIPTION VT_LPWSTR	Cadena de descripción del sensor.
SENSOR_PROPERTY_DEVICE_PATH VT_LPWSTR	Identifica de forma única la instancia del dispositivo con la que está asociado el sensor. Puede usar esta propiedad para determinar si un dispositivo contiene varios sensores. Los controladores de dispositivo no tienen que admitir esta propiedad porque la plataforma proporciona este valor a las aplicaciones sin consultar controladores.
SENSOR_PROPERTY_FRIENDLY_NAME VT_LPWSTR	Nombre descriptivo del dispositivo.
SENSOR_PROPERTY_LOCATION_DESIRED_ACCURACY VT_UI4	Valor enumerado que indica el tipo de control de precisión solicitado por una aplicación cliente. LOCATION_DESIRED_ACCURACY_DEFAULT (0) indica que el sensor debe usar la precisión para la que puede optimizar el uso de energía y otras consideraciones de costos. LOCATION_DESIRED_ACCURACY_HIGH (1) indica que el sensor debe entregar el informe más preciso posible. Para ello, pueden usarse servicios que no son gratuitos o aumentar el consumo de energía de la batería o del ancho de banda de la conexión.
SENSOR_PROPERTY_MANUFACTURER VT_LPWSTR	Nombre del fabricante.
SENSOR_PROPERTY_MIN_REPORT_INTERVAL VT_UI4	La configuración de tiempo mínimo transcurrido que admite el hardware para la generación de informes de datos del sensor, en milisegundos.
SENSOR_PROPERTY_MODEL VT_LPWSTR	Nombre del modelo de sensor.
SENSOR_PROPERTY_PERSISTENT_UNIQUE_ID VT_CLSID	GUID que identifica el sensor. Este valor debe ser único para cada sensor de un dispositivo o en todos los dispositivos del mismo modelo que se enumeran en el equipo.
SENSOR_PROPERTY_RANGE_MAXIMUM VT_UKNOWN	Objeto IPortableDeviceValues que contiene nombres de campo de datos del sensor y sus valores máximos asociados.
VT_UKNOWN de SENSOR_PROPERTY_RANGE_MINIMUM	Objeto IPortableDeviceValues que contiene nombres de campo de datos del sensor y sus valores mínimos asociados.
SENSOR_PROPERTY_RESOLUTION VT_UKNOWN	Objeto IPortableDeviceValues que contiene nombres de campo de datos del sensor y sus resoluciones asociadas. Los valores de resolución representan la confidencialidad para cambiar en el campo de datos. Los valores de resolución se expresan mediante las mismas unidades que el campo de datos, excepto cuando se documentan de otro modo.
SENSOR_PROPERTY_SERIAL_NUMBER VT_LPWSTR	Número de serie del sensor.
SENSOR_PROPERTY_STATE VT_UI4	Valor sensorState que contiene el estado actual del sensor.
SENSOR_PROPERTY_TYPE VT_CLSID	GUID que identifica el tipo de sensor. Los tipos de sensor definidos por la plataforma se definen en Sensors.h.

Ejemplos

En el ejemplo siguiente se muestra cómo llamar a GetValue para obtener un valor de propiedad. Debe incluir sensors.h para usar la constante en el ejemplo.


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

En el ejemplo siguiente se muestra cómo implementar GetValue en su propio objeto de informe. Esta implementación permite al autor de la llamada obtener valores para varios campos de informe de ubicación. Este código requiere que incluya sensors.h y 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	Value
Cliente mínimo compatible	Windows 7 [solo aplicaciones de escritorio],Windows 7
Servidor mínimo compatible	No se admite ninguno
Plataforma de destino	Windows
Encabezado	locationapi.h
Archivo DLL	LocationAPI.dll

Consulte también

ILocationReport

Compartir a través de

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

Sintaxis

Parámetros

Valor devuelto

Comentarios

Ejemplos

Requisitos

Consulte también

Comentarios

Recursos adicionales