Top |
Functions
void | geocode_backend_forward_search_async () |
GList * | geocode_backend_forward_search_finish () |
GList * | geocode_backend_forward_search () |
void | geocode_backend_reverse_resolve_async () |
GList * | geocode_backend_reverse_resolve_finish () |
GList * | geocode_backend_reverse_resolve () |
Description
The GeocodeBackend interface defines the operations that a resolver service must implement.
geocode-glib supports multiple backends which provide the underlying geocoding database and functionality. By default, the GeocodeNominatim backend is used with GNOME’s Nominatim server. If you are using geocode-glib in some GNOME software, this is the correct backend to use. Otherwise, you should use a new GeocodeNominatim instance with your own Nominatim server, or a custom GeocodeBackend implementation to use geocoding data from a non-Nominatim service. In all cases, please respect the terms of use of the service you are using.
If you are writing a library which uses geocode-glib, consider exposing the choice of GeocodeBackend in your library API, so that applications can make the best choice about which geocoding backend to use.
Custom backends can be implemented by subclassing GeocodeBackend and
implementing the synchronous forward_search
and reverse_resolve
methods.
The asynchronous versions may be implemented as well; the default
implementations run the synchronous version in a thread.
In order to use a custom backend, either instantiate the backend directly
and do forward and reverse queries on it using the GeocodeBackend interface;
or create GeocodeForward and GeocodeReverse objects as normal, and set
the backend they use with geocode_forward_set_backend()
and
geocode_reverse_set_backend()
. They default to using the GNOME Nominatim
backend.
GeocodeMockBackend is intended to be used in unit tests for applications which use geocode-glib — it allows them to set the geocode results they expect their application to query, and check afterwards that the queries were performed. Additionally, it works offline, which allows application unit tests to be run on integration and build machines which are not online. It is not expected that GeocodeMockBackend will be used in production code.
Functions
geocode_backend_forward_search_async ()
void geocode_backend_forward_search_async (GeocodeBackend *backend
,GHashTable *params
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
);
Asynchronously performs a forward geocoding query using the backend
. Use
geocode_backend_forward_search()
to do the same thing synchronously.
The params
hash table is in the format used by Telepathy, and documented
in the Telepathy specification.
See also: XEP-0080 specification.
When the operation is finished, callback
will be called. You can then call
geocode_backend_forward_search_finish()
to get the result of the operation.
Parameters
backend |
||
params |
a GHashTable with string keys, and GValue values. |
[transfer none][element-type utf8 GValue] |
cancellable |
optional GCancellable, |
|
callback |
a GAsyncReadyCallback to call when the request is satisfied |
|
user_data |
the data to pass to the |
Since: 3.23.1
geocode_backend_forward_search_finish ()
GList * geocode_backend_forward_search_finish (GeocodeBackend *backend
,GAsyncResult *result
,GError **error
);
Finishes a forward geocoding operation. See
geocode_backend_forward_search_async()
.
Returns
A list of
places or NULL
in case of errors. Free the returned instances with
g_object_unref()
and the list with g_list_free()
when done.
[element-type GeocodePlace][transfer full]
Since: 3.23.1
geocode_backend_forward_search ()
GList * geocode_backend_forward_search (GeocodeBackend *backend
,GHashTable *params
,GCancellable *cancellable
,GError **error
);
Gets the result of a forward geocoding query using the backend
.
If no results are found, a GEOCODE_ERROR_NO_MATCHES
error is returned.
This is a synchronous function, which means it may block on network requests.
In most situations, the asynchronous version
(geocode_backend_forward_search_async()
) is more appropriate. See its
documentation for more information on usage.
Parameters
backend |
||
params |
a GHashTable with string keys, and GValue values. |
[transfer none][element-type utf8 GValue] |
cancellable |
optional GCancellable, |
|
error |
a GError |
Returns
A list of
places or NULL
in case of errors. Free the returned instances with
g_object_unref()
and the list with g_list_free()
when done.
[element-type GeocodePlace][transfer full]
Since: 3.23.1
geocode_backend_reverse_resolve_async ()
void geocode_backend_reverse_resolve_async (GeocodeBackend *backend
,GHashTable *params
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
);
Asynchronously gets the result of a reverse geocoding query using the backend.
Typically, a single result will be returned representing the place at a
given latitude and longitude (the lat
and lon
keys to params
); but in
some cases the results will be ambiguous and *multiple* results will be
returned. They will be returned in order of relevance, with the most
relevant result first in the list.
The params
hash table is in the format used by Telepathy, and documented
in the Telepathy specification.
See also: XEP-0080 specification.
Use geocode_backend_reverse_resolve()
to do the same thing synchronously.
When the operation is finished, callback
will be called. You can then call
geocode_backend_reverse_resolve_finish()
to get the result of the operation.
Parameters
backend |
||
params |
a GHashTable with string keys, and GValue values. |
[transfer none][element-type utf8 GValue] |
cancellable |
optional GCancellable object, |
|
callback |
a GAsyncReadyCallback to call when the request is satisfied. |
|
user_data |
the data to pass to callback function. |
Since: 3.23.1
geocode_backend_reverse_resolve_finish ()
GList * geocode_backend_reverse_resolve_finish (GeocodeBackend *backend
,GAsyncResult *result
,GError **error
);
Finishes a reverse geocoding operation. See geocode_backend_reverse_resolve_async()
.
Returns
A list of
GeocodePlace instances, or NULL
in case of errors. The list is ordered
by relevance, with most relevant results first. Free the returned
instances with g_object_unref()
and the list with g_list_free()
when done.
[transfer full][element-type GeocodePlace]
Since: 3.23.1
geocode_backend_reverse_resolve ()
GList * geocode_backend_reverse_resolve (GeocodeBackend *backend
,GHashTable *params
,GCancellable *cancellable
,GError **error
);
Gets the result of a reverse geocoding query using the backend
.
If no result could be found, a GEOCODE_ERROR_NOT_SUPPORTED
error will be
returned. This typically happens if the coordinates to geocode are in the
middle of the ocean.
This is a synchronous function, which means it may block on network requests.
In most situations, the asynchronous version,
geocode_backend_forward_search_async()
, is more appropriate. See its
documentation for more information on usage.
Parameters
backend |
||
params |
a GHashTable with string keys, and GValue values. |
[transfer none][element-type utf8 GValue] |
cancellable |
optional GCancellable object, |
|
error |
a GError. |
Returns
A list of
GeocodePlace instances, or NULL
in case of errors. The list is ordered
by relevance, with most relevant results first. Free the returned
instances with g_object_unref()
and the list with g_list_free()
when done.
[transfer full][element-type GeocodePlace]
Since: 3.23.1
Types and Values
GEOCODE_TYPE_BACKEND
#define GEOCODE_TYPE_BACKEND (geocode_backend_get_type ())
See GeocodeBackend.
Since: 3.23.1
struct GeocodeBackendInterface
struct GeocodeBackendInterface { /* Forward */ GList *(*forward_search) (GeocodeBackend *backend, GHashTable *params, GCancellable *cancellable, GError **error); void (*forward_search_async) (GeocodeBackend *backend, GHashTable *params, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data); GList *(*forward_search_finish) (GeocodeBackend *backend, GAsyncResult *result, GError **error); /* Reverse */ GList *(*reverse_resolve) (GeocodeBackend *backend, GHashTable *params, GCancellable *cancellable, GError **error); void (*reverse_resolve_async) (GeocodeBackend *backend, GHashTable *params, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data); GList *(*reverse_resolve_finish) (GeocodeBackend *backend, GAsyncResult *result, GError **error); };
Interface which defines the basic operations for geocoding.
Members
handles a synchronous forward geocoding request. |
||
starts an asynchronous forward geocoding request. |
||
finishes an asynchronous forward geocoding request. |
||
handles a synchronous reverse geocoding request. |
||
starts an asynchronous reverse geocoding request. |
||
finishes an asynchronous reverse geocoding request. |
Since: 3.23.1
GeocodeBackend
typedef struct _GeocodeBackend GeocodeBackend;
All the fields in the GeocodeBackend structure are private and should never be accessed directly.
Since: 3.23.1