GeocodeBackend: geocode-glib Reference Manual

GeocodeBackend

GeocodeBackend — Geocode backend object

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 ()

Types and Values

#define	GEOCODE_TYPE_BACKEND
struct	GeocodeBackendInterface
	GeocodeBackend

Object Hierarchy

    GInterface
    ╰── GeocodeBackend

Prerequisites

GeocodeBackend requires GObject.

Known Implementations

GeocodeBackend is implemented by GeocodeMockBackend and GeocodeNominatim.

Includes

#include <geocode-glib/geocode-glib.h>

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.

Parameters

backend	a GeocodeBackend.
params	a GHashTable with string keys, and GValue values.	[transfer none][element-type utf8 GValue]
cancellable	optional GCancellable, `NULL` to ignore.
callback	a GAsyncReadyCallback to call when the request is satisfied
user_data	the data to pass to the `callback` function

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().

Parameters

backend	a GeocodeBackend.
result	a GAsyncResult.
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_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	a GeocodeBackend.
params	a GHashTable with string keys, and GValue values.	[transfer none][element-type utf8 GValue]
cancellable	optional GCancellable, `NULL` to ignore.
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.

Parameters

backend	a GeocodeBackend.
params	a GHashTable with string keys, and GValue values.	[transfer none][element-type utf8 GValue]
cancellable	optional GCancellable object, `NULL` to ignore.
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().

Parameters

backend	a GeocodeBackend.
result	a GAsyncResult.
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

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	a GeocodeBackend.
params	a GHashTable with string keys, and GValue values.	[transfer none][element-type utf8 GValue]
cancellable	optional GCancellable object, `NULL` to ignore.
error	a GError.

Returns

[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

`forward_search` ()	handles a synchronous forward geocoding request.
`forward_search_async` ()	starts an asynchronous forward geocoding request.
`forward_search_finish` ()	finishes an asynchronous forward geocoding request.
`reverse_resolve` ()	handles a synchronous reverse geocoding request.
`reverse_resolve_async` ()	starts an asynchronous reverse geocoding request.
`reverse_resolve_finish` ()	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