ILocationReport::GetValue-Methode (locationapi.h)

Artikel
02/28/2024

[Die Win32-Standort-API ist für die Verwendung in den im Abschnitt Anforderungen angegebenen Betriebssystemen verfügbar. Es kann in nachfolgenden Versionen geändert oder entfernt werden. Verwenden Sie stattdessen die Windows.Devices.Geolocation-API . ]

Ruft einen Eigenschaftswert aus dem Standortbericht ab.

Syntax

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

Parameter

[in] pKey

REFPROPERTYKEY , der den Namen der abzurufenden Eigenschaft angibt.

[out] pValue

Adresse eines PROPVARIANT-Objekts , das den Eigenschaftswert empfängt.

Rückgabewert

Wenn diese Methode erfolgreich ist, wird S_OK zurückgegeben. Andernfalls wird ein Fehlercode HRESULT zurückgegeben.

Hinweise

Die Eigenschaften können plattformdefiniert oder vom Hersteller definiert sein.

Plattformdefinierte PROPERTYKEY-Werte für Positionssensoren werden im Abschnitt location sensor data types von sensors.h definiert.

Die folgende Tabelle enthält einige plattformdefinierte Eigenschaften, die häufig mit Standortberichten in Verbindung stehen. Diese Eigenschaftsschlüssel verfügen über ein fmtid-Feld gleich SENSOR_DATA_TYPE_LOCATION_GUID. Weitere Eigenschaften finden Sie unter sensors.h. Wenn Sie einen eigenen Standortbericht implementieren, der an SetReport übergeben werden soll, gibt diese Tabelle an, welche Werte in der GetValue-Implementierung Ihres Berichtsobjekts angegeben werden müssen.

Name und Typ des Eigenschaftsschlüssels	BESCHREIBUNG
SENSOR_DATA_TYPE_LATITUDE VT_R8	Grad Breitengrad, bei dem Nord positiv ist. Hinweis Ein An SetReport übergebenes Breiten-/Längengrad-Berichtsobjekt muss diesen Wert in der Implementierung von GetValue bereitstellen.
SENSOR_DATA_TYPE_LONGITUDE VT_R8	Längengrad, wobei Der Osten positiv ist. Hinweis Ein An SetReport übergebenes Breiten-/Längengrad-Berichtsobjekt muss diesen Wert in der Implementierung von GetValue bereitstellen.
SENSOR_DATA_TYPE_ALTITUDE_SEALEVEL_METERS VT_R8	Höhe in Bezug auf den Meeresspiegel in Metern.
SENSOR_DATA_TYPE_ALTITUDE_ELLIPSOID_METERS VT_R8	Höhe in Bezug auf das Referenzellipsoid in Metern.
SENSOR_DATA_TYPE_SPEED_KNOTS VT_R8	In Knoten gemessene Geschwindigkeit.
SENSOR_DATA_TYPE_TRUE_HEADING_DEGREES VT_R8	Relativ zu true nord in Grad.
SENSOR_DATA_TYPE_MAGNETIC_HEADING_DEGREES VT_R8	Relativ zum magnetischen Norden in Grad.
SENSOR_DATA_TYPE_MAGNETIC_VARIATION VT_R8	Magnetische Variation. Der Osten ist positiv.
SENSOR_DATA_TYPE_ERROR_RADIUS_METERS VT_R8	Fehlerradius, der die Genauigkeit des Breiten- und Längengrads in Metern angibt. Hinweis Ein An SetReport übergebenes Breiten-/Längengrad-Berichtsobjekt muss diesen Wert in der Implementierung von GetValue bereitstellen.
SENSOR_DATA_TYPE_ADDRESS1 VT_LPWSTR	Erste Zeile der Adresse in einem Bürgeradressenbericht. Hinweis Wenn ein an SetReport übergebenes Objekt für zivile Adressen diese Daten enthält, sollte es diesen Wert in der Implementierung von GetValue angeben.
SENSOR_DATA_TYPE_ADDRESS2 VT_LPWSTR	Zweite Zeile der Adresse in einem Bürgeradressenbericht. Hinweis Wenn ein an SetReport übergebenes Objekt für zivile Adressen diese Daten enthält, sollte es diesen Wert in der Implementierung von GetValue angeben.
SENSOR_DATA_TYPE_CITY VT_LPWSTR	Feld "Ort" in einem Bürgeradressenbericht. Hinweis Wenn ein an SetReport übergebenes Objekt für zivile Adressen diese Daten enthält, sollte es diesen Wert in der Implementierung von GetValue angeben.
SENSOR_DATA_TYPE_STATE_PROVINCE VT_LPWSTR	Feld "Bundesland/Provinz" in einem Bürgeradressenbericht. Hinweis Wenn ein an SetReport übergebenes Objekt für zivile Adressen diese Daten enthält, sollte es diesen Wert in der Implementierung von GetValue angeben.
SENSOR_DATA_TYPE_POSTALCODE VT_LPWSTR	Postleitzahlfeld in einem Bürgeradressenbericht. Hinweis Wenn ein an SetReport übergebenes Objekt für zivile Adressen diese Daten enthält, sollte es diesen Wert in der Implementierung von GetValue angeben.
SENSOR_DATA_TYPE_COUNTRY_REGION VT_LPWSTR	Landes-/Regionscode in einem Bürgeradressenbericht. Der Wert muss aus zwei oder drei Buchstaben iso 3166-Ländercode sein. Hinweis Ein an SetReport übergebenes Objekt für zivile Adressen muss diesen Wert in der Implementierung von GetValue bereitstellen.
SENSOR_DATA_TYPE_ALTITUDE_ELLIPSOID_ERROR_METERS VT_R8	Höhenfehler in Bezug auf das Referenzellipsoid in Metern.
SENSOR_DATA_TYPE_ALTITUDE_SEALEVEL_ERROR_METERS VT_R8	Höhenfehler in Bezug auf den Meeresspiegel in Metern.

