# Geolocation module

## Introduction

The geolocation module provides the glue between the platform implementation of various hardware devices and the DOM API for retrieving geographic positioning data. Hardware devices currently supported are

- wireless network interfaces (IEEE 802.11),
- cell information from phone, and
- GPS

The information is retrieved from Google given the above data. We return the favor by helping them collect data—that is, if the user agrees. This data is used, among other things, to identify traffic jams.

### Preferences

Global preferences are found in the geolocation collection. There are also host specific settings for allowing/disallowing use of the DOM API.

## Resources

- Geolocation wiki page
- DOM interface

## Interface overview and API documentation

### API documentation

The API documentation is extracted automatically by Doxygen.

### Overview

To be written...

## Supported standards

- We assist in implementing the geolocation DOM interface, though the implementation is in the DOM module.
- We use Google's Network Location Provider Protocol (which again uses JSON).

## Implementation and design

See also the API documentation.

### Generalisation and re-implementation

The OpPrefsCollection class is written so that it is easy to create new preferences sets for new code. Having them divided into several collection objects like this also helps hiding irrelevant settings from builds not sporting the code where they are used, and makes it possible to store the objects in the code modules where the preferences are referenced, meaning that the prefs module can be released asynchronously from the other modules.

### Memory management

#### Heap usage

No unbound memory usage, but we will allocate structures on the order of magnitude of those received from the platform.

#### Stack usage

The response parser is a recursive descent parser which has a fixed maximum stack depth, and will simply fail parsing on a too deep structure.

#### Static memory usage

#### OOM policies

OOM will lead to an error in the user of the Geolocation DOM API.

### Performance

The geolocation module might request data from the platforms on regular intervals, at most a handful per minute. This is the biggest performance hit, and needs to be solved on the platform side if polling for wifi, GPS or other data is a slow and blocking operation. We have tried to build an API that caters for keeping such polling in a different thread.