90 lines
2.9 KiB
Plaintext
90 lines
2.9 KiB
Plaintext
/*
|
|
* Copyright 2019 Haiku, Inc. All rights reserved.
|
|
* Distributed under the terms of the MIT License.
|
|
*
|
|
* Authors:
|
|
* Adrien Destugues, pulkomandy@pulkomandy.tk
|
|
*
|
|
* Corresponds to:
|
|
* headers/private/netservices/Geolocation.h hrev54923
|
|
* src/kits/network/libnetservices/Geolocation.cpp hrev54923
|
|
*/
|
|
|
|
|
|
/*!
|
|
\file Geolocation.h
|
|
\ingroup netservices
|
|
\brief Geolocation and geocoding services.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\class BPrivate::Network::BGeolocation
|
|
\ingroup netservices
|
|
\brief Geolocation and geocoding services.
|
|
|
|
Geolocation allows to know where the computer is currently located.
|
|
This is currently done by sending a list of Wifi networks within reach to
|
|
a 3rd party webservice (Mozilla location services), which uses a database
|
|
of known networks around the world to return an estimate position.
|
|
|
|
Geocoding is about identifying places in a way more convenient than
|
|
latitude and longitude. This can include postal codes, country names,
|
|
street or building names, etc. This class allows to perform both geocoding
|
|
(finding a latitude and a longitude from a name) and reverse geocoding
|
|
(finding a suitable name for a given position). This service is provided
|
|
to haiku by the 3rd-party geonames.org
|
|
|
|
Note that most of the methods in this class perform HTTPS requests to
|
|
3rd-parties. When using it in your application, it is good practise to
|
|
first inform the user about what will be shared with these services, and
|
|
why that's needed. Of course, this also means using these services requires
|
|
internet access, and you may want to limit the number of calls, both to
|
|
save bandwidth and time, and to not overuse the provided API keys. If you
|
|
are going to do more than a few request per application run, you should
|
|
provide your own API keys instead.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BGeolocation::BGeolocation()
|
|
\brief Initialize a BGeolocation using the default services and API keys.
|
|
|
|
Official builds of Haiku include a shared API key for both Mozilla Location
|
|
Services and geonames.org. You can use this constructor to use these keys
|
|
in your application.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BGeolocation::BGeolocation(const BUrl& geolocationService,
|
|
const BUrl& geocodingService)
|
|
\brief Initialize a BGeolocation using custom services or API keys.
|
|
|
|
You can use this constructor to provide your own URL to a webservice to
|
|
use for the requests. The services have to implement the MLS and geonames
|
|
API, respectively.
|
|
|
|
If you want to override only one of the two URLs, the other can be passed
|
|
as an empty BUrl object.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BGeolocation::LocateSelf(float& latitude, float& longitude)
|
|
\brief Locate the computer by detecting nearby WiFi networks.
|
|
|
|
This method makes a request to Mozilla Location Services.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn status_t BGeolocation::Country(float latitude, float longitude,
|
|
BCountry& country)
|
|
\brief Find which country a given set of coordinates is in.
|
|
|
|
This method makes a request to geonames.org.
|
|
*/
|