Im Folgenden finden Sie eine Tabelle mit anderen plattformdefinierte Eigenschaften, die möglicherweise in Standortberichten vorkommen, aber nicht standortspezifisch sind. Das Fmtid-Feld dieser Eigenschaftenschlüssel ist SENSOR_PROPERTY_COMMON_GUID.

Name und Typ des Eigenschaftsschlüssels	BESCHREIBUNG
SENSOR_PROPERTY_ACCURACY VT_UNKNOWN	IPortableDeviceValues-Objekt, das Sensordatentypnamen und die zugehörigen Genauigkeiten enthält. Genauigkeitswerte stellen eine mögliche Abweichung von true-Werten dar. Genauigkeitswerte werden mit den gleichen Einheiten wie das Datenfeld ausgedrückt, sofern nicht anders dokumentiert.
SENSOR_PROPERTY_CHANGE_SENSITIVITY VT_UNKNOWN	IPortableDeviceValues-Objekt , das Sensordatentypnamen und die zugehörigen Änderungsempfindlichkeitswerte enthält. Änderungsempfindlichkeitswerte stellen die Menge dar, um die sich das Datenfeld ändern muss, bevor das SENSOR_EVENT_DATA_UPDATED-Ereignis ausgelöst wird. Vertraulichkeitswerte werden mithilfe der gleichen Einheiten wie das Datenfeld ausgedrückt, sofern nicht anders dokumentiert. Beispielsweise würde ein Änderungsempfindlichkeitswert von 2 für SENSOR_DATA_TYPE_TEMPERATURE_CELSIUS eine Empfindlichkeit von plus oder minus 2 Grad Celsius darstellen.
SENSOR_PROPERTY_CURRENT_CONNECTION_TYPE VT_UI4	SensorConnectionType-Wert , der den aktuellen Verbindungstyp enthält.
SENSOR_PROPERTY_CURRENT_REPORT_INTERVAL VT_UI4	Die aktuell verstrichene Zeit für die Generierung von Sensordatenberichten in Millisekunden. Das Festlegen des Werts 0 (null) signalisiert dem Treiber, sein Standardberichtsintervall zu verwenden. Nachdem der Wert 0 (null) für diese Eigenschaft empfangen wurde, muss ein Treiber bei der Abfrage sein Standardberichtsintervall zurückgeben, nicht 0. Anwendungen können diesen Wert festlegen, um ein bestimmtes Berichtsintervall anzufordern, aber mehrere Anwendungen verwenden möglicherweise denselben Treiber. Daher bestimmen Treiber das wahre Berichtsintervall, das auf interner Logik basiert. Beispielsweise kann der Treiber immer das kürzeste Berichtsintervall verwenden, das vom Aufrufer angefordert wird.
SENSOR_PROPERTY_DESCRIPTION VT_LPWSTR	Die Sensorbeschreibungszeichenfolge.
SENSOR_PROPERTY_DEVICE_PATH VT_LPWSTR	Identifiziert eindeutig das Gerät instance, dem der Sensor zugeordnet ist. Sie können diese Eigenschaft verwenden, um zu bestimmen, ob ein Gerät mehrere Sensoren enthält. Gerätetreiber müssen diese Eigenschaft nicht unterstützen, da die Plattform diesen Wert für Anwendungen bereitstellt, ohne Treiber abzufragen.
SENSOR_PROPERTY_FRIENDLY_NAME VT_LPWSTR	Der Anzeigename für das Gerät.
SENSOR_PROPERTY_LOCATION_DESIRED_ACCURACY VT_UI4	Ein aufgezählter Wert, der die Art der Genauigkeitsbehandlung angibt, die von einer Clientanwendung angefordert wird. LOCATION_DESIRED_ACCURACY_DEFAULT (0) gibt an, dass der Sensor die Genauigkeit verwenden sollte, für die er die Energienutzung und andere Kostenaspekte optimieren kann. LOCATION_DESIRED_ACCURACY_HIGH (1) gibt an, dass der Sensor einen möglichst genauen Bericht liefern soll. Dies beinhaltet die Verwendung von kostenpflichtigen Diensten oder Diensten mit höherem Akkuverbrauch oder höherer Verbindungsbandbreite.
SENSOR_PROPERTY_MANUFACTURER VT_LPWSTR	Der Name des Herstellers.
SENSOR_PROPERTY_MIN_REPORT_INTERVAL VT_UI4	Die Mindesteinstellung für verstrichene Zeit, die die Hardware für die Generierung von Sensordatenberichten in Millisekunden unterstützt.
SENSOR_PROPERTY_MODEL VT_LPWSTR	Der Name des Sensormodells.
SENSOR_PROPERTY_PERSISTENT_UNIQUE_ID VT_CLSID	Eine GUID , die den Sensor identifiziert. Dieser Wert muss für jeden Sensor auf einem Gerät oder für Geräte mit demselben Modell wie auf dem Computer eindeutig sein.
SENSOR_PROPERTY_RANGE_MAXIMUM VT_UKNOWN	IPortableDeviceValues-Objekt , das Sensordatenfeldnamen und die zugehörigen Maximalwerte enthält.
SENSOR_PROPERTY_RANGE_MINIMUM VT_UKNOWN	IPortableDeviceValues-Objekt , das Sensordatenfeldnamen und die zugehörigen Mindestwerte enthält.
SENSOR_PROPERTY_RESOLUTION VT_UKNOWN	IPortableDeviceValues-Objekt , das Sensordatenfeldnamen und die zugehörigen Auflösungen enthält. Auflösungswerte stellen die Vertraulichkeit für Änderungen im Datenfeld dar. Auflösungswerte werden mit den gleichen Einheiten wie das Datenfeld ausgedrückt, sofern nicht anders dokumentiert.
SENSOR_PROPERTY_SERIAL_NUMBER VT_LPWSTR	Die Seriennummer des Sensors.
SENSOR_PROPERTY_STATE VT_UI4	SensorState-Wert , der den aktuellen Sensorzustand enthält.
SENSOR_PROPERTY_TYPE VT_CLSID	Eine GUID , die den Sensortyp identifiziert. Plattformdefinierte Sensortypen werden in Sensors.h definiert.

Beispiele

Im folgenden Beispiel wird veranschaulicht, wie GetValue aufgerufen wird, um einen Eigenschaftswert abzurufen. Sie müssen sensors.h einschließen, um die Konstante im Beispiel zu verwenden.


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

Das folgende Beispiel zeigt, wie Sie GetValue in Ihrem eigenen Berichtsobjekt implementieren. Diese Implementierung ermöglicht es dem Aufrufer, Werte für mehrere Speicherortberichtsfelder abzurufen. Für diesen Code müssen Sie sensors.h und provarutil.h einschließen.

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;
}

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 7 [nur Desktop-Apps],Windows 7
Unterstützte Mindestversion (Server)	Nicht unterstützt
Zielplattform	Windows
Kopfzeile	locationapi.h
DLL	LocationAPI.dll

Weitere Informationen

ILocationReport

Freigeben über