Developing Device Drivers for the Sensor and Location Platform

Frank ChenSenior Development Lead

PC|3frank.chen@microsoft.com

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

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

Sensor and Location Platform Overview

Sensor API

Location API

Location Automation API

UMDF Sensor Device Driver

Sensor Driver Class Extension

Location and Other Sensors Control Panel

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

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

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

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

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

UMDF Sensor Device Driver

Sensor Driver Class Extension

ISensorClassExtension

ISensorDriver

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

ISensorClassExtension Methods

• Performs class extension object initializationInitialize

• Performs class extension object cleanupUninitialize

• Cleans up file handlesCleanupFile

• Handles WPD I/O requests onlyProcessIoControl

• Fires state change events to applicationsPostStateChange

• Fires new data events and custom events to applicationsPostEvent

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

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…

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

Sensor Properties Example

• Sensor AObject ID

• LocationCategory

• GPSType

• Time Stamp• Latitude Degrees• Longitude Degrees• Error Radius Meters

Supported Data Fields

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

Sensor Data Example

• 09/09/2008 12:32:30Time Stamp

• 47.123Latitude Degrees

• -122.321Longitude Degrees

• 1.5Error Radius Meters

ISensorDriver Methods

• Returns a collection of all sensor objectsOnGetSupportedSens

orObjects

• Returns a collection of property keys for a sensor object properties

OnGetSupportedProperties

• Returns a collection of property keys for a sensor object data

OnGetSupportedDataFields

• Returns an array of event ID GUIDsOnGetSupportedEven

ts

• Returns property key and value pairs of properties for a sensor objectOnGetProperties

• Returns property key and value pairs of data for a sensor objectOnGetDataFields

ISensorDriver Methods (Continued)

• Sets a sensor object configurationOnSetProperties

• Signals that a client application opens this sensorOnClientConnect

• Signals that a client application closes this sensorOnClientDisconnect

• Signals that a client application sets an event sink on this sensor

OnClientSubscribeToEvents

• Signals that a client application removes an event sink from this sensor

OnClientUnsubscribeFromEvents

• Process messages not handled by the class extension

OnProcessWpdMessage

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

Resources

• Sensor Driver Logo Kit

• DDC 2008 Technical Session, Tues. 9:45-10:45

• Sensor and Location Platform: Windows Logo Program Testing for Drivers

• Windows Logo Program Web site http://www.microsoft.com/whdc/winlogo/default.mspx

• Discussion AliasesSensExt@Microsoft.comLocExt@Microsoft.com

Appendix

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

Device Driver Creates and Initializes the Class Extension

Object• Sample code from Sensor Skeleton Driver sample in WDK

// IPnpCallbackHardware methodHRESULT 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( … ); …}

Device Driver Releases the Class Extension Object Before Exiting

• More sample code from WDK sample

// IPnpCallbackHardware methodHRESULT CMyDevice::OnReleaseHardware( __in IWDFDevice*

pWdfDevice ){ … // Release class extension

if (m_pClassExtension != NULL){

m_pClassExtension->Uninitialize();m_pClassExtension->Release();m_pClassExtension = NULL;

} …}

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

Device Driver Dispatches WPD IO Requests to Class Extension

• More sample code from WDK sample

// IQueueCallbackDeviceIoControl methodVoid 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 … }}

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

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 typepEventParams -

>SetGuidValue( SENSOR_EVENT_PARAMETER_EVENT_ID,SENSOR_EVENT_DATA_UPDATED );

//Set other data values…

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 eventpEventCollection->Add( pEventParams );

//Add other events…

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

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([in] LPWSTR pwszSensorID,

[out] IPortableDeviceKeyCollection** ppSupportedDataFields );

HRESULT OnGetSupportedEvents([in] LPWSTR pwszSensorID,

[out] GUID** ppSupportedEvents, [out] ULONG* pulEventCount );

ISensorDriver Interface (Continued)HRESULT OnGetProperties(

[in] IWDFFile* pClientFile, [in] LPWSTR pwszSensorID, [in] IPortableDeviceKeyCollection* pProperties, [out] IPortableDeviceValues** ppPropertyValues );

HRESULT OnGetDataFields([in] IWDFFile* pClientFile,

[in] LPWSTR pwszSensorID, [in] IPortableDeviceKeyCollection* pDataFields, [out] IPortableDeviceValues** ppDataValues );

HRESULT OnSetProperties([in] IWDFFile* pClientFile,

[in] LPWSTR pwszSensorID, [in] IPortableDeviceValues* pPropertiesToSet, [out] IPortableDeviceValues** ppResults );

HRESULT OnClientConnect([in] IWDFFile* pClientFile,

[in] LPWSTR pwszSensorID );

ISensorDriver Interface (Continued)

HRESULT OnClientDisconnect([in] IWDFFile* pClientFile,

[in] LPWSTR pwszSensorID );

HRESULT OnClientSubscribeToEvents([in] IWDFFile* pClientFile,

[in] LPWSTR pwszSensorID );

HRESULT OnClientUnsubscribeFromEvents([in] IWDFFile* pClientFile,

[in] LPWSTR pwszSensorID );

HRESULT OnProcessWpdMessage([in] IUnknown* pUnkPortableDeviceValuesParams,

[in] IUnknown* pUnkPortableDeviceValuesResults );};

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 );…

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);…

}

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 );…

}

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

…

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

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