Developing Device Drivers for the Sensor and Location Platform Frank Chen Senior Development Lead...
-
date post
19-Dec-2015 -
Category
Documents
-
view
228 -
download
1
Transcript of Developing Device Drivers for the Sensor and Location Platform Frank Chen Senior Development Lead...
Developing Device Drivers for the Sensor and Location Platform
Frank ChenSenior Development Lead
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 [email protected]@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 );