2. Developing Device Drivers for the Sensor and Location Platform
Frank Chen
Senior Development Lead
PC|3

3. Sensor and Location Platform
Is a new component in Windows 7
Allows applications to query and discover sensors
Shares sensor and location data among multiple applications
Enables scenarios
Adaptive display brightness
Automatic display orientation
Location-aware weather gadget

4. Introduction: Sensors
Represent measurements of physical quantities or other interactions
Belong to a “sensor category”
Can be identified by “sensor type”
Have metadata and data fields
Report data and events

5. Sensor and Location Platform Overview
Location Automation API
Location and Other Sensors Control Panel
Location API
Sensor API
UMDF Sensor Device Driver
Sensor Driver Class Extension

6. Sensor and Location Platform Overview
Sensor API
Is an inproc COM DLL
Exposes interfaces
ISensorManager, ISensorManagerEvents
ISensor, ISensorEvents
Are used by client applications to discover and access sensor and sensor data
Defines
Sensor categories
Sensor types
Sensor data types
Sensor events

7. Sensor and Location Platform Overview
Location API and Location Automation API
Are contained in an inproc COM DLL
Expose interfaces
Ilocation, ILocationEvents
ILatLongReport, IDispLatLongReport
Are used by client applications to access location data
Location and Other Sensors Control Panel
Allows users to “opt in”
Sensor Driver Class Extension
Integrates UMDF driver with Sensor Platform
Enforces the “opt in” security model

8. Demo Simulated GPS device driver plays back a route
Location gadget displays current location on the map
Weather gadget displays weather for current location
Users enable/disable sensors device through Location and Other Sensors Control Panel

9. Presentation Goals Introduce location and sensor drivers
Explain design pattern on how to use Sensor Driver Class Extension
Explain how to implement Sensor Driver Callback Class

10. Sensor Driver Overview
Built on the user-mode driver framework (UMDF)
Requires the use of Sensor Driver Class Extension
Provides Sensor Driver Class Extension callback support
ISensorClassExtension
UMDF Sensor Device Driver
Sensor Driver Class Extension
ISensorDriver

11. Sensor Driver Class Extension Overview
Is an inproc COM server dll
Implements ISensorClassExtension interface
Requires a callback object that supports ISensorDriver interface
Passed as a parameter in the Initialize() function
Handles Windows portable devices (WPD) control requests
De-serializes input data buffer
Serializes output data
Enforces access control for location and sensor data
Checks location and sensor data access permission
Secures event data

12. ISensorClassExtension Methods
Initialize
Performs class extension object initialization
Uninitialize
Performs class extension object cleanup
CleanupFile
Cleans up file handles
ProcessIoControl
Handles WPD I/O requests only
PostStateChange
Fires state change events to applications
PostEvent
Fires new data events and custom events to applications

13. Callback Object Overview
Implements ISensorDriver interface
The interface pointer is passed as a parameter in the ISensorClassExtension::Initialize() function
Enumerates sensor objects
Returns sensor properties and data
Changes sensor configuration
Tracks client applications and event sinks
Processes other WPD messages

14. Introduction: Sensor Objects
A device may contain multiple sensors.
A device object is required. It is similar to WPD root object
Has the name WPD_DEVICE_OBJECT_ID
Contains device properties
Each sensor is represented by a sensor object. Sensor objects are similar to WPD functional objects
Contains sensor properties and data
Device
Sensor A
Sensor B
Sensor N …

15. Introduction: Sensor Object Properties
Properties are identified by property keys. They are returned as property key and value pairs.
Well-known sensor property keys are listed in sensors.h
Well-known WPD property keys are listed in PortableDevice.h
Each object has a unique ID or name property in string format. It identifies the device or sensor.
Property key: WPD_OBJECT_ID
VarType: VT_LPWSTR
Each sensor has a functional category
Property key: WPD_FUNCTIONAL_OBJECT_CATEGORY
VarType: VT_CLSID

16. Sensor Properties Example
Object ID
Sensor A
Category
Location
Type
GPS
Supported Data Fields
Time Stamp
Latitude Degrees
Longitude Degrees
Error Radius Meters

