Windows 7 Training Windows Sensor and Location Platform

Windows 7 Training

® Windows Sensor and Location Platform Name Title Microsoft® Corporation

Agenda Introduction to the Windows Sensor and Location Platform Sensor architecture Working with the Sensor API Location architecture Working with the Location API

Sensor Platform Overview Windows 7 features a new API for working with sensors COM-based API Works with drivers using the sensor class extension Benefits No need to target vendor-specific APIs or to know hardware specifics Consistent interface for all sensor types Privacy and security

Sensor Platform Architecture This is a partial diagram of the Sensor and Location Platform, showing only sensor-related parts

Sensor API Architecture COM-based API (includes Sensorsapi. h and Sensors. h) Consists of these main interfaces: ISensor. Manager Sensor enumeration, attachment event, request permissions ISensor Get and set properties, get report, events (new report, detachment, state change, custom) and more ISensor. Data. Report Get sensor data report data fields

Privacy and Access Control Location data is considered personally identifiable information (PII) User consent is required to share data All sensors are disabled by default Administrator rights required to enable a sensor Sensors can be configured on a per-user basis Enable Sensors dialog box invoked by applications

Sensor API Architecture

What Is a Sensor? Enumerated via category and type GUIDs Category represents what is being sensed (for example, environment, location, motion, electrical systems) Type represents how it is being sensed (for example, by thermometer, GPS, accelerometer, voltage) Properties Read-only (such as model) or read-write (such as report interval). Sensors may have custom properties Data Get (sensor-specific) data report object synchronously (not recommended) or asynchronously (events) Events State change, leave (detach), data updated, custom State Is sensor working properly? Do you have access?

Enumerating Sensors #include <sensorsapi. h> #include <sensors. h> HRESULT hr; CCom. Ptr<ISensor. Manager> p. Sensor. Manager; p. Sensor. Manager. Co. Create. Instance(CLSID_Sensor. Manager); CCom. Ptr<ISensor. Collection> p. ALSCollection; CCom. Ptr<ISensor> p. ALSSensor; // Get all the ALS sensors on the system p. Sensor. Manager->Get. Sensors. By. Type(SENSOR_TYPE_AMBIENT_LIGHT, &p. ALSCollection); hr = p. Sensor. Manager->Request. Permissions( 0, // Owner window p. ALSCollection, // Collection of sensors requiring permissions TRUE); // Modal flag if(SUCCEEDED(hr)) { p. ALSCollection->Get. At(0, &p. ALSSensor); }

