Package org.gnome.gio

Class Resolver

java.lang.Object

io.github.jwharm.javagi.base.ProxyInstance

org.gnome.gobject.TypeInstance

org.gnome.gobject.GObject

org.gnome.gio.Resolver

All Implemented Interfaces:

Proxy

Direct Known Subclasses:

Resolver.ResolverImpl, ThreadedResolver

@Generated("io.github.jwharm.JavaGI")
public abstract class Resolver
extends GObject

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

GResolver provides cancellable synchronous and asynchronous DNS resolution, for hostnames (lookupByAddress(org.gnome.gio.InetAddress, org.gnome.gio.Cancellable), lookupByName(java.lang.String, org.gnome.gio.Cancellable) and their async variants) and SRV (service) records (lookupService(java.lang.String, java.lang.String, java.lang.String, org.gnome.gio.Cancellable)).

NetworkAddress and NetworkService provide wrappers around GResolver functionality that also implement SocketConnectable, making it easy to connect to a remote host/service.

The default resolver (see getDefault()) has a timeout of 30s set on it since GLib 2.78. Earlier versions of GLib did not support resolver timeouts.

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

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Resolver.Builder<B extends Resolver.Builder<B>>	Inner class implementing a builder pattern to construct a GObject with properties.
static interface	Resolver.ReloadCallback	Functional interface declaration of the ReloadCallback callback.
static class	Resolver.ResolverClass
static class	Resolver.ResolverImpl	The ResolverImpl type represents a native instance of the abstract Resolver class.

Nested classes/interfaces inherited from class org.gnome.gobject.GObject

GObject.NotifyCallback, GObject.ObjectClass

Constructor Summary

Constructors

Constructor	Description
Resolver(MemorySegment address)	Create a Resolver proxy instance for the provided memory address.

Method Summary

Modifier and Type	Method	Description
protected Resolver	asParent()	Returns this instance as if it were its parent type.
static Resolver.Builder<? extends Resolver.Builder>	builder()	A Resolver.Builder object constructs a Resolver with the specified properties.
void	emitReload()	Emits the "reload" signal.
static void	freeAddresses(List<MemorySegment> addresses)	Frees addresses (which should be the return value from g_resolver_lookup_by_name() or g_resolver_lookup_by_name_finish()).
static void	freeTargets(List<MemorySegment> targets)	Frees targets (which should be the return value from g_resolver_lookup_service() or g_resolver_lookup_service_finish()).
static Resolver	getDefault()	Gets the default GResolver.
static MemoryLayout	getMemoryLayout()	The memory layout of the native struct.
int	getTimeout()	Get the timeout applied to all resolver lookups.
static Type	getType()	Get the GType of the Resolver class
String	lookupByAddress(InetAddress address, @Nullable Cancellable cancellable)	Synchronously reverse-resolves address to determine its associated hostname.
void	lookupByAddressAsync(InetAddress address, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback)	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.
String	lookupByAddressFinish(AsyncResult result)	Retrieves the result of a previous call to g_resolver_lookup_by_address_async().
List<InetAddress>	lookupByName(String hostname, @Nullable Cancellable cancellable)	Synchronously resolves hostname to determine its associated IP address(es).
void	lookupByNameAsync(String hostname, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback)	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.
List<InetAddress>	lookupByNameFinish(AsyncResult result)	Retrieves the result of a call to g_resolver_lookup_by_name_async().
List<InetAddress>	lookupByNameWithFlags(String hostname, Set<ResolverNameLookupFlags> flags, @Nullable Cancellable cancellable)	This differs from g_resolver_lookup_by_name() in that you can modify the lookup behavior with flags.
List<InetAddress>	lookupByNameWithFlags(String hostname, ResolverNameLookupFlags flags, @Nullable Cancellable cancellable)	This differs from g_resolver_lookup_by_name() in that you can modify the lookup behavior with flags.
void	lookupByNameWithFlagsAsync(String hostname, Set<ResolverNameLookupFlags> flags, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback)	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.
void	lookupByNameWithFlagsAsync(String hostname, ResolverNameLookupFlags flags, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback)	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.
List<InetAddress>	lookupByNameWithFlagsFinish(AsyncResult result)	Retrieves the result of a call to g_resolver_lookup_by_name_with_flags_async().
List<Variant>	lookupRecords(String rrname, ResolverRecordType recordType, @Nullable Cancellable cancellable)	Synchronously performs a DNS record lookup for the given rrname and returns a list of records as GVariant tuples.
void	lookupRecordsAsync(String rrname, ResolverRecordType recordType, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback)	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.
List<Variant>	lookupRecordsFinish(AsyncResult result)	Retrieves the result of a previous call to g_resolver_lookup_records_async().
List<SrvTarget>	lookupService(String service, String protocol, String domain, @Nullable Cancellable cancellable)	Synchronously performs a DNS SRV lookup for the given service and protocol in the given domain and returns an array of GSrvTarget.
protected List<MemorySegment>	lookupService(String rrname, @Nullable Cancellable cancellable)
void	lookupServiceAsync(String service, String protocol, String domain, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback)	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.
protected void	lookupServiceAsync(String rrname, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback)
List<SrvTarget>	lookupServiceFinish(AsyncResult result)	Retrieves the result of a previous call to g_resolver_lookup_service_async().
SignalConnection<Resolver.ReloadCallback>	onReload(Resolver.ReloadCallback handler)	Emitted when the resolver notices that the system resolver configuration has changed.
protected void	reload()
void	setDefault()	Sets this Resolver to be the application's default resolver (reffing this Resolver, and unreffing the previous default resolver, if any).
void	setTimeout(int timeoutMs)	Set the timeout applied to all resolver lookups.