17. Introduction: Sensor Data
Data have associated time stamp
A latlong (latitude-longitude) location sensor must at least support following data fields
SENSOR_DATA_TYPE_TIMESTAMP
SENSOR_DATA_TYPE_LATITUDE_DEGREES
SENSOR_DATA_TYPE_LONGITUDE_DEGREES
SENSOR_DATA_TYPE_ERROR_RADIUS_METERS

18. Sensor Data Example Time Stamp 09/09/2008 12:32:30 Latitude Degrees
47.123
Longitude Degrees
Error Radius Meters
1.5

19. ISensorDriver Methods
OnGetSupportedSensorObjects
Returns a collection of all sensor objects
OnGetSupportedProperties
Returns a collection of property keys for a sensor object properties
OnGetSupportedDataFields
Returns a collection of property keys for a sensor object data
OnGetSupportedEvents
Returns an array of event ID GUIDs
OnGetProperties
Returns property key and value pairs of properties for a sensor object
OnGetDataFields
Returns property key and value pairs of data for a sensor object

20. ISensorDriver Methods (Continued)
OnSetProperties
Sets a sensor object configuration
OnClientConnect
Signals that a client application opens this sensor
OnClientDisconnect
Signals that a client application closes this sensor
OnClientSubscribeToEvents
Signals that a client application sets an event sink on this sensor
OnClientUnsubscribeFromEvents
Signals that a client application removes an event sink from this sensor
OnProcessWpdMessage
Process messages not handled by the class extension

21. Summary A sensor device driver for Windows 7
Must use Sensor Driver Class Extension
Calls ISensorClassExtension methods
Implements a callback object that supports ISensorDriver interface

22. Resources Sensor Driver Logo Kit Discussion Aliases
DDC 2008 Technical Session, Tues. 9:45-10:45
Sensor and Location Platform: Windows Logo Program Testing for Drivers
Windows Logo Program Web site
Discussion Aliases

23. Appendix

24. ISensorClassExtension Interface
Interface definition from IDL file
interface ISensorClassExtension::IUnknown {
HRESULT Initialize( [in] IUnknown* pWdfDeviceUnknown,
[in] IUnknown* pSensorDriverUnknown );
HRESULT Uninitialize();
HRESULT ProcessIoControl( [in] IWDFIoRequest* pRequest );
HRESULT PostEvent( [in] LPWSTR pwszSensorID,
[in] IPortableDeviceValuesCollection* pEventCollection );
HRESULT PostStateChange( [in] LPWSTR pwszSensorID,
[in] SensorState state );
HRESULT CleanupFile( [in] IWDFFile* pWdfFile ); };

25. Device Driver Creates and Initializes the Class Extension Object
Sample code from Sensor Skeleton Driver sample in WDK
// IPnpCallbackHardware method
HRESULT CMyDevice::OnPrepareHardware( __in IWDFDevice* pWdfDevice ) { …
// Create class extension object
hr = CoCreateInstance( CLSID_SensorClassExtension,
NULL,
CLSCTX_INPROC_SERVER,
__uuidof( ISensorClassExtension ),
(void**)&m_pClassExtension );
// Call Initialize method
hr = m_pClassExtension->Initialize( … ); }

26. Device Driver Releases the Class Extension Object Before Exiting
More sample code from WDK sample
// IPnpCallbackHardware method
HRESULT CMyDevice::OnReleaseHardware( __in IWDFDevice* pWdfDevice ) { …
// Release class extension
if (m_pClassExtension != NULL)
m_pClassExtension->Uninitialize();
m_pClassExtension->Release();
m_pClassExtension = NULL; }

27. Device Driver Must Clean Up File Handles
CleanupFile() must be called from IFileCallbackCleanup::OnCleanupFile() function
// IFileCallbackCleanup method
HRESULT CMyDevice::OnCleanupFile( __in IWDFFile* pWdfFile ) {
if (m_pClassExtension != NULL)
m_pClassExtension->CleanupFile( pWdfFile ); }
return S_OK;

