The Sensor and Location Drill Down – Part 3: The Location API

Over the last few weeks we have been providing an introduction to the Sensor and Location Platform by examining each component in the platform in greater detail.

We started first with an overview of the Sensor and Location Platform.

This was followed up with a drill down in the Sensor DDI or Device Driver Interface.

Next we examined the Sensor API and how it fits into the Sensor and Location Platform.

As the final post in this series we will be examining the Location API. The Location API, as described in the introduction post (link) sits on top of the sensor and location “API stack”. That is to say that the Location API is really a client of the Sensor API and the framework provided by the Sensor DDI. As a refresher – here is a diagram of the Location Platform:

There are a few important notes to cover about the Location API Layer in this diagram. The first is that the Location API is actually a collection of two API’s. A COM API which is accessible via native C++ applications and an IDispatch or “scripting” API. The IDispatch API provides access to Location in script enabled environments like the Windows Scripting Host and Active X controls. As an example – it’s possible to write a Sidebar Gadget (as identified in the diagram above) that can access Location via the IDispatch API interface.

What may not be clear in this diagram is that a “Location Sensor” is really just a Sensor that provides Location information. The location sensor data that is available from the Location API is also available, in a more basic format, from the Sensor API.

This may make you ask – what does the Location API do for you? The Location API is designed to focus on making access to location information easier. Two specific guiding goals are important to drill into:

- Simplify access to location sources (i.e. location sensors).

- Simplify accessing location information from location sensors.

Let’s examine each of those goals in isolation:

First, simplifying access to location sources: At any given time you may have one or more location sensors on your machine (default location + some other location sensor like a GPS sensor). If you were to access these location sensors directly from the Sensor API you would need to talk to all available location sensors and make some determination about which sensor is likely to provide the location data you want. The Location API does the work, internally, to identify and use the location sensor which appears to be most accurate and reliable.

Second, simplify accessing location information from location sensors: A location sensor is just a sensor. As such you can access the location sensors information from the Sensor API. However, the Sensor API is designed to provide generalized access to all forms of sensor devices on your machine. As a result accessing data from sensors usually requires a several steps. Take a look at our last blog post on the Sensor API to get a quick overview of these steps (link). The Location API automatically calls into the Sensor API and extracts location information for you. The Location API then presents the information in a format that is specifically suited for location data, such as ILatLongReport and ICivicAddressReport. The net effect is that it is generally much simpler to ask the Location API for location data instead of using the Sensor API.

So, how do you access location data from the Location API? Let’s walk through a quick example using the COM Location API. Note - each step below will contain a link to the relevant document in MSDN.

- First create an instance of the Location API by CoCreating ILocation.

- Next, call ILocation->RegisterForReports() to register to receive ILocationReport’s (either an ILatLongReport or an ICivicAddressReport).

- When you call RegisterForReports() on an ILocation object you will register a call-back object which will be called when the Location API wants to notify you of changes in Location or Location Status. The callback object will need to implement the ILocationEvents interface to receive location events. When a location change occurs the OnLocationChanged() method, which will be implemented in your callback object, will get called with the updated ILatLongReport or ICivicAddressReport.

- The OnLocationChanged() callback method will deliver to your callback object either an ILatLongReport or an ICivicAddressReport. Each report object provides methods to access the location information contained by the object. As an example you can access the latitude on an ILatLongReport by calling the GetLatitude() method. The GetLatitude() method will return a double which represents the current latitude for your location sensor.

The Location API documentation on MSDN has an example which shows all of the above in steps in one location with a description for each object used. You can find that information here.

To summarize:

- The Location API sit’s at the top of the Sensor API stack and provides simplified access to location data.

- To access Location you can either use the COM Location API interface in C++ or you can use the scripting interface.

- To get location updates in your application all you need to do is create the Location API, register for reports and then handle location changes on your call back object.

A few final notes: The Location API team has been working over the last several months with the .NET CLR Team to build a Managed Location API which will ship in the next version of .NET. We are tremendously excited about having location exposed to developers via COM, Scripting and now .NET. You can find some initial information about the .NET Location API on Gavin’s blog (link). Stay tuned here for more information!

-- Sensor & Location Platform Team

This posting is provided "AS IS" with no warranties and confers no rights.