Geolocation API's

[Redth]

The Geolocation API is meant to be extremely simple at this point.

Geocoding API's: #28

static class Geolocation {
    // Android and iOS have a concept of a last known position that should return very quickly compared to firing up the GPS and waiting for a position.
    // This should return null if there is no known last position.
    // UWP has something interesting about consent-less location:
    // https://docs.microsoft.com/en-us/uwp/api/Windows.Devices.Geolocation.Geolocator#Windows_Devices_Geolocation_Geolocator_AllowFallbackToConsentlessPositions
    static Task<Position> GetLastKnownPositionAsync();

    // We should throw different exceptions depending on the error: For example a DeviceFeatureUnavailableException or something similar if the device has no GPS abilities.
    static Task<Position> GetPositionAsync(GeolocationAccuracy desiredAccuracy, TimeSpan timeout, CancellationToken token = default(CancellationToken));
}

class Position {
    Position();
    Position(double latitude, double longitude);
    Position(double latitude, double longitude, DateTimeOffset timestamp);
    Position(Position position);

    DateTimeOffset Timestamp { get; set; }
    double Latitude { get; set; }
    double Longitude { get; set; }

    static double CalculateDistance(Position positionStart, Position positionEnd);
    static double CalculateDistance(
        double latitudeStart, double latitudeEnd, 
        double longitudeStart, double longitudeEnd);
}

enum GeolocationAccuracy {
    Lowest,
    Low,
    Medium,
    High,
    Best
}

The accuracy enum values should map to the following table of platform specific accuracy choices:

	iOS	Expected	Android	Expected	UWP	Expected
Lowest	ThreeKilometers	3000	ACCURACY_LOW, POWER_LOW	500	3000	1000-5000
Low	Kilometer	1000	ACCURACY_LOW, POWER_MEDIUM	500	1000	300-3000
Medium	HundredMeters	100	ACCURACY_MEDIUM, POWER_MEDIUM	100-500	100	30-500
High	NearestTenMeters	10	ACCURACY_HIGH, POWER_MEDIUM	0-100	High	<=10
Best	Best	0	ACCURACY_HIGH, POWER_HIGH	0-100	High	<=10

class GeolocationException {
    GeolocationException(GeolocationErrorType errorType);
    GeolocationException(GeolocationErrorType, Exception innerException);

    GeolocationErrorType ErrorType { get; }
}

enum GeolocationErrorType {
    PositionUnavailable,
    Unauthorized
}

[mattleibow]

Maybe we should split this issue into two separate to focus the discussion and implementation.

[jamesmontemagno]

Geocoder should have it's own thread as it is a different api

[mattleibow]

Moved Geocoding to #28.

[mattleibow]

There was a comment (#29 (comment)) that suggested that we change the Position type to GeoPosition. I also agree that it is better because Position is too generic and could conflict with graphics libraries or something. We may also do something that may use Position.

Also, all the stuff already starts with the Geo prefix, so we can be consistent here.

Any thoughts?