28. Device Driver Dispatches WPD IO Requests to Class Extension
More sample code from WDK sample
// IQueueCallbackDeviceIoControl method
Void CMyQueue::OnDeviceIoControl( __in IWDFIoQueue* FxQueue,
__in IWDFIoRequest* FxRequest, __in ULONG controlCode,
__in SIZE_T inBufSize, __in SIZE_T outBufSize ) {
if ( IS_WPD_IOCTL( controlCode ) )
CComPtr<ISensorClassExtension> p; …
p->ProcessIoControl(FxRequest); }
else
{ // Handle other requests

29. Device Driver Calls Class Extension to Post Sensor State Change Events
Calls PostStateChange to fire state change events
LPWSTR pwszSensorID;
SensorState state = SENSOR_STATE_READY;
CComPtr<ISensorClassExtension> p; …
p->PostStateChange( pwszSensorID, state );

30. Device Driver Calls Class Extension to Post New Data Events
Event parameters are stored in IPortableDeviceValues as property key and value pairs.
SENSOR_EVENT_PARAMETER_EVENT_ID is required.
CComPtr<IPortableDeviceValues> pEventParams;
CoCreateInstance( CLSID_PortableDeviceValues,
NULL,
CLSCTX_INPROC_SERVER,
IID_IPortableDeviceValues,
(void**)&pEventParams );
// Set event type
pEventParams ->SetGuidValue( SENSOR_EVENT_PARAMETER_EVENT_ID,
SENSOR_EVENT_DATA_UPDATED );
//Set other data values …

31. Device Driver Calls Class Extension to Post New Data Events (Continued)
IPortableDeviceValues with event parameters are added to IPortableDeviceValuesCollection
Multiple events can be bundled together
CComPtr<IPortableDeviceValuesCollection> pEventCollection;
CoCreateInstance( CLSID_PortableDeviceValuesCollection,
NULL,
CLSCTX_INPROC_SERVER,
IID_IPortableDeviceValuesCollection,
(void**)&pEventCollection );
// Add an event
pEventCollection->Add( pEventParams );
//Add other events …

32. Device Driver Calls Class Extension to Post New Data Events (Continued)
Calls PostEvent to fire new data event
LPWSTR pwszSensorID;
CComPtr<ISensorClassExtension> p; …
p->PostEvent( pwszSensorID, pEventCollection );

33. Device Driver Provides Sensor Properties and Data through Callback Interface: ISensorDriver
Interface definition from IDL file
interface ISensorDriver::IUnknown {
HRESULT OnGetSupportedSensorObjects(
[out] IPortableDeviceValuesCollection** ppSensorObjectCollection );
HRESULT OnGetSupportedProperties(
[in] LPWSTR pwszSensorID,
[out] IPortableDeviceKeyCollection** ppSupportedProperties );
HRESULT OnGetSupportedDataFields(
[out] IPortableDeviceKeyCollection** ppSupportedDataFields );
HRESULT OnGetSupportedEvents(
[out] GUID** ppSupportedEvents,
[out] ULONG* pulEventCount );

34. ISensorDriver Interface (Continued)
HRESULT OnGetProperties(
[in] IWDFFile* pClientFile,
[in] LPWSTR pwszSensorID,
[in] IPortableDeviceKeyCollection* pProperties,
[out] IPortableDeviceValues** ppPropertyValues );
HRESULT OnGetDataFields(
[in] IPortableDeviceKeyCollection* pDataFields,
[out] IPortableDeviceValues** ppDataValues );
HRESULT OnSetProperties(
[in] IPortableDeviceValues* pPropertiesToSet,
[out] IPortableDeviceValues** ppResults );
HRESULT OnClientConnect(
[in] IWDFFile* pClientFile,
[in] LPWSTR pwszSensorID );

35. ISensorDriver Interface (Continued)
HRESULT OnClientDisconnect(
[in] IWDFFile* pClientFile,
[in] LPWSTR pwszSensorID );
HRESULT OnClientSubscribeToEvents(
HRESULT OnClientUnsubscribeFromEvents(
HRESULT OnProcessWpdMessage(
[in] IUnknown* pUnkPortableDeviceValuesParams,
[in] IUnknown* pUnkPortableDeviceValuesResults ); };

36. Device Driver Returns Collection of Sensors
Each sensor is represented by its properties.
Properties of a sensor are stored in IPortableDeviceValues as property key and value pairs.
HRESULT CSensorDdi::OnGetSupportedSensorObjects(
__out IPortableDeviceValuesCollection** ppSensorObjectCollection ) {
CComPtr<IPortableDeviceValues> pValues;
hr = CoCreateInstance( CLSID_PortableDeviceValues,
NULL,
CLSCTX_INPROC_SERVER,
IID_IPortableDeviceValues,
(VOID**) &pValues );
pValues->SetStringValue( WPD_OBJECT_NAME, GPS_SENSOR_ID );
pValues->SetGuidValue( WPD_FUNCTIONAL_OBJECT_CATEGORY, SENSOR_CATEGORY_LOCATION );
pValues->SetGuidValue( SENSOR_PROPERTY_TYPE, SENSOR_TYPE_LOCATION_GPS ); …

37. Device Driver Returns Collection of Sensors (Continued)
IPortableDeviceValues with sensor properties are added to IPortableDeviceValuesCollection.
hr = CoCreateInstance( CLSID_PortableDeviceValuesCollection,
NULL,
CLSCTX_INPROC_SERVER,
IID_IPortableDeviceValuesCollection,
(VOID**) ppPortableDeviceValuesCollection );
(*ppPortableDeviceValuesCollection)->Add(pValues); … }

38. Device Driver Returns Collection of Supported Data Fields for a Sensor
Property keys of data fields are stored in IPortableDeviceKeyCollection.
HRESULT CSensorDdi::OnGetSupportedDataFields(
__in LPWSTR ObjectID,
__out IPortableDeviceKeyCollection** ppKeys ) {
hr = CoCreateInstance( CLSID_PortableDeviceKeyCollection,
NULL,
CLSCTX_INPROC_SERVER,
IID_IPortableDeviceKeyCollection,
(VOID**) ppKeys );
*(ppKeys )->Add( SENSOR_DATA_TYPE_TIMESTAMP );
*(ppKeys )->Add( SENSOR_DATA_TYPE_LATITUDE_DEGREES );
*(ppKeys )->Add( SENSOR_DATA_TYPE_LONGITUDE_DEGREES );
*(ppKeys )->Add( SENSOR_DATA_TYPE_ERROR_RADIUS_METERS ); … }

39. Device Driver Processes WPD Messages
That Are Not Handled by Class Extension
Input parameters are stored in IPortableDeviceValues as property key and value pairs.
HRESULT CSensorDdi::OnProcessWpdMessage(
__in IUnknown* pUnkPortableDeviceValuesParams,
__in IUnknown* pUnkPortableDeviceValuesResults ) {
CComPtr<IPortableDeviceValues> pParams;
PROPERTYKEY CommandKey = WPD_PROPERTY_NULL;
hr = pUnkPortableDeviceValuesParams->QueryInterface(
IID_IPortableDeviceValues,
(void**) &pParams );
pParams->GetGuidValue( WPD_PROPERTY_COMMON_COMMAND_CATEGORY, &(CommandKey.fmtid) );
pParams->GetUnsignedIntegerValue( WPD_PROPERTY_COMMON_COMMAND_ID, &(CommandKey.pid) ); …

40. Device Driver Processes WPD Messages
That Are Not Handled by Class Extension (Continued)
Object ID is stored in IPortableDeviceValues.
LPWSTR wszObjectID = NULL;
pParams-> GetStringValue( WPD_PROPERTY_OBJECT_PROPERTIES_OBJECT_ID, &wszObjectID ); …
CoTaskMemFree( wszObjectID );

41. Device Driver Processes WPD Messages
That Are Not Handled by Class Extension (Continued)
Results are stored in IPortableDeviceValues as property key and value pairs.
A result value is required.
CComPtr<IPortableDeviceValues> pResults;
hr = pUnkPortableDeviceValuesResults->QueryInterface(
IID_IPortableDeviceValues,
(void**) & pResults ); …
pResults->SetErrorValue( WPD_PROPERTY_COMMON_RESULT, hr );