manpagez: man pages & more
html files: gio
Home | html | info | man

GResolver

GResolver — Asynchronous and cancellable DNS resolver

Signals

Types and Values

Object Hierarchy

    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.

[allow-none]

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.

[allow-none]

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

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.

[allow-none]

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.

[allow-none]

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.

[allow-none]

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.

[allow-none]

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

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 lookup the record for

 

record_type

the type of DNS record to lookup

 

cancellable

a GCancellable, or NULL.

[allow-none]

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 lookup the record for

 

record_type

the type of DNS record to lookup

 

cancellable

a GCancellable, or NULL.

[allow-none]

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


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.

Types and Values

GResolver

typedef struct _GResolver GResolver;

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


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.

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

lookup DNS SRV records for a domain

 

G_RESOLVER_RECORD_MX

lookup DNS MX records for a domain

 

G_RESOLVER_RECORD_TXT

lookup DNS TXT records for a name

 

G_RESOLVER_RECORD_SOA

lookup DNS SOA records for a zone

 

G_RESOLVER_RECORD_NS

lookup DNS NS records for a domain

 

Since 2.34


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

© manpagez.com 2000-2024
Individual documents may contain additional copyright information.