Resolver

class Resolver(**properties: Any)

Superclasses: Object

Subclasses: ThreadedResolver

The object that handles DNS resolution. Use get_default to get the default resolver.

GResolver provides cancellable synchronous and asynchronous DNS resolution, for hostnames (lookup_by_address, lookup_by_name and their async variants) and SRV (service) records (lookup_service).

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

Methods

class Resolver
get_default() → Resolver

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

Added in version 2.22.

get_timeout() → int

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

Added in version 2.78.

lookup_by_address(address: InetAddress, cancellable: Cancellable | None = None) → str

Synchronously reverse-resolves address to determine its associated hostname.

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

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

Added in version 2.22.

Parameters:

  • address – the address to reverse-resolve

  • cancellable – a Cancellable, or None

lookup_by_address_async(address: InetAddress, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

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

Added in version 2.22.

Parameters:

  • address – the address to reverse-resolve

  • cancellable – a Cancellable, or None

  • callback – callback to call after resolution completes

  • user_data – data for callback

lookup_by_address_finish(result: AsyncResult) → str

Retrieves the result of a previous call to lookup_by_address_async().

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

Added in version 2.22.

Parameters:

result – the result passed to your AsyncReadyCallback

lookup_by_name(hostname: str, cancellable: Cancellable | None = None) → list[InetAddress]

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

On success, lookup_by_name() will return a non-empty List of InetAddress, 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. add_address().

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

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

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

Added in version 2.22.

Parameters:

  • hostname – the hostname to look up

  • cancellable – a Cancellable, or None

lookup_by_name_async(hostname: str, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

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

Added in version 2.22.

Parameters:

  • hostname – the hostname to look up the address of

  • cancellable – a Cancellable, or None

  • callback – callback to call after resolution completes

  • user_data – data for callback

lookup_by_name_finish(result: AsyncResult) → list[InetAddress]

Retrieves the result of a call to lookup_by_name_async().

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

Added in version 2.22.

Parameters:

result – the result passed to your AsyncReadyCallback

lookup_by_name_with_flags(hostname: str, flags: ResolverNameLookupFlags, cancellable: Cancellable | None = None) → list[InetAddress]

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

Added in version 2.60.

Parameters:
lookup_by_name_with_flags_async(hostname: str, flags: ResolverNameLookupFlags, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

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

Added in version 2.60.

Parameters:

  • hostname – the hostname to look up the address of

  • flags – extra ResolverNameLookupFlags for the lookup

  • cancellable – a Cancellable, or None

  • callback – callback to call after resolution completes

  • user_data – data for callback

lookup_by_name_with_flags_finish(result: AsyncResult) → list[InetAddress]

Retrieves the result of a call to lookup_by_name_with_flags_async().

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

Added in version 2.60.

Parameters:

result – the result passed to your AsyncReadyCallback

lookup_records(rrname: str, record_type: ResolverRecordType, cancellable: Cancellable | None = None) → list[Variant]

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

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

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

Added in version 2.34.

Parameters:

  • rrname – the DNS name to look up the record for

  • record_type – the type of DNS record to look up

  • cancellable – a Cancellable, or None

lookup_records_async(rrname: str, record_type: ResolverRecordType, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

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

Added in version 2.34.

Parameters:

  • rrname – the DNS name to look up the record for

  • record_type – the type of DNS record to look up

  • cancellable – a Cancellable, or None

  • callback – callback to call after resolution completes

  • user_data – data for callback

lookup_records_finish(result: AsyncResult) → list[Variant]

Retrieves the result of a previous call to lookup_records_async(). Returns a non-empty list of records as Variant tuples. See ResolverRecordType for information on what the records contain.

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

Added in version 2.34.

Parameters:

result – the result passed to your AsyncReadyCallback

lookup_service(service: str, protocol: str, domain: str, cancellable: Cancellable | None = None) → list[SrvTarget]

Synchronously performs a DNS SRV lookup for the given service and protocol in the given domain and returns an array of SrvTarget. 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, lookup_service() will return a non-empty List of SrvTarget, 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-None) will be set to a value from GResolverError and None will be returned.

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

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

Added in version 2.22.

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 Cancellable, or None

lookup_service_async(service: str, protocol: str, domain: str, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

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

Added in version 2.22.

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 Cancellable, or None

  • callback – callback to call after resolution completes

  • user_data – data for callback

lookup_service_finish(result: AsyncResult) → list[SrvTarget]

Retrieves the result of a previous call to lookup_service_async().

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

Added in version 2.22.

Parameters:

result – the result passed to your AsyncReadyCallback

set_default() → None

Sets resolver to be the application’s default resolver (reffing resolver, and unreffing the previous default resolver, if any). Future calls to 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 Resolver 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.

Added in version 2.22.

set_timeout(timeout_ms: int) → None

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

Added in version 2.78.

Parameters:

timeout_ms – timeout in milliseconds, or 0 for no timeouts

Properties

class Resolver
props.timeout: int

The timeout applied to all resolver lookups, in milliseconds.

This may be changed through the lifetime of the Resolver. The new value will apply to any lookups started after the change, but not to any already-ongoing lookups.

If this is 0, no timeout is applied to lookups.

No timeout was applied to lookups before this property was added in GLib 2.78.

Added in version 2.78.

Signals

class Resolver.signals
reload() → None

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

Virtual Methods

class Resolver
do_lookup_by_address(address: InetAddress, cancellable: Cancellable | None = None) → str

Synchronously reverse-resolves address to determine its associated hostname.

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

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

Added in version 2.22.

Parameters:

  • address – the address to reverse-resolve

  • cancellable – a Cancellable, or None

do_lookup_by_address_async(address: InetAddress, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

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

Added in version 2.22.

Parameters:

  • address – the address to reverse-resolve

  • cancellable – a Cancellable, or None

  • callback – callback to call after resolution completes

  • user_data – data for callback

do_lookup_by_address_finish(result: AsyncResult) → str

Retrieves the result of a previous call to lookup_by_address_async().

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

Added in version 2.22.

Parameters:

result – the result passed to your AsyncReadyCallback

do_lookup_by_name(hostname: str, cancellable: Cancellable | None = None) → list[InetAddress]

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

On success, lookup_by_name() will return a non-empty List of InetAddress, 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. add_address().

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

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

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

Added in version 2.22.

Parameters:

  • hostname – the hostname to look up

  • cancellable – a Cancellable, or None

do_lookup_by_name_async(hostname: str, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

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

Added in version 2.22.

Parameters:

  • hostname – the hostname to look up the address of

  • cancellable – a Cancellable, or None

  • callback – callback to call after resolution completes

  • user_data – data for callback

do_lookup_by_name_finish(result: AsyncResult) → list[InetAddress]

Retrieves the result of a call to lookup_by_name_async().

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

Added in version 2.22.

Parameters:

result – the result passed to your AsyncReadyCallback

do_lookup_by_name_with_flags(hostname: str, flags: ResolverNameLookupFlags, cancellable: Cancellable | None = None) → list[InetAddress]

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

Added in version 2.60.

Parameters:
do_lookup_by_name_with_flags_async(hostname: str, flags: ResolverNameLookupFlags, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

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

Added in version 2.60.

Parameters:

  • hostname – the hostname to look up the address of

  • flags – extra ResolverNameLookupFlags for the lookup

  • cancellable – a Cancellable, or None

  • callback – callback to call after resolution completes

  • user_data – data for callback

do_lookup_by_name_with_flags_finish(result: AsyncResult) → list[InetAddress]

Retrieves the result of a call to lookup_by_name_with_flags_async().

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

Added in version 2.60.

Parameters:

result – the result passed to your AsyncReadyCallback

do_lookup_records(rrname: str, record_type: ResolverRecordType, cancellable: Cancellable | None = None) → list[Variant]

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

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

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

Added in version 2.34.

Parameters:

  • rrname – the DNS name to look up the record for

  • record_type – the type of DNS record to look up

  • cancellable – a Cancellable, or None

do_lookup_records_async(rrname: str, record_type: ResolverRecordType, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

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

Added in version 2.34.

Parameters:

  • rrname – the DNS name to look up the record for

  • record_type – the type of DNS record to look up

  • cancellable – a Cancellable, or None

  • callback – callback to call after resolution completes

  • user_data – data for callback

do_lookup_records_finish(result: AsyncResult) → list[Variant]

Retrieves the result of a previous call to lookup_records_async(). Returns a non-empty list of records as Variant tuples. See ResolverRecordType for information on what the records contain.

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

Added in version 2.34.

Parameters:

result – the result passed to your AsyncReadyCallback

do_lookup_service_async(rrname: str, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None
Parameters:

  • rrname

  • cancellable

  • callback

  • user_data

do_lookup_service_finish(result: AsyncResult) → list[SrvTarget]

Retrieves the result of a previous call to lookup_service_async().

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

Added in version 2.22.

Parameters:

result – the result passed to your AsyncReadyCallback

do_reload() → None

Fields

class Resolver
parent_instance
priv