Schreiben eines Positionssensortreibers für Windows 8.1
Wichtig
Diese Dokumentation und das Beispiel für geolocation-Treiber für Windows 8.1 sind veraltet.
Die Sensor- und Standortplattform stellt die Windows-Standort-API bereit, damit Softwareentwickler ihren Anwendungen Standortfeatures hinzufügen können. Wenn Sie einen Treiber für einen Standortsensor schreiben, müssen Sie wissen, wie Sie den Treiber mit der Standort-API kompatibel machen und die Richtlinien unter Richtlinien für Standorttreiber für Leistung und Leistung befolgen.
Anforderungen an das Windows-Hardwarezertifizierungsprogramm
Das Windows-Hardwarezertifizierungsprogramm ermöglicht Es Hardwareherstellern, die Zertifizierung zu erhalten, dass ihre Geräte die erforderlichen Standards für die Arbeit mit Windows erfüllen. Das Zertifizierungsprogramm beschreibt die Anforderungen an Standortsensoren und andere Arten von Sensoren. Sie sollten dafür sorgen, dass Ihr Standortsensortreiber alle Anforderungen des Zertifizierungsprogramms erfüllt. Zu diesen Anforderungen gehören die folgenden:
Positionssensoren müssen den erforderlichen Satz von Daten und Sensoreigenschaften unterstützen.
Positionssensoren müssen die erforderlichen Datenfelder für mindestens einen integrierten Datenberichtstyp unterstützen.
Im Allgemeinen entsprechen die Empfehlungen in dieser WDK-Dokumentation den Anforderungen des Zertifizierungsprogramms. Sie müssen jedoch die offizielle Dokumentation zum Zertifizierungsprogramm lesen, wenn Sie Sensortreiber erstellen, die Sie zur Genehmigung übermitteln möchten. Weitere Informationen zum Windows-Hardwarezertifizierungsprogramm finden Sie auf der Windows Hardware Developer Central-Website .
Anforderungen an die Standort-API
Sie erstellen Treiber für Positionssensoren, indem Sie dasselbe Treibermodell und dieselbe Klassenerweiterung wie für jede andere Sensorkategorie verwenden. Um als Standortsensor zu arbeiten, muss der Treiber mindestens:
Identifizieren Sie den Positionssensor als gehört zur Kategorie Standort.
Legen Sie den Sensortyp auf einen der Positionssensortypen fest.
Identifizieren Sie die Datenfelder des Standortberichts, die der Sensor bereitstellt.
Unterstützen Sie die erforderlichen Eigenschaften.
Geben Sie Daten an, wenn sie angefordert werden.
Verwalten von Zustandsübergängen
Auslösen von Datenupdates und Zustandsänderungsereignissen.
Im weiteren Verlauf dieses Abschnitts werden diese Mindestanforderungen beschrieben.
Identifizieren der Kategorie
Wenn er über ISensorDriver::OnGetProperties aufgerufen wird, legen Sie den Wert der WPD_FUNCTIONAL_OBJECT_CATEGORY-Eigenschaft auf SENSOR_CATEGORY_LOCATION fest. Im folgenden Codebeispiel wird gezeigt, wie Diese Konstante über einen Zeiger auf IPortableDeviceValues namens pValues festgelegt wird.
hr = pValues->SetGuidValue(WPD_FUNCTIONAL_OBJECT_CATEGORY, SENSOR_CATEGORY_LOCATION);
Festlegen des Positionssensortyps
Wenn sie über ISensorDriver::OnGetProperties aufgerufen wird, legen Sie den wert der SENSOR_PROPERTY_TYPE-Eigenschaft auf den richtigen Wert fest. Im folgenden Codebeispiel wird gezeigt, wie der Sensortyp mithilfe der SENSOR_TYPE_LOCATION_GPS Konstante über einen Zeiger auf IPortableDeviceValues namens pValues festgelegt wird.
hr = pValues->SetGuidValue(SENSOR_PROPERTY_TYPE, SENSOR_TYPE_LOCATION_GPS);
Identifizieren der unterstützten Datenfelder
Die Standort-API definiert zwei Arten von Standortberichten. Dies sind Objekte, die Standortdaten organisieren. LatLong-Berichte enthalten Breiten-, Längen- und Höhendatenfelder sowie Datenfelder, die Fehlerbereichsinformationen enthalten. Bürgeradressenberichte enthalten Straßendatenfelder, z. B. Ort und Postleitzahl. Ihr Standorttreiber muss die erforderlichen Datenfelder für mindestens einen dieser beiden Datenberichtstypen unterstützen.
Um einen LatLong-Bericht zu unterstützen, sind die folgenden Datenfelder erforderlich:
SENSOR_DATA_TYPE_LATITUDE_DEGREES
SENSOR_DATA_TYPE_LONGITUDE_DEGREES
SENSOR_DATA_TYPE_ERROR_RADIUS_METERS
Um einen Bürgeradressenbericht zu unterstützen, ist mindestens eines der folgenden Datenfelder erforderlich:
- SENSOR_DATA_TYPE_COUNTRY_REGION
Informationen zum vollständigen Satz plattformdefinierter Standortdatenfelder finden Sie unter SENSOR_CATEGORY_LOCATION im Abschnitt Windows-Sensorreferenz .
Wenn sie über ISensorDriver::OnGetSupportedDataFields aufgerufen werden, fügen Sie der IPortableDeviceKeyCollection die unterstützten Datenfeld-Eigenschaftsschlüsselkonstanten hinzu, die Sie über den ppSupportedDataFields-Parameter zurückgeben. Im folgenden Codebeispiel wird gezeigt, wie das Postleitzahldatenfeld zu IPortableDeviceKeyCollection über eine Variable namens pKeyCollection hinzugefügt wird.
pKeyCollection->Add(SENSOR_DATA_TYPE_POSTALCODE);
Unterstützung der erforderlichen Eigenschaften
Wie andere Sensortreiber stellen Standorttreiber Informationen über den Sensor selbst über eine Reihe von Eigenschaften bereit. Das Windows-Hardwarezertifizierungsprogramm gibt den mindestens erforderlichen Satz von Eigenschaften an, die ein Standortsensor unterstützen muss. Weitere Informationen zu Sensoreigenschaften, deren Bedeutungen und welche Eigenschaften für Sensortreiber erforderlich sind, finden Sie unter Sensoreigenschaften. Die folgende Liste enthält die erforderlichen Eigenschaften:
WPD_FUNCTIONAL_OBJECT_CATEGORY
SENSOR_PROPERTY_TYPE
SENSOR_PROPERTY_STATE
SENSOR_PROPERTY_PERSISTENT_UNIQUE_ID
SENSOR_PROPERTY_MANUFACTURER
SENSOR_PROPERTY_MODEL
SENSOR_PROPERTY_SERIAL_NUMBER
SENSOR_PROPERTY_FRIENDLY_NAME
SENSOR_PROPERTY_MIN_REPORT_INTERVAL
SENSOR_PROPERTY_CURRENT_REPORT_INTERVAL
SENSOR_PROPERTY_LOCATION_DESIRED_ACCURACY
Bereitstellen von Daten
Standorttreiber stellen Daten über die gleichen Mechanismen wie andere Sensortreiber bereit. Das heißt, die Sensorklassenerweiterung ruft den Treiber über ISensorDriver::OnGetDataFields auf, und der Treiber gibt die Werte über den ppDataValues-Parameter zurück.
Die folgenden Anforderungen gelten für die Bereitstellung von Daten von einem Standortsensor:
Stellen Sie Daten sowohl über synchrone Anforderungen als auch durch Auslösen von Ereignissen bereit.
Verwalten Sie eine Kopie Ihres letzten Datenberichts. Wenn bei der Anforderung keine neuen Daten verfügbar sind, geben Sie den zwischengespeicherten Bericht zurück. Aktualisieren Sie den Zeitstempel nicht.
Geben Sie keine Werte für SENSOR_DATA_TYPE_LATITUDE_DEGREES und SENSOR_DATA_TYPE_LONGITUDE_DEGREES an, die außerhalb des Bereichs der realen Breiten- und Längengrade liegen.
Melden Sie keinen Wert für SENSOR_DATA_TYPE_ERROR_RADIUS_METERS, der null oder weniger ist.
Legen Sie den Wert für SENSOR_DATA_TYPE_COUNTRY_REGION auf einen gültigen ISO 3166 1-alpha-2-Ländercode fest.
Wenn Ihr Treiber sowohl Breiten-/Längen- als auch Ziviladressenberichte unterstützt, sollten die Standortdaten in diesen Berichten demselben physischen Standort entsprechen.
In der folgenden Tabelle werden die Sensordatenfelder beschrieben, die den Berichtsfeldern der Standort-API-Daten entsprechen. Verwenden Sie diese Datenfeldkonstanten, wenn Sie Datenberichte für einen Standort bereitstellen.
Verwalten von Zustandsübergängen
Ein Sensortreiber kann sich jederzeit in einem von mehreren Zuständen befinden. Sensorzustände werden durch die SensorState-Enumeration definiert. Um ordnungsgemäß mit der Standort-API zu arbeiten, müssen Standortsensoren diese Regeln für die Behandlung von Zustandsübergängen befolgen.
Starten Sie immer im SENSOR_STATE_INITIALIZING Zustand, aber lösen Sie beim Start kein Zustandsänderungsereignis aus.
Der Treiber sollte von SENSOR_STATE_INITIALIZING zu SENSOR_STATE_READY wechseln, wenn Daten verfügbar sind.
Der Treiber sollte zurück zu SENSOR_STATE_INITIALIZING wechseln, wenn der Treiber keine aktuellen Daten zu melden hat. Der Treiber sollte entscheiden, wann dieser Übergang stattfindet. Wenn Sie ein Signal verloren haben, aber dennoch über eine Möglichkeit verfügen, gültige Daten bereitzustellen, bleiben Sie im SENSOR_STATE_READY Zustand.
Auslösen von Ereignissen immer in der richtigen Reihenfolge. Stellen Sie zunächst fest, dass Daten verfügbar sind. Lösen Sie dann ein Zustandsänderungsereignis aus. Lösen Sie schließlich das Ereignis mit aktualisierten Daten aus.
Lösen Sie immer ein Zustandsänderungsereignis aus, wenn sich der Zustand des Treibers ändert.
– Die Standort-API verwendet keine Daten von Sensoren, die sich in den folgenden Zuständen befinden: SENSOR_STATE_NO_DATA, SENSOR_STATE_NOT_AVAILABLE, SENSOR_STATE_ERROR.
Die verschiedenen Sensorzustände für Standortsensortreiber werden in der folgenden Tabelle beschrieben.
| Wert | BESCHREIBUNG | Standort-API-Status |
|---|---|---|
| SENSOR_STATE_READY | Der Sensortreiber kann neue Standortberichte mit vollständigen und genauen Daten bereitstellen. Beispielsweise ist ein Wi-Fi- oder Mobilfunkanbieter verbunden und funktioniert, oder ein GPS-Sensor verfügt über eine Korrektur. Ein GPS-Treiber, der Daten von einem Triangulationssensor verwendet hat, um den Standort zu bestimmen, hat diesen Zustand. | REPORT_RUNNING |
| SENSOR_STATE_INITIALIZING | Der Sensortreiber versucht, eine Korrektur zu erhalten. Der Sensortreiber sollte diesen Zustand verlassen, um zu SENSOR_STATE_READY zu wechseln, nachdem ein Fix gesperrt und nachverfolgt wurde. Beispielsweise sucht ein Wi-Fi Anbieter nach einer Internetverbindung, ein Mobilfunkanbieter nach Funkgeräten oder ein GPS-Sensor sucht eine Reparatur. GPS-Sensoren sollten diesen Zustand erneut erreichen, wenn sie versuchen, eine Korrektur zu erzwingen. | REPORT_INITIALIZING |
| SENSOR_STATE_NO_DATA | Der Standortanbieter ist verfügbar, kann aber keine Standortdaten bereitstellen. Beispielsweise hat ein Wi-Fi Anbieter Zugriff auf das Internet, aber die Datenbank verfügt über keine Standortdaten. | REPORT_ERROR |
| SENSOR_STATE_NOT_AVAILABLE | Die Funktionalität, die der Standortanbieter zum Abrufen von Daten verwendet, ist deaktiviert. Ein GPS-Sensor kann sich in diesem Zustand befinden, wenn das Radio ausgeschaltet ist. | REPORT_ERROR |
| SENSOR_STATE_ERROR | Beim Sensor ist ein schwerwiegender Fehler aufgetreten. Der Sensor kann von diesem Zustand wiederhergestellt werden, aber der Zeitrahmen für die Wiederherstellung ist nicht bekannt. | REPORT_ERROR |
Das folgende Diagramm zeigt, wie Zustandsübergänge in einem Standortsensor auftreten können. 
Auslösen von Daten aktualisierten und zustandsveränderten Ereignissen
Die Standort-API erfordert Standortsensoren, z. B. GPS-Sensoren, um Ereignisse auszulösen, die Daten und Zustandsänderungsinformationen bereitstellen. Weitere Informationen zum Auslösen von Sensorereignissen finden Sie unter Informationen zu Sensortreiberereignissen.
Beim Auslösen dieser Ereignisse müssen Standorttreiber die folgenden Regeln befolgen:
Lösen Sie Zustandsänderungsereignisse aus, indem Sie die ISensorClassExtension::P ostStateChange-Methode der Sensorklassenerweiterung aufrufen. Rufen Sie PostEvent nicht auf, um Zustandsänderungsereignisse auszulösen.
Auslösen von Daten aktualisierten Ereignissen durch Aufrufen von PostEvent.
Auslösen eines Daten-Aktualisierten-Ereignisses nur, wenn die Daten auf dem neuesten Stand und genau sind.
Lösen Sie kein Ereignis mit Daten aktualisiert zweimal aus. Dies bedeutet, dass Sie kein Daten-Updateereignis mithilfe zwischengespeicherter Daten auslösen sollten. Sie können zwischengespeicherte Daten als Reaktion auf eine synchrone Anforderung für Daten bereitstellen.
Fügen Sie immer alle erforderlichen Datenfelder ein, wenn Sie einen Breiten-/Längengradbericht über ein Ereignis senden.
Lösen Sie immer ein Daten-update-Ereignis aus, wenn sich die Sensorgenauigkeit ändert.
Melden Sie einen gültigen Wert für SENSOR_DATA_TYPE_ERROR_RADIUS_METERS, bevor Sie Ereignisse auslösen oder den Wert für SENSOR_PROPERTY_STATE in SENSOR_STATE_READY ändern.
Stellen Sie keine unvollständigen Datenberichte bereit.
Möglicherweise verfügen Sie nicht über aktuelle Daten für die erforderlichen Datenfelder, z. B. wenn ein GPS-Sensor seine Korrektur verloren hat. In diesem Fall möchten Sie möglicherweise weiterhin Benachrichtigungen über Updates für erweiterte Datenfelder bereitstellen, z. B. SENSOR_DATA_TYPE_NMEA_SENTENCE. Um solche Benachrichtigungen bereitzustellen, müssen Sie einen benutzerdefinierten Ereignistyp verwenden und nur das benutzerdefinierte Ereignis auslösen, bis Daten für die erforderlichen Datenfelder verfügbar sind. Informationen zum Definieren benutzerdefinierter Typen finden Sie unter Definieren benutzerdefinierter Werte für Konstanten.
Verwandte Themen
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für