About Sensor Driver Events
Applications can receive information from sensors in two ways: synchronously, by requesting a particular property or data field, or asynchronously, by subscribing to an event that is raised by the sensor driver.
Sensor drivers can raise state change events, which notify applications about a transition in the device to a new operational condition, and other kinds of event notifications. Your driver should raise separate events for each sensor that your device provides.
Note Do not use IWDFDevice::PostEvent to raise sensor events. The sensor platform will not forward such events to the connected client programs.
State Change Events
Sensor drivers raise state change events by calling the sensor class extension's ISensorClassExtension::PostStateChange method. For example, a driver that has finished initializing a sensor will call this method to signal the new SensorState value named SENSOR_STATE_READY.
Event Constants
The sensor platform defines the following constants for driver events.
Sensor Event Types
The sensor platform defines the following sensor event types identifiers.
| Name | Description |
|---|---|
| SENSOR_EVENT_DATA_UPDATED | Indicates that new data is available. |
| SENSOR_EVENT_PROPERTY_CHANGED | Indicates that a property value changed. |
| SENSOR_EVENT_STATE_CHANGED | Indicates a change of operational state, for example, from SENSOR_STATE_INITIALIZING to SENSOR_STATE_READY. |
Sensor Event PROPERTYKEYs
The sensor platform defines the following PROPERTYKEYs to identify the parameters for sensor events.
| Name | Description |
|---|---|
| SENSOR_EVENT_PARAMETER_EVENT_ID | Indicates that the GUID value in IPortableDeviceValues is an event type ID, such as SENSOR_EVENT_DATA_UPDATED. |
| SENSOR_EVENT_PARAMETER_STATE | Indicates that the unsigned integer value in IPortableDeviceValues is a sensor state, such as SENSOR_STATE_READY. Note To raise a state change event, call ISensorClass Extension::PostStateChange. You do not have to explicitly specify SENSOR_EVENT_PARAMETER_STATE to raise the event. |
Other Events
Sensor drivers raise all other types of events by calling the sensor class extension's ISensorClassExtension::PostEvent method. This method provides a generic, extensible way to raise sensor events unrelated to operating state. Each call to PostEvent contains a pointer to IPortableDeviceValuesCollection. Each IPortableDeviceValues object in this collection contains a GUID value for the SENSOR_EVENT_PARAMETER_EVENT_ID property, which identifies the event type, and optional data field values, which contain the event data. For example, a GPS driver that has new city data will use the SENSOR_EVENT_DATA_UPDATED event ID and provide a string value for the SENSOR_DATA_TYPE_CITY property key.
After your driver posts the event, the sensor class extension forwards the event and any associated data to the Sensor API.
You can find the definitions of platform-defined constants in the file named Sensors.h. For detailed information about platform-defined sensor constants, see Constants.
Managing Sensor Driver Events
Before your driver accepts event requests, it should create a separate thread to generate and post events. By using a thread, you can help prevent frequent event procedures from blocking synchronous procedures, such as data request callbacks. For an example of a thread class that raises data-updated events, see Raising Data-Updated Events.
Your sensor should raise events only if at least one client application has requested event notifications. When an application requests event notifications, including for state-change events, the sensor class extension notifies the driver through ISensorDriver::OnClientSubscribeToEvents. This method provides an IWDFFile pointer that identifies the application and a string that identifies the sensor for which the application is requesting event notifications. You can use the IWDFFile pointer as a unique identifier to help keep track of applications that have subscribed to events. Although your sensor cannot raise events destined for specific clients, you will probably need to keep track of which application set which values for certain properties, such as SENSOR_PROPERTY_CURRENT_REPORT_INTERVAL or SENSOR_PROPERTY_CHANGE_SENSITIVITY.
For example, if multiple client applications set different values for SENSOR_PROPERTY_CURRENT_REPORT_INTERVAL, you could apply a rule that sets the event frequency to the shortest interval that has been requested. However, your sensor may need to adjust the interval each time a new client subscribes to events or an existing client unsubscribes. For more information about report intervals, including example code, see Filtering Data.
Sensor Events and Data Privacy
Like other data requests, requests for event notifications are made secure through use of the sensor class extension. The class extension allows location data only for the user that requests this data.
Caution
Make sure to use the sensor class extension to process all I/O requests for sensors. By doing this, you are less likely to reveal a user's private information.
For more information about data privacy, see Privacy and Security in the Sensor and Location Platform