Metodo ILocationReport::GetValue (locationapi.h)
[L'API Percorso Win32 è disponibile per l'uso nei sistemi operativi specificati nella sezione Requisiti. È possibile che in versioni successive sia stata modificata o non sia più disponibile. Usare invece l'API Windows.Devices.Geolocation . ]
Recupera un valore della proprietà dal report della posizione.
Sintassi
HRESULT GetValue(
[in] REFPROPERTYKEY pKey,
[out] PROPVARIANT *pValue
);
Parametri
[in] pKey
REFPROPERTYKEY che specifica il nome della proprietà da recuperare.
[out] pValue
Indirizzo di un OGGETTO PROPVARIANT che riceve il valore della proprietà.
Valore restituito
Se questo metodo ha esito positivo, restituisce S_OK. In caso contrario, restituisce un codice di errore HRESULT .
Commenti
Le proprietà possono essere definite dalla piattaforma o dal produttore.
I valori PROPERTYKEY definiti dalla piattaforma per i sensori di posizione sono definiti nella sezione tipi di dati del sensore di posizione di sensors.h.
Di seguito è riportata una tabella di alcune proprietà definite dalla piattaforma che sono comunemente associate ai report di posizione. Queste chiavi di proprietà hanno un campo fmtid uguale a SENSOR_DATA_TYPE_LOCATION_GUID. Altre proprietà sono disponibili in sensors.h. Se si implementa un report di posizione personalizzato per passare a SetReport, questa tabella indica quali valori devono essere forniti nell'implementazione dell'oggetto report di GetValue.
| Nome della chiave di proprietà e tipo | Descrizione |
|---|---|
| SENSOR_DATA_TYPE_LATITUDE VT_R8 | Latitudine in cui il nord è positivo.
Nota Un oggetto report latitudine/longitudine passato a SetReport deve fornire questo valore nell'implementazione di GetValue.
|
| SENSOR_DATA_TYPE_LONGITUDE VT_R8 | Longitudine gradi in cui Est è positivo.
Nota Un oggetto report latitudine/longitudine passato a SetReport deve fornire questo valore nell'implementazione di GetValue.
|
| SENSOR_DATA_TYPE_ALTITUDE_SEALEVEL_METERS VT_R8 | Altitudine rispetto al livello del mare, in metri. |
| SENSOR_DATA_TYPE_ALTITUDE_ELLIPSOID_METERS VT_R8 | Altitudine rispetto ai puntini di sospensione del riferimento, in metri. |
| SENSOR_DATA_TYPE_SPEED_KNOTS VT_R8 | Velocità misurata in nodi. |
| SENSOR_DATA_TYPE_TRUE_HEADING_DEGREES VT_R8 | Intestazione relativa al vero nord in gradi. |
| SENSOR_DATA_TYPE_MAGNETIC_HEADING_DEGREES VT_R8 | Intestazione relativa a nord magnetico in gradi. |
| SENSOR_DATA_TYPE_MAGNETIC_VARIATION VT_R8 | Variazione magnetica. Est è positivo. |
| SENSOR_DATA_TYPE_ERROR_RADIUS_METERS VT_R8 | Raggio di errore che indica l'accuratezza della latitudine e longitudine in metri.
Nota Un oggetto report latitudine/longitudine passato a SetReport deve fornire questo valore nell'implementazione di GetValue.
|
| SENSOR_DATA_TYPE_ADDRESS1 VT_LPWSTR | Prima riga dell'indirizzo in un report di indirizzo civico.
Nota Se un oggetto report di indirizzo civico passato a SetReport contiene questi dati, deve fornire questo valore nell'implementazione di GetValue.
|
| SENSOR_DATA_TYPE_ADDRESS2 VT_LPWSTR | Seconda riga dell'indirizzo in un rapporto di indirizzo civico. Nota Se un oggetto report di indirizzo civico passato a SetReport contiene questi dati, deve fornire questo valore nell'implementazione di GetValue.
|
| SENSOR_DATA_TYPE_CITY VT_LPWSTR | Campo città in un rapporto di indirizzo civico. Nota Se un oggetto report di indirizzo civico passato a SetReport contiene questi dati, deve fornire questo valore nell'implementazione di GetValue.
|
| SENSOR_DATA_TYPE_STATE_PROVINCE VT_LPWSTR | Campo stato/provincia in un report di indirizzo civico. Nota Se un oggetto report di indirizzo civico passato a SetReport contiene questi dati, deve fornire questo valore nell'implementazione di GetValue.
|
| SENSOR_DATA_TYPE_POSTALCODE VT_LPWSTR | Campo codice postale in un report di indirizzo civico. Nota Se un oggetto report di indirizzo civico passato a SetReport contiene questi dati, deve fornire questo valore nell'implementazione di GetValue.
|
| SENSOR_DATA_TYPE_COUNTRY_REGION VT_LPWSTR | Codice paese/area geografica in un report di indirizzo civico. Il valore deve essere un codice paese ISO 3166 a due lettere o a tre lettere.
Nota Un oggetto report di indirizzo civico passato a SetReport deve fornire questo valore nell'implementazione di GetValue.
|
| SENSOR_DATA_TYPE_ALTITUDE_ELLIPSOID_ERROR_METERS VT_R8 | Errore di altitudine rispetto ai puntini di sospensione del riferimento, in metri. |
| SENSOR_DATA_TYPE_ALTITUDE_SEALEVEL_ERROR_METERS VT_R8 | Errore di altitudine rispetto al livello del mare, in metri. |
Di seguito è riportata una tabella di altre proprietà definite dalla piattaforma che possono verificarsi nei report di posizione, ma non sono specifiche per la posizione. Il campo fmtid di queste chiavi di proprietà è SENSOR_PROPERTY_COMMON_GUID.
| Nome della chiave di proprietà e tipo | Descrizione |
|---|---|
| SENSOR_PROPERTY_ACCURACY VT_UNKNOWN | Oggetto IPortableDeviceValues che contiene nomi dei tipi di dati del sensore e le relative accuratezze associate. I valori di accuratezza rappresentano la possibile variazione dei valori true.
I valori di accuratezza vengono espressi usando le stesse unità del campo dati, tranne se altrimenti documentate. |
| SENSOR_PROPERTY_CHANGE_SENSITIVITY VT_UNKNOWN |
Oggetto IPortableDeviceValues che contiene nomi dei tipi di dati del sensore e i relativi valori di riservatezza delle modifiche associati. I valori di riservatezza delle modifiche rappresentano la quantità in base alla quale il campo dati deve cambiare prima che venga generato l'evento SENSOR_EVENT_DATA_UPDATED.
I valori di riservatezza vengono espressi usando le stesse unità del campo dati, ad eccezione della posizione diversamente documentata. Ad esempio, un valore di riservatezza di modifica pari a 2 per SENSOR_DATA_TYPE_TEMPERATURE_CELSIUS rappresenta una sensibilità di più o meno 2 gradi Celsius. |
| SENSOR_PROPERTY_CURRENT_CONNECTION_TYPE VT_UI4 | Valore SensorConnectionType contenente il tipo di connessione corrente. |
| SENSOR_PROPERTY_CURRENT_REPORT_INTERVAL VT_UI4 |
Tempo trascorso corrente per la generazione di report dei dati del sensore, in millisecondi.
L'impostazione di un valore pari a zero segnala al driver di usare l'intervallo di report predefinito. Dopo aver ricevuto un valore pari a zero per questa proprietà, un driver deve restituire l'intervallo di report predefinito, non zero, quando viene eseguita una query. Le applicazioni possono impostare questo valore per richiedere un determinato intervallo di report, ma più applicazioni potrebbero usare lo stesso driver. Pertanto, i driver determinano l'intervallo di report true basato sulla logica interna. Ad esempio, il driver potrebbe usare sempre l'intervallo di report più breve richiesto dal chiamante. |
| SENSOR_PROPERTY_DESCRIPTION VT_LPWSTR | Stringa di descrizione del sensore. |
| SENSOR_PROPERTY_DEVICE_PATH VT_LPWSTR |
Identifica in modo univoco l'istanza del dispositivo con cui è associato il sensore. È possibile usare questa proprietà per determinare se un dispositivo contiene più sensori.
I driver di dispositivo non devono supportare questa proprietà perché la piattaforma fornisce questo valore alle applicazioni senza eseguire query sui driver. |
| SENSOR_PROPERTY_FRIENDLY_NAME VT_LPWSTR | Nome descrittivo per il dispositivo. |
| SENSOR_PROPERTY_LOCATION_DESIRED_ACCURACY VT_UI4 | Valore enumerato che indica il tipo di gestione dell'accuratezza richiesta da un'applicazione client. LOCATION_DESIRED_ACCURACY_DEFAULT (0) indica che il sensore deve usare l'accuratezza per cui può ottimizzare l'utilizzo di energia e altre considerazioni sui costi.
LOCATION_DESIRED_ACCURACY_HIGH (1) indica che il sensore deve fornire il report più accurato possibile. È incluso l'utilizzo di servizi a pagamento o il consumo maggiore della batteria o della larghezza di banda della connessione. |
| SENSOR_PROPERTY_MANUFACTURER VT_LPWSTR | Nome del produttore. |
| SENSOR_PROPERTY_MIN_REPORT_INTERVAL VT_UI4 | Impostazione minima di tempo trascorso supportata dall'hardware per la generazione di report dei dati del sensore, in millisecondi. |
| SENSOR_PROPERTY_MODEL VT_LPWSTR | Nome del modello di sensore. |
| SENSOR_PROPERTY_PERSISTENT_UNIQUE_ID VT_CLSID | GUID che identifica il sensore. Questo valore deve essere univoco per ogni sensore in un dispositivo o tra dispositivi dello stesso modello enumerato nel computer. |
| SENSOR_PROPERTY_RANGE_MAXIMUM VT_UKNOWN | Oggetto IPortableDeviceValues che contiene i nomi dei campi dei dati del sensore e i relativi valori massimi associati. |
| SENSOR_PROPERTY_RANGE_MINIMUM VT_UKNOWN | Oggetto IPortableDeviceValues che contiene nomi dei campi dati del sensore e i relativi valori minimi associati. |
| SENSOR_PROPERTY_RESOLUTION VT_UKNOWN | Oggetto IPortableDeviceValues che contiene i nomi dei campi dei dati del sensore e le relative risoluzioni associate. I valori di risoluzione rappresentano la riservatezza per la modifica nel campo dati.
I valori di risoluzione vengono espressi usando le stesse unità del campo dati, tranne se altrimenti documentate. |
| SENSOR_PROPERTY_SERIAL_NUMBER VT_LPWSTR | Numero di serie del sensore. |
| SENSOR_PROPERTY_STATE VT_UI4 | Valore SensorState contenente lo stato corrente del sensore. |
| SENSOR_PROPERTY_TYPE VT_CLSID | GUID che identifica il tipo di sensore. I tipi di sensore definiti dalla piattaforma sono definiti in Sensors.h. |
Esempio
Nell'esempio seguente viene illustrato come chiamare GetValue per ottenere un valore della proprietà. È necessario includere sensor.h per usare la costante nell'esempio.
PROPVARIANT pv;
HRESULT hr = spLatLongReport->GetValue(SENSOR_DATA_TYPE_LATITUDE_DEGREES, &pv);
Nell'esempio seguente viene illustrato come implementare GetValue nell'oggetto report. Questa implementazione consente al chiamante di ottenere valori per diversi campi del report del percorso. Questo codice richiede di includere sensor.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;
}
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows 7 [solo app desktop],Windows 7 |
| Server minimo supportato | Nessuno supportato |
| Piattaforma di destinazione | Windows |
| Intestazione | locationapi.h |
| DLL | LocationAPI.dll |