Getting Current Light Level STDMETHODIMP CALSEvent. Sink: : On. Data. Updated( ISensor* p. Sensor, ISensor. Data. Report* p. New. Data) { PROPVARIANT light. Level; Prop. Variant. Init(&light. Level); // Get the sensor reading from the ISensor. Data. Report object p. New. Data->Get. Sensor. Value(SENSOR_DATA_TYPE_LIGHT_LEVEL_LUX, &light. Level); // Extract the float value from the PROPVARIANT object float lux. Value = V_FLOAT(light. Level); // Normalize the light sensor data double light. Normalized = : : pow(lux. Value, 0. 4) / 100. 0; // Handle UI changes based on the normalized LUX data // which ranges from 0. 0 - 1. 0 for a lux range of // 0 lux to 100, 000 lux, this method represents such a // handler that would be implemented in your application Update. UI(light. Normalized); Prop. Variant. Clear(&light. Level); return S_OK; }

Windows 7 Integration Library Managed class library to ease. NET Framework access to Windows 7® features Taskbar, Libraries, Sensor, Location, Multi. Touch, UAC, power management, restart and recovery, network awareness, Aero Glass and more. It is a sample library not a full product Open source with no support Use at your own risk

Sensor Wrapper Architecture The three classes retain the same roles as they had in the COM API, only wrapping properties and events

Sensor Wrapper Architecture Sensor is an abstract base class with a derived type for each sensor type Derived types can add properties and events

Sensor Wrapper Architecture Sensor. Data. Report also has a derived type for each sensor type Provides a strongly-typed way to access data

Enumerating Sensors Accelerometer 3 D[] sensors = Sensor. Manager. Get. Sensors. By. Type<Accelerometer 3 D>(); Accelerometer 3 D a 3 d. Sensor = null; if (sensors. Length > 0) { a 3 d. Sensor = sensors[0]; Sensor. Manager. Request. Permission(Int. Ptr. Zero, true, a 3 d. Sensor); }

Receiving Data Reports from Sensor a 3 d. Sensor. Data. Updated += On. Data. Updated; void On. Data. Updated(Sensor sensor, Sensor. Data. Report data. Report) { Accelerometer 3 DReport a 3 d. Report = (Accelerometer 3 DReport)data. Report; Console. Write. Line("X: {0} Y: {1} Z: {2}", a 3 d. Report. Axis. X_G, a 3 d. Report. Axis. Y_G, a 3 d. Report. Axis. Z_G); }

Location Platform Overview The Windows 7 Location API is built on top of the Sensor API COM-based API (includes Locationapi. h) It is a high-level abstraction Leverages sensors which provide location information Some sensors (location providers) may be logical Wi-Fi hotspot triangulation

Sensor and Location Platform Architecture – The Big Picture User System

Location Platform Benefits Single API call to answer “Where am I? ” Provider (such as: GPS, IP resolver, Wi-Fi) independent Synchronous and asynchronous models Script or automation compatible Automatic transition between providers Most accurate providers have priority Concurrent access for multiple applications Default location Provided by user as fallback when no other sources are available

Default Location in Control Panel

Location API Architecture Consists of four main interfaces ILocation – Get location report (synchronous), query status, register for notification (asynchronous), request permissions ILocation. Report – Base interface; Two derived types exist: ILat. Long. Report and ICivic. Address. Report

Location API Architecture ILocation Methods Method Description Get. Report([in] REFIID report. Type, [out] ILocation. Report *pp. Loc. Report) Synchronously retrieves location report by report type. ILocation. Report is a base type. Get. Report. Status([in] REFIID report. Type, [out] LOCATION_REPORT_STATUS *p. Status) Retrieves status for specified report type. Request. Permissions([in] HWND h. Parent, [in] IID *p. Report. Types, [in] ULONG count, BOOL f. Modal) Opens a dialog to request user permission for sensors providing the given report types. Register. For. Report([in] ILocation. Events *p. Events, [in] REFIID report. Type, [in] DWORD dw. Min. Report. Interval) Subscribes a user object implementing ILocation. Events to asynchronously receive reports of the specified type. Unregister. For. Report([in]REFIID report. Type) Stops event notifications for the specified report type. Get. Report. Interval([in] REFIID report. Type, [out] DWORD *p. Milliseconds) Gets current minimal time (max. frequency) between events. Set. Report. Interval([in] REFIID report. Type, [in] DWORD milliseconds) Sets minimal time (max. frequency) between events.

Location API Architecture ILocation. Events Method Description On. Location. Changed([in] REFIID report. Type, [in] ILocation. Report *p. Location. Report ) Called when a new location report is available. ILocation. Report is a base type of the actual type. On. Status. Changed([in] REFIID report. Type, Called when a report status changes. [in] LOCATION_REPORT_STATUS new. Status );

Location API Architecture ILocation. Report (Base Class) Methods Method Description Get. Sensor. ID([out] SENSOR_ID *p. Sensor. ID) Retrieves the instance ID of the sensor that generated the location report. Get. Timestamp([out] SYSTEMTIME *p. Creation. Time ) Retrieves the date and time when the report was generated. Get. Value([in] REFPROPERTYKEY p. Key, [out] PROPVARIANT *p. Value) Retrieves a property value from the location report.

Location API Architecture Report Statuses (Enumeration) LOCATION_REPORT_STATUS enumeration: Value Description REPORT_NOT_SUPPORTED The requested report type is not supported by the API. REPORT_ERROR There was an error when creating the report. REPORT_ACCESS_DENIED No permissions have been granted to access this report type. Call ILocation: : Request. Permissions. REPORT_INITIALIZING The report is being initialized. REPORT_RUNNING The report is running.

Location API Architecture IDefault. Location Used to set default location (just like the Control Panel applet does) or specifically get the default location. Method Description Get. Report([in] REFIID report. Type, [out] ILocation. Report **pp. Location. Report) Retrieves the specified report type from the default location provider. Set. Report([in] REFIID report. Type, [in] ILocation. Report *p. Location. Report) Specifies the default location.

Types of Location Data Geographic data (ILat. Long. Report) Latitude, longitude, altitude, associated error required Most common format Best format for precise location Can reverse geo-code later Civic address (ICivic. Address. Report) Zip code, country required Most human readable Best for ‘rough’ location estimates, street directions

Getting a Location Report HRESULT hr; IID civic. Report. IID = IID_ICivic. Address. Report; CCom. Ptr<ILocation> p. Location; CCom. Ptr<ILocation. Report> p. Report; hr = p. Location. Co. Create. Instance(CLSID_Location); hr = p. Location->Request. Permissions(0, &civic. Report. IID, 1, TRUE); hr = p. Location->Get. Report(civic. Report. IID, &p. Report); CCom. Ptr<ICivic. Address. Report> p. Civic. Address. Report; p. Report. Query. Interface<ICivic. Address. Report>(&p. Civic. Address. Report); BSTR str; hr = p. Civic. Address. Report->Get. Country. Region(&str); _tprintf(_T("Country/region: %sn"), str); Sys. Free. String(str);

Location Wrapper Architecture Consists of two main classes: Location. Provider and Location. Report • Instantiate a Location. Providerderived type (for example, Lat. Long. Location. Provider). C’tor expects minimum report interval. • Query status via Report. Status. • If necessary, call Request. Permissions static method. • Get. Report() synchronously, or • Subscribe to Location. Changed event.

Location Wrapper Architecture Location. Report is the actual object containing data • Cast the Location. Report type you got from Get. Report() or in Location. Changed delegate to the appropriate derived type. • Query properties to retrieve the desired information.

Using Location Wrapper Synchronous var provider = new Civic. Address. Location. Provider(10000); Location. Provider. Request. Permissions(Int. Ptr. Zero, true, provider); var report = (Civic. Address. Location. Report) provider. Get. Report(); Console. Write. Line("Country/region: “, report. Country. Or. Region);

Using Location Wrapper Asynchronous var provider = new Civic. Address. Location. Provider(10000); Location. Provider. Request. Permissions(Int. Ptr. Zero, true, provider); provider. Location. Changed += (Location. Provider prov, Location. Report new. Loc) => { var civic. Loc. Report = (Civic. Address. Location. Report) new. Loc; Console. Write. Line("Country/region: ", civic. Loc. Report. Country. Or. Region); };

Summary Platform overview Native Sensor API Managed Sensor API wrapper Custom sensors Native Location API Types of location data, default location Managed Location API wrapper

Sensors and Location Q&A …everything you were afraid to ask

Sensors and Location hands-on lab It is time to race

© 2007 Microsoft Corporation. All rights reserved. Microsoft, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U. S. and/or other countries. The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION.