GResolver: GIO Reference Manual

## GResolver GResolver — Asynchronous and cancellable DNS resolver |

## Functions

GResolver * | g_resolver_get_default ()
void | g_resolver_set_default ()
GList * | g_resolver_lookup_by_name ()
void | g_resolver_lookup_by_name_async ()
GList * | g_resolver_lookup_by_name_finish ()
GList * | g_resolver_lookup_by_name_with_flags ()
void | g_resolver_lookup_by_name_with_flags_async ()
GList * | g_resolver_lookup_by_name_with_flags_finish ()
void | g_resolver_free_addresses ()
gchar * | g_resolver_lookup_by_address ()
void | g_resolver_lookup_by_address_async ()
gchar * | g_resolver_lookup_by_address_finish ()
GList * | g_resolver_lookup_service ()
void | g_resolver_lookup_service_async ()
GList * | g_resolver_lookup_service_finish ()
void | g_resolver_free_targets ()
GList * | g_resolver_lookup_records ()
void | g_resolver_lookup_records_async ()
GList * | g_resolver_lookup_records_finish ()

## Signals

void | reload | Run Last

## Types and Values

| GResolver
enum | GResolverNameLookupFlags
enum | GResolverRecordType
#define | G_RESOLVER_ERROR
enum | GResolverError

## Object Hierarchy

        GEnum
        ├── GResolverError
        ╰── GResolverRecordType
        GFlags
        ╰── GResolverNameLookupFlags
        GObject
        ╰── GResolver

## Includes

    #include <gio/gio.h>

## Description

GResolver provides cancellable synchronous and asynchronous DNS resolution, for hostnames (`g_resolver_lookup_by_address()`, `g_resolver_lookup_by_name()` and their async variants) and SRV (service) records (`g_resolver_lookup_service()`).

GNetworkAddress and GNetworkService provide wrappers around GResolver functionality that also implement GSocketConnectable, making it easy to connect to a remote host/service.

## Functions

### g_resolver_get_default ()

    GResolver *
    g_resolver_get_default (void);

Gets the default GResolver. You should unref it when you are done with it. GResolver may use its reference count as a hint about how many threads it should allocate for concurrent DNS resolutions.

#### Returns

the default GResolver.

[transfer full]

Since: 2.22

### g_resolver_set_default ()

    void
    g_resolver_set_default (GResolver *resolver);

Sets `resolver` to be the application's default resolver (reffing `resolver` , and unreffing the previous default resolver, if any). Future calls to `g_resolver_get_default()` will return this resolver.

This can be used if an application wants to perform any sort of DNS caching or "pinning"; it can implement its own GResolver that calls the original default resolver for DNS operations, and implements its own cache policies on top of that, and then set itself as the default resolver for all later code to use.

#### Parameters

resolver | the new default GResolver |

Since: 2.22

### g_resolver_lookup_by_name ()

    GList *
    g_resolver_lookup_by_name (GResolver *resolver,
                               const gchar *hostname,
                               GCancellable *cancellable,
                               GError **error);

Synchronously resolves `hostname` to determine its associated IP address(es). `hostname` may be an ASCII-only or UTF-8 hostname, or the textual form of an IP address (in which case this just becomes a wrapper around `g_inet_address_new_from_string()`).

On success, `g_resolver_lookup_by_name()` will return a non-empty GList of GInetAddress, sorted in order of preference and guaranteed to not contain duplicates. That is, if using the result to connect to `hostname` , you should attempt to connect to the first address first, then the second if the first fails, etc. If you are using the result to listen on a socket, it is appropriate to add each result using e.g. `g_socket_listener_add_address()`.

If the DNS resolution fails, `error` (if non-`NULL`) will be set to a value from GResolverError and `NULL` will be returned.

If `cancellable` is non-`NULL`, it can be used to cancel the operation, in which case `error` (if non-`NULL`) will be set to `G_IO_ERROR_CANCELLED`.

If you are planning to connect to a socket on the resolved IP address, it may be easier to create a GNetworkAddress and use its GSocketConnectable interface.

#### Parameters

resolver | a GResolver |
hostname | the hostname to look up |
cancellable | a GCancellable, or `NULL`. | [nullable]
error | return location for a GError, or `NULL` |

#### Returns

a non-empty GList of GInetAddress, or `NULL` on error. You must unref each of the addresses and free the list when you are done with it. (You can use `g_resolver_free_addresses()` to do this.).

[element-type GInetAddress][transfer full]

Since: 2.22

### g_resolver_lookup_by_name_async ()

    void
    g_resolver_lookup_by_name_async (GResolver *resolver,
                                     const gchar *hostname,
                                     GCancellable *cancellable,
                                     GAsyncReadyCallback callback,
                                     gpointer user_data);

Begins asynchronously resolving `hostname` to determine its associated IP address(es), and eventually calls `callback` , which must call `g_resolver_lookup_by_name_finish()` to get the result. See `g_resolver_lookup_by_name()` for more details.

#### Parameters

resolver | a GResolver |
hostname | the hostname to look up the address of |
cancellable | a GCancellable, or `NULL`. | [nullable]
callback | callback to call after resolution completes. | [scope async]
user_data | data for `callback` . | [closure]

Since: 2.22

### g_resolver_lookup_by_name_finish ()

    GList *
    g_resolver_lookup_by_name_finish (GResolver *resolver,
                                      GAsyncResult *result,
                                      GError **error);

Retrieves the result of a call to `g_resolver_lookup_by_name_async()`.

If the DNS resolution failed, `error` (if non-`NULL`) will be set to a value from GResolverError. If the operation was cancelled, `error` will be set to `G_IO_ERROR_CANCELLED`.

#### Parameters

resolver | a GResolver |
result | the result passed to your GAsyncReadyCallback |
error | return location for a GError, or `NULL` |

#### Returns

a GList of GInetAddress, or `NULL` on error. See `g_resolver_lookup_by_name()` for more details.

[element-type GInetAddress][transfer full]

Since: 2.22

### g_resolver_lookup_by_name_with_flags ()

    GList *
    g_resolver_lookup_by_name_with_flags (GResolver *resolver,
                                          const gchar *hostname,
                                          GResolverNameLookupFlags flags,
                                          GCancellable *cancellable,
                                          GError **error);

This differs from `g_resolver_lookup_by_name()` in that you can modify the lookup behavior with `flags` . For example this can be used to limit results with G_RESOLVER_NAME_LOOKUP_FLAGS_IPV4_ONLY.

#### Parameters

resolver | a GResolver |
hostname | the hostname to look up |
flags | extra GResolverNameLookupFlags for the lookup |
cancellable | a GCancellable, or `NULL`. | [nullable]
error | return location for a GError, or `NULL`. | [nullable]

#### Returns

a non-empty GList of GInetAddress, or `NULL` on error. You must unref each of the addresses and free the list when you are done with it. (You can use `g_resolver_free_addresses()` to do this.).

[element-type GInetAddress][transfer full]

Since: 2.60

### g_resolver_lookup_by_name_with_flags_async ()

    void
    g_resolver_lookup_by_name_with_flags_async
                                   (GResolver *resolver,
                                    const gchar *hostname,
                                    GResolverNameLookupFlags flags,
                                    GCancellable *cancellable,
                                    GAsyncReadyCallback callback,
                                    gpointer user_data);

Begins asynchronously resolving `hostname` to determine its associated IP address(es), and eventually calls `callback` , which must call `g_resolver_lookup_by_name_with_flags_finish()` to get the result. See `g_resolver_lookup_by_name()` for more details.

#### Parameters

resolver | a GResolver |
hostname | the hostname to look up the address of |
flags | extra GResolverNameLookupFlags for the lookup |
cancellable | a GCancellable, or `NULL`. | [nullable]
callback | callback to call after resolution completes. | [scope async]
user_data | data for `callback` . | [closure]

Since: 2.60

### g_resolver_lookup_by_name_with_flags_finish ()

    GList *
    g_resolver_lookup_by_name_with_flags_finish
                                   (GResolver *resolver,
                                    GAsyncResult *result,
                                    GError **error);

Retrieves the result of a call to `g_resolver_lookup_by_name_with_flags_async()`.

If the DNS resolution failed, `error` (if non-`NULL`) will be set to a value from GResolverError. If the operation was cancelled, `error` will be set to `G_IO_ERROR_CANCELLED`.

#### Parameters

resolver | a GResolver |
result | the result passed to your GAsyncReadyCallback |
error | return location for a GError, or `NULL` |

#### Returns

a GList of GInetAddress, or `NULL` on error. See `g_resolver_lookup_by_name()` for more details.

[element-type GInetAddress][transfer full]

Since: 2.60

### g_resolver_free_addresses ()

    void
    g_resolver_free_addresses (GList *addresses);

Frees `addresses` (which should be the return value from `g_resolver_lookup_by_name()` or `g_resolver_lookup_by_name_finish()`). (This is a convenience method; you can also simply free the results by hand.)

[skip]

#### Parameters

addresses | a GList of GInetAddress |

Since: 2.22

### g_resolver_lookup_by_address ()

    gchar *
    g_resolver_lookup_by_address (GResolver *resolver,
                                  GInetAddress *address,
                                  GCancellable *cancellable,
                                  GError **error);

Synchronously reverse-resolves `address` to determine its associated hostname.

If the DNS resolution fails, `error` (if non-`NULL`) will be set to a value from GResolverError.

If `cancellable` is non-`NULL`, it can be used to cancel the operation, in which case `error` (if non-`NULL`) will be set to `G_IO_ERROR_CANCELLED`.

#### Parameters

resolver | a GResolver |
address | the address to reverse-resolve |
cancellable | a GCancellable, or `NULL`. | [nullable]
error | return location for a GError, or `NULL` |

#### Returns

a hostname (either ASCII-only, or in ASCII-encoded form), or `NULL` on error.

Since: 2.22

### g_resolver_lookup_by_address_async ()

    void
    g_resolver_lookup_by_address_async (GResolver *resolver,
                                        GInetAddress *address,
                                        GCancellable *cancellable,
                                        GAsyncReadyCallback callback,
                                        gpointer user_data);

Begins asynchronously reverse-resolving `address` to determine its associated hostname, and eventually calls `callback` , which must call `g_resolver_lookup_by_address_finish()` to get the final result.

#### Parameters

resolver | a GResolver |
address | the address to reverse-resolve |
cancellable | a GCancellable, or `NULL`. | [nullable]
callback | callback to call after resolution completes. | [scope async]
user_data | data for `callback` . | [closure]

Since: 2.22

### g_resolver_lookup_by_address_finish ()

    gchar *
    g_resolver_lookup_by_address_finish (GResolver *resolver,
                                         GAsyncResult *result,
                                         GError **error);

Retrieves the result of a previous call to `g_resolver_lookup_by_address_async()`.

If the DNS resolution failed, `error` (if non-`NULL`) will be set to a value from GResolverError. If the operation was cancelled, `error` will be set to `G_IO_ERROR_CANCELLED`.

#### Parameters

resolver | a GResolver |
result | the result passed to your GAsyncReadyCallback |
error | return location for a GError, or `NULL` |

#### Returns

a hostname (either ASCII-only, or in ASCII-encoded form), or `NULL` on error.

Since: 2.22

### g_resolver_lookup_service ()

    GList *
    g_resolver_lookup_service (GResolver *resolver,
                               const gchar *service,
                               const gchar *protocol,
                               const gchar *domain,
                               GCancellable *cancellable,
                               GError **error);

Synchronously performs a DNS SRV lookup for the given `service` and `protocol` in the given `domain` and returns an array of GSrvTarget. `domain` may be an ASCII-only or UTF-8 hostname. Note also that the `service` and `protocol` arguments do not include the leading underscore that appears in the actual DNS entry.

On success, `g_resolver_lookup_service()` will return a non-empty GList of GSrvTarget, sorted in order of preference. (That is, you should attempt to connect to the first target first, then the second if the first fails, etc.)

If the DNS resolution fails, `error` (if non-`NULL`) will be set to a value from GResolverError and `NULL` will be returned.

If `cancellable` is non-`NULL`, it can be used to cancel the operation, in which case `error` (if non-`NULL`) will be set to `G_IO_ERROR_CANCELLED`.

If you are planning to connect to the service, it is usually easier to create a GNetworkService and use its GSocketConnectable interface.

#### Parameters

resolver | a GResolver |
service | the service type to look up (eg, "ldap") |
protocol | the networking protocol to use for `service` (eg, "tcp") |
domain | the DNS domain to look up the service in |
cancellable | a GCancellable, or `NULL`. | [nullable]
error | return location for a GError, or `NULL` |

#### Returns

a non-empty GList of GSrvTarget, or `NULL` on error. You must free each of the targets and the list when you are done with it. (You can use `g_resolver_free_targets()` to do this.).

[element-type GSrvTarget][transfer full]

Since: 2.22

### g_resolver_lookup_service_async ()

    void
    g_resolver_lookup_service_async (GResolver *resolver,
                                     const gchar *service,
                                     const gchar *protocol,
                                     const gchar *domain,
                                     GCancellable *cancellable,
                                     GAsyncReadyCallback callback,
                                     gpointer user_data);

Begins asynchronously performing a DNS SRV lookup for the given `service` and `protocol` in the given `domain` , and eventually calls `callback` , which must call `g_resolver_lookup_service_finish()` to get the final result. See `g_resolver_lookup_service()` for more details.

#### Parameters

resolver | a GResolver |
service | the service type to look up (eg, "ldap") |
protocol | the networking protocol to use for `service` (eg, "tcp") |
domain | the DNS domain to look up the service in |
cancellable | a GCancellable, or `NULL`. | [nullable]
callback | callback to call after resolution completes. | [scope async]
user_data | data for `callback` . | [closure]

Since: 2.22

### g_resolver_lookup_service_finish ()

    GList *
    g_resolver_lookup_service_finish (GResolver *resolver,
                                      GAsyncResult *result,
                                      GError **error);

Retrieves the result of a previous call to `g_resolver_lookup_service_async()`.

If the DNS resolution failed, `error` (if non-`NULL`) will be set to a value from GResolverError. If the operation was cancelled, `error` will be set to `G_IO_ERROR_CANCELLED`.

#### Parameters

resolver | a GResolver |
result | the result passed to your GAsyncReadyCallback |
error | return location for a GError, or `NULL` |

#### Returns

a non-empty GList of GSrvTarget, or `NULL` on error. See `g_resolver_lookup_service()` for more details.

[element-type GSrvTarget][transfer full]

Since: 2.22

### g_resolver_free_targets ()

    void
    g_resolver_free_targets (GList *targets);

Frees `targets` (which should be the return value from `g_resolver_lookup_service()` or `g_resolver_lookup_service_finish()`). (This is a convenience method; you can also simply free the results by hand.)

[skip]

#### Parameters

targets | a GList of GSrvTarget |

Since: 2.22

### g_resolver_lookup_records ()

    GList *
    g_resolver_lookup_records (GResolver *resolver,
                               const gchar *rrname,
                               GResolverRecordType record_type,
                               GCancellable *cancellable,
                               GError **error);

Synchronously performs a DNS record lookup for the given `rrname` and returns a list of records as GVariant tuples. See GResolverRecordType for information on what the records contain for each `record_type` .

If the DNS resolution fails, `error` (if non-`NULL`) will be set to a value from GResolverError and `NULL` will be returned.

If `cancellable` is non-`NULL`, it can be used to cancel the operation, in which case `error` (if non-`NULL`) will be set to `G_IO_ERROR_CANCELLED`.

#### Parameters

resolver | a GResolver |
rrname | the DNS name to look up the record for |
record_type | the type of DNS record to look up |
cancellable | a GCancellable, or `NULL`. | [nullable]
error | return location for a GError, or `NULL` |

#### Returns

a non-empty GList of GVariant, or `NULL` on error. You must free each of the records and the list when you are done with it. (You can use `g_list_free_full()` with `g_variant_unref()` to do this.).

[element-type GVariant][transfer full]

Since: 2.34

### g_resolver_lookup_records_async ()

    void
    g_resolver_lookup_records_async (GResolver *resolver,
                                     const gchar *rrname,
                                     GResolverRecordType record_type,
                                     GCancellable *cancellable,
                                     GAsyncReadyCallback callback,
                                     gpointer user_data);

Begins asynchronously performing a DNS lookup for the given `rrname` , and eventually calls `callback` , which must call `g_resolver_lookup_records_finish()` to get the final result. See `g_resolver_lookup_records()` for more details.

#### Parameters

resolver | a GResolver |
rrname | the DNS name to look up the record for |
record_type | the type of DNS record to look up |
cancellable | a GCancellable, or `NULL`. | [nullable]
callback | callback to call after resolution completes. | [scope async]
user_data | data for `callback` . | [closure]

Since: 2.34

### g_resolver_lookup_records_finish ()

    GList *
    g_resolver_lookup_records_finish (GResolver *resolver,
                                      GAsyncResult *result,
                                      GError **error);

Retrieves the result of a previous call to `g_resolver_lookup_records_async()`. Returns a non-empty list of records as GVariant tuples. See GResolverRecordType for information on what the records contain.

If the DNS resolution failed, `error` (if non-`NULL`) will be set to a value from GResolverError. If the operation was cancelled, `error` will be set to `G_IO_ERROR_CANCELLED`.

#### Parameters

resolver | a GResolver |
result | the result passed to your GAsyncReadyCallback |
error | return location for a GError, or `NULL` |

#### Returns

a non-empty GList of GVariant, or `NULL` on error. You must free each of the records and the list when you are done with it. (You can use `g_list_free_full()` with `g_variant_unref()` to do this.).

[element-type GVariant][transfer full]

Since: 2.34

## Types and Values

### GResolver

    typedef struct _GResolver GResolver;

The object that handles DNS resolution. Use `g_resolver_get_default()` to get the default resolver.

This is an abstract type; subclasses of it implement different resolvers for different platforms and situations.

### enum GResolverNameLookupFlags

Flags to modify lookup behavior.

#### Members

G_RESOLVER_NAME_LOOKUP_FLAGS_DEFAULT | default behavior (same as `g_resolver_lookup_by_name()`) |
G_RESOLVER_NAME_LOOKUP_FLAGS_IPV4_ONLY | only resolve ipv4 addresses |
G_RESOLVER_NAME_LOOKUP_FLAGS_IPV6_ONLY | only resolve ipv6 addresses |

Since: 2.60

### enum GResolverRecordType

The type of record that `g_resolver_lookup_records()` or `g_resolver_lookup_records_async()` should retrieve. The records are returned as lists of GVariant tuples. Each record type has different values in the variant tuples returned.

`G_RESOLVER_RECORD_SRV` records are returned as variants with the signature `(qqqs)`, containing a `guint16` with the priority, a `guint16` with the weight, a `guint16` with the port, and a string of the hostname.

`G_RESOLVER_RECORD_MX` records are returned as variants with the signature `(qs)`, representing a `guint16` with the preference, and a string containing the mail exchanger hostname.

`G_RESOLVER_RECORD_TXT` records are returned as variants with the signature `(as)`, representing an array of the strings in the text record. Note: Most TXT records only contain a single string, but RFC 1035 does allow a record to contain multiple strings. The RFC which defines the interpretation of a specific TXT record will likely require concatenation of multiple strings if they are present, as with RFC 7208.

`G_RESOLVER_RECORD_SOA` records are returned as variants with the signature `(ssuuuuu)`, representing a string containing the primary name server, a string containing the administrator, the serial as a `guint32`, the refresh interval as a `guint32`, the retry interval as a `guint32`, the expire timeout as a `guint32`, and the TTL as a `guint32`.

`G_RESOLVER_RECORD_NS` records are returned as variants with the signature `(s)`, representing a string of the hostname of the name server.

#### Members

G_RESOLVER_RECORD_SRV | look up DNS SRV records for a domain |
G_RESOLVER_RECORD_MX | look up DNS MX records for a domain |
G_RESOLVER_RECORD_TXT | look up DNS TXT records for a name |
G_RESOLVER_RECORD_SOA | look up DNS SOA records for a zone |
G_RESOLVER_RECORD_NS | look up DNS NS records for a domain |

Since: 2.34

### G_RESOLVER_ERROR

    #define G_RESOLVER_ERROR (g_resolver_error_quark ())

Error domain for GResolver. Errors in this domain will be from the GResolverError enumeration. See GError for more information on error domains.

### enum GResolverError

An error code used with `G_RESOLVER_ERROR` in a GError returned from a GResolver routine.

#### Members

G_RESOLVER_ERROR_NOT_FOUND | the requested name/address/service was not found |
G_RESOLVER_ERROR_TEMPORARY_FAILURE | the requested information could not be looked up due to a network error or similar problem |
G_RESOLVER_ERROR_INTERNAL | unknown error |

Since: 2.22

## Signal Details

### The `“reload”` signal

    void
    user_function (GResolver *resolver,
                   gpointer   user_data)

Emitted when the resolver notices that the system resolver configuration has changed.

#### Parameters

resolver | a GResolver |
user_data | user data set when the signal handler was connected. |

Flags: Run Last