## GeocodeForward

GeocodeForward — Geocode forward geocoding object

## Synopsis

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

    struct              GeocodeForward;
    struct              GeocodeForwardClass;
    GeocodeForward *    geocode_forward_new_for_string      (const char *str);
    GeocodeForward *    geocode_forward_new_for_params      (GHashTable *params);
    void                geocode_forward_set_answer_count    (GeocodeForward *forward,
                                                             guint count);
    void                geocode_forward_search_async        (GeocodeForward *forward,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GList *             geocode_forward_search_finish       (GeocodeForward *forward,
                                                             GAsyncResult *res,
                                                             GError **error);
    GList *             geocode_forward_search              (GeocodeForward *forward,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----GeocodeForward

## Description

Contains functions for geocoding using the OSM Nominatim APIs

## Details

### struct GeocodeForward

    struct GeocodeForward;

All the fields in the GeocodeForward structure are private and should never be accessed directly.

### struct GeocodeForwardClass

    struct GeocodeForwardClass {
    };

All the fields in the GeocodeForwardClass structure are private and should never be accessed directly.

### geocode_forward_new_for_string ()

    GeocodeForward *    geocode_forward_new_for_string      (const char *str);

Creates a new GeocodeForward to perform forward geocoding with. The string is in free-form format.

`str` : | a string containing a free-form description of the location
Returns : | a new GeocodeForward. Use `g_object_unref()` when done.

### geocode_forward_new_for_params ()

    GeocodeForward *    geocode_forward_new_for_params      (GHashTable *params);

Creates a new GeocodeForward to perform geocoding with. The GHashTable is in the format used by Telepathy, and documented on Telepathy's specification site.

See also: XEP-0080 specification.

`params` : | a GHashTable with string keys, and GValue values. [transfer none][element-type utf8 GValue]
Returns : | a new GeocodeForward. Use `g_object_unref()` when done.

### geocode_forward_set_answer_count ()

    void                geocode_forward_set_answer_count    (GeocodeForward *forward,
                                                             guint count);

Sets the number of requested results to `count`.

`forward` : | a GeocodeForward representing a query
`count` : | the number of requested results

### geocode_forward_search_async ()

    void                geocode_forward_search_async        (GeocodeForward *forward,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously performs a forward geocoding query using a web service. Use `geocode_forward_search()` to do the same thing synchronously.

When the operation is finished, `callback` will be called. You can then call `geocode_forward_search_finish()` to get the result of the operation.

`forward` : | a GeocodeForward representing a query
`cancellable` : | optional GCancellable forward, `NULL` to ignore.
`callback` : | a GAsyncReadyCallback to call when the request is satisfied
`user_data` : | the data to pass to callback function

### geocode_forward_search_finish ()

    GList *             geocode_forward_search_finish       (GeocodeForward *forward,
                                                             GAsyncResult *res,
                                                             GError **error);

Finishes a forward geocoding operation. See `geocode_forward_search_async()`.

`forward` : | a GeocodeForward representing a query
`res` : | a GAsyncResult.
`error` : | a GError.
Returns : | A list of places or `NULL` in case of errors. Free the returned list with `g_list_free()` when done. [element-type GeocodePlace][transfer container]

### geocode_forward_search ()

    GList *             geocode_forward_search              (GeocodeForward *forward,
                                                             GError **error);

Gets the result of a forward geocoding query using a web service.

`forward` : | a GeocodeForward representing a query
`error` : | a GError
Returns : | A list of places or `NULL` in case of errors. Free the returned list with `g_list_free()` when done. [element-type GeocodePlace][transfer container]