Methods inherited from class org.gnome.gobject.GObject

addToggleRef, addWeakPointer, bindProperty, bindProperty, bindProperty, bindPropertyFull, bindPropertyFull, bindPropertyWithClosures, bindPropertyWithClosures, compatControl, connect, connect, connect, constructed, disconnect, dispatchPropertiesChanged, dispose, dupData, dupQdata, emit, emitNotify, finalize_, forceFloating, freezeNotify, get, getData, getProperty, getProperty, getProperty, getQdata, getv, interfaceFindProperty, interfaceInstallProperty, interfaceListProperties, isFloating, newInstance, newInstance, newInstance, newInstance, newv, notify_, notify_, notifyByPspec, onNotify, ref, refSink, removeToggleRef, removeWeakPointer, replaceData, replaceQdata, runDispose, set, setData, setDataFull, setProperty, setProperty, setProperty, setQdata, setQdataFull, setv, stealData, stealQdata, takeRef, thawNotify, unref, watchClosure, weakRef, weakUnref, withProperties

Methods inherited from class org.gnome.gobject.TypeInstance

callParent, callParent, getPrivate, readGClass, writeGClass

Methods inherited from class io.github.jwharm.javagi.base.ProxyInstance

equals, handle, hashCode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Details

Resolver

public Resolver(MemorySegment address)

Create a Resolver proxy instance for the provided memory address.

Parameters:

address - the memory address of the native object

Method Details

getType

public static Type getType()

Get the GType of the Resolver class

Returns:

the GType

getMemoryLayout

public static MemoryLayout getMemoryLayout()

The memory layout of the native struct.

Returns:

the memory layout

asParent

protected Resolver asParent()

Returns this instance as if it were its parent type. This is mostly synonymous to the Java super keyword, but will set the native typeclass function pointers to the parent type. When overriding a native virtual method in Java, "chaining up" with super.methodName() doesn't work, because it invokes the overridden function pointer again. To chain up, call asParent().methodName(). This will call the native function pointer of this virtual method in the typeclass of the parent type.

Overrides:

asParent in class GObject

freeAddresses

public static void freeAddresses(List<MemorySegment> 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

freeTargets

public static void freeTargets(List<MemorySegment> 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

getDefault

public static Resolver getDefault()

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.

getTimeout

public int getTimeout()

Get the timeout applied to all resolver lookups. See GResolver:timeout.

Returns:

the resolver timeout, in milliseconds, or 0 for no timeout

lookupByAddress

public String lookupByAddress(InetAddress address,
 @Nullable
 @Nullable Cancellable cancellable)
                       throws GErrorException

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 IOErrorEnum.CANCELLED.

Parameters:

address - the address to reverse-resolve

cancellable - a GCancellable, or null

Returns:

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

Throws:

GErrorException - see GError

lookupByAddressAsync

public void lookupByAddressAsync(InetAddress address,
 @Nullable
 @Nullable Cancellable cancellable,
 @Nullable
 @Nullable AsyncReadyCallback callback)

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:

address - the address to reverse-resolve

cancellable - a GCancellable, or null

callback - callback to call after resolution completes

lookupByAddressFinish

public String lookupByAddressFinish(AsyncResult result)
                             throws GErrorException

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 IOErrorEnum.CANCELLED.

Parameters:

result - the result passed to your GAsyncReadyCallback

Returns:

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

Throws:

GErrorException - see GError

lookupByName

public List<InetAddress> lookupByName(String hostname,
 @Nullable
 @Nullable Cancellable cancellable)
                               throws GErrorException

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 IOErrorEnum.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:

hostname - the hostname to look up

cancellable - a GCancellable, 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.)

Throws:

GErrorException - see GError

lookupByNameAsync

public void lookupByNameAsync(String hostname,
 @Nullable
 @Nullable Cancellable cancellable,
 @Nullable
 @Nullable AsyncReadyCallback callback)

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:

hostname - the hostname to look up the address of

cancellable - a GCancellable, or null

callback - callback to call after resolution completes

lookupByNameFinish

public List<InetAddress> lookupByNameFinish(AsyncResult result)
                                     throws GErrorException

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 IOErrorEnum.CANCELLED.

Parameters:

result - the result passed to your GAsyncReadyCallback

Returns:

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

Throws:

GErrorException - see GError

lookupByNameWithFlags

public List<InetAddress> lookupByNameWithFlags(String hostname,
 Set<ResolverNameLookupFlags> flags,
 @Nullable
 @Nullable Cancellable cancellable)
                                        throws GErrorException

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 ResolverNameLookupFlags.IPV4_ONLY.

Parameters:

hostname - the hostname to look up

flags - extra GResolverNameLookupFlags for the lookup

cancellable - a GCancellable, 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.)

Throws:

GErrorException - see GError

lookupByNameWithFlags

public List<InetAddress> lookupByNameWithFlags(String hostname,
 ResolverNameLookupFlags flags,
 @Nullable
 @Nullable Cancellable cancellable)
                                        throws GErrorException

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 ResolverNameLookupFlags.IPV4_ONLY.

Parameters:

hostname - the hostname to look up

flags - extra GResolverNameLookupFlags for the lookup

cancellable - a GCancellable, 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.)

Throws:

GErrorException - see GError

lookupByNameWithFlagsAsync

public void lookupByNameWithFlagsAsync(String hostname,
 Set<ResolverNameLookupFlags> flags,
 @Nullable
 @Nullable Cancellable cancellable,
 @Nullable
 @Nullable AsyncReadyCallback callback)

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:

hostname - the hostname to look up the address of

flags - extra GResolverNameLookupFlags for the lookup

cancellable - a GCancellable, or null

callback - callback to call after resolution completes

lookupByNameWithFlagsAsync

public void lookupByNameWithFlagsAsync(String hostname,
 ResolverNameLookupFlags flags,
 @Nullable
 @Nullable Cancellable cancellable,
 @Nullable
 @Nullable AsyncReadyCallback callback)

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:

hostname - the hostname to look up the address of

flags - extra GResolverNameLookupFlags for the lookup

cancellable - a GCancellable, or null

callback - callback to call after resolution completes

lookupByNameWithFlagsFinish

public List<InetAddress> lookupByNameWithFlagsFinish(AsyncResult result)
                                              throws GErrorException

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 IOErrorEnum.CANCELLED.

Parameters:

result - the result passed to your GAsyncReadyCallback

Returns:

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

Throws:

GErrorException - see GError

lookupRecords

public List<Variant> lookupRecords(String rrname,
 ResolverRecordType recordType,
 @Nullable
 @Nullable Cancellable cancellable)
                            throws GErrorException

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

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 IOErrorEnum.CANCELLED.

Parameters:

rrname - the DNS name to look up the record for

recordType - the type of DNS record to look up

cancellable - a GCancellable, 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.)

Throws:

GErrorException - see GError

lookupRecordsAsync

public void lookupRecordsAsync(String rrname,
 ResolverRecordType recordType,
 @Nullable
 @Nullable Cancellable cancellable,
 @Nullable
 @Nullable AsyncReadyCallback callback)

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:

rrname - the DNS name to look up the record for

recordType - the type of DNS record to look up

cancellable - a GCancellable, or null

callback - callback to call after resolution completes

lookupRecordsFinish

public List<Variant> lookupRecordsFinish(AsyncResult result)
                                  throws GErrorException

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 IOErrorEnum.CANCELLED.

Parameters:

result - the result passed to your GAsyncReadyCallback

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

Throws:

GErrorException - see GError

lookupService

public List<SrvTarget> lookupService(String service,
 String protocol,
 String domain,
 @Nullable
 @Nullable Cancellable cancellable)
                              throws GErrorException

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 IOErrorEnum.CANCELLED.

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

Parameters:

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

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

Throws:

GErrorException - see GError

lookupServiceAsync

public void lookupServiceAsync(String service,
 String protocol,
 String domain,
 @Nullable
 @Nullable Cancellable cancellable,
 @Nullable
 @Nullable AsyncReadyCallback callback)

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:

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

callback - callback to call after resolution completes

lookupServiceFinish

public List<SrvTarget> lookupServiceFinish(AsyncResult result)
                                    throws GErrorException

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 IOErrorEnum.CANCELLED.

Parameters:

result - the result passed to your GAsyncReadyCallback

Returns:

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

Throws:

GErrorException - see GError

setDefault

public void setDefault()

Sets this Resolver to be the application's default resolver (reffing this 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.

setTimeout

public void setTimeout(int timeoutMs)

Set the timeout applied to all resolver lookups. See GResolver:timeout.

Parameters:

timeoutMs - timeout in milliseconds, or 0 for no timeouts

lookupService

protected List<MemorySegment> lookupService(String rrname,
 @Nullable
 @Nullable Cancellable cancellable)
                                     throws GErrorException

Throws:

GErrorException

lookupServiceAsync

protected void lookupServiceAsync(String rrname,
 @Nullable
 @Nullable Cancellable cancellable,
 @Nullable
 @Nullable AsyncReadyCallback callback)

reload

protected void reload()

onReload

public SignalConnection<Resolver.ReloadCallback> onReload(Resolver.ReloadCallback handler)

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

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• Resolver.ReloadCallback.run()

emitReload

public void emitReload()

Emits the "reload" signal. See onReload(org.gnome.gio.Resolver.ReloadCallback).

builder

public static Resolver.Builder<? extends Resolver.Builder> builder()

A Resolver.Builder object constructs a Resolver with the specified properties. Use the various set...() methods to set properties, and finish construction with Resolver.Builder.build().