Gio.Resolver¶

class — extends GObject.Object

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

GResolver provides cancellable synchronous and asynchronous DNS resolution, for hostnames (Resolver.lookup_by_address, Resolver.lookup_by_name and their async variants) and SRV (service) records (Resolver.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 Resolver.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¶

get_timeout¶

def get_timeout(self) -> int

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

lookup_by_address¶

def lookup_by_address(self, address: InetAddress, cancellable: Cancellable | 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 ResolverError.

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

Parameters:

address — the address to reverse-resolve
cancellable — a Cancellable, or None

lookup_by_address_async¶

def lookup_by_address_async(self, address: InetAddress, cancellable: Cancellable | None = ..., callback: Callable[[Resolver | None, AsyncResult], None] | None = ...) -> None

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

Parameters:

address — the address to reverse-resolve
cancellable — a Cancellable, or None
callback — callback to call after resolution completes

lookup_by_address_finish¶

def lookup_by_address_finish(self, result: AsyncResult) -> str

Retrieves the result of a previous call to Resolver.lookup_by_address_async.

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

Parameters:

result — the result passed to your GAsyncReadyCallback

lookup_by_name¶

def lookup_by_name(self, hostname: str, cancellable: Cancellable | 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 InetAddress.new_from_string).

On success, Resolver.lookup_by_name will return a non-empty GLib.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. SocketListener.add_address.

If the DNS resolution fails, error (if non-None) will be set to a value from ResolverError 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 IOErrorEnum.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.

Parameters:

hostname — the hostname to look up
cancellable — a Cancellable, or None

lookup_by_name_async¶

def lookup_by_name_async(self, hostname: str, cancellable: Cancellable | None = ..., callback: Callable[[Resolver | None, AsyncResult], None] | None = ...) -> None

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

Parameters:

hostname — the hostname to look up the address of
cancellable — a Cancellable, or None
callback — callback to call after resolution completes

lookup_by_name_finish¶

def lookup_by_name_finish(self, result: AsyncResult) -> list[InetAddress]

Retrieves the result of a call to Resolver.lookup_by_name_async.

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

Parameters:

result — the result passed to your GAsyncReadyCallback

lookup_by_name_with_flags¶

def lookup_by_name_with_flags(self, hostname: str, flags: ResolverNameLookupFlags | int, cancellable: Cancellable | None = ...) -> list[InetAddress]

This differs from 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 ResolverNameLookupFlags for the lookup
cancellable — a Cancellable, or None

lookup_by_name_with_flags_async¶

def lookup_by_name_with_flags_async(self, hostname: str, flags: ResolverNameLookupFlags | int, cancellable: Cancellable | None = ..., callback: Callable[[Resolver | None, AsyncResult], None] | None = ...) -> None

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

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

lookup_by_name_with_flags_finish¶

def lookup_by_name_with_flags_finish(self, result: AsyncResult) -> list[InetAddress]

Retrieves the result of a call to Resolver.lookup_by_name_with_flags_async.

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

Parameters:

result — the result passed to your GAsyncReadyCallback

lookup_records¶

def lookup_records(self, rrname: str, record_type: ResolverRecordType | int, cancellable: Cancellable | None = ...) -> list[GLib.Variant]

Synchronously performs a DNS record lookup for the given rrname and returns a list of records as GLib.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 ResolverError 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 IOErrorEnum.CANCELLED.

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¶

def lookup_records_async(self, rrname: str, record_type: ResolverRecordType | int, cancellable: Cancellable | None = ..., callback: Callable[[Resolver | None, AsyncResult], None] | None = ...) -> None

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

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

lookup_records_finish¶

def lookup_records_finish(self, result: AsyncResult) -> list[GLib.Variant]

Retrieves the result of a previous call to Resolver.lookup_records_async. Returns a non-empty list of records as GLib.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 ResolverError. If the operation was cancelled, error will be set to IOErrorEnum.CANCELLED.

Parameters:

result — the result passed to your GAsyncReadyCallback

lookup_service¶

def lookup_service(self, service: str, protocol: str, domain: str, cancellable: Cancellable | 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, Resolver.lookup_service will return a non-empty GLib.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 ResolverError 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 IOErrorEnum.CANCELLED.

If you are planning to connect to the service, it is usually easier to create a NetworkService and use its SocketConnectable 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 Cancellable, or None

lookup_service_async¶

def lookup_service_async(self, service: str, protocol: str, domain: str, cancellable: Cancellable | None = ..., callback: Callable[[Resolver | None, AsyncResult], None] | None = ...) -> 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 Resolver.lookup_service_finish to get the final result. See 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 Cancellable, or None
callback — callback to call after resolution completes

lookup_service_finish¶

def lookup_service_finish(self, result: AsyncResult) -> list[SrvTarget]

Retrieves the result of a previous call to Resolver.lookup_service_async.

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

Parameters:

result — the result passed to your GAsyncReadyCallback

set_default¶

def set_default(self) -> None

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

set_timeout¶

def set_timeout(self, timeout_ms: int) -> None

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

Parameters:

timeout_ms — timeout in milliseconds, or 0 for no timeouts

Static functions¶

get_default¶

@staticmethod
def 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.

Virtual methods¶

do_lookup_by_address¶

def do_lookup_by_address(self, address: InetAddress, cancellable: Cancellable | 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 ResolverError.

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

Parameters:

address — the address to reverse-resolve
cancellable — a Cancellable, or None

do_lookup_by_address_async¶

def do_lookup_by_address_async(self, address: InetAddress, cancellable: Cancellable | None = ..., callback: Callable[[Resolver | None, AsyncResult], None] | None = ...) -> None

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

Parameters:

address — the address to reverse-resolve
cancellable — a Cancellable, or None
callback — callback to call after resolution completes

do_lookup_by_address_finish¶

def do_lookup_by_address_finish(self, result: AsyncResult) -> str

Retrieves the result of a previous call to Resolver.lookup_by_address_async.

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

Parameters:

result — the result passed to your GAsyncReadyCallback

do_lookup_by_name¶

def do_lookup_by_name(self, hostname: str, cancellable: Cancellable | 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 InetAddress.new_from_string).

On success, Resolver.lookup_by_name will return a non-empty GLib.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. SocketListener.add_address.

If the DNS resolution fails, error (if non-None) will be set to a value from ResolverError 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 IOErrorEnum.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.

Parameters:

hostname — the hostname to look up
cancellable — a Cancellable, or None

do_lookup_by_name_async¶

def do_lookup_by_name_async(self, hostname: str, cancellable: Cancellable | None = ..., callback: Callable[[Resolver | None, AsyncResult], None] | None = ...) -> None

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

Parameters:

hostname — the hostname to look up the address of
cancellable — a Cancellable, or None
callback — callback to call after resolution completes

do_lookup_by_name_finish¶

def do_lookup_by_name_finish(self, result: AsyncResult) -> list[InetAddress]

Retrieves the result of a call to Resolver.lookup_by_name_async.

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

Parameters:

result — the result passed to your GAsyncReadyCallback

do_lookup_by_name_with_flags¶

def do_lookup_by_name_with_flags(self, hostname: str, flags: ResolverNameLookupFlags | int, cancellable: Cancellable | None = ...) -> list[InetAddress]

This differs from 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 ResolverNameLookupFlags for the lookup
cancellable — a Cancellable, or None

do_lookup_by_name_with_flags_async¶

def do_lookup_by_name_with_flags_async(self, hostname: str, flags: ResolverNameLookupFlags | int, cancellable: Cancellable | None = ..., callback: Callable[[Resolver | None, AsyncResult], None] | None = ...) -> None

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

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

do_lookup_by_name_with_flags_finish¶

def do_lookup_by_name_with_flags_finish(self, result: AsyncResult) -> list[InetAddress]

Retrieves the result of a call to Resolver.lookup_by_name_with_flags_async.

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

Parameters:

result — the result passed to your GAsyncReadyCallback

do_lookup_records¶

def do_lookup_records(self, rrname: str, record_type: ResolverRecordType | int, cancellable: Cancellable | None = ...) -> list[GLib.Variant]

Synchronously performs a DNS record lookup for the given rrname and returns a list of records as GLib.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 ResolverError 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 IOErrorEnum.CANCELLED.

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¶

def do_lookup_records_async(self, rrname: str, record_type: ResolverRecordType | int, cancellable: Cancellable | None = ..., callback: Callable[[Resolver | None, AsyncResult], None] | None = ...) -> None

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

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

do_lookup_records_finish¶

def do_lookup_records_finish(self, result: AsyncResult) -> list[GLib.Variant]

Retrieves the result of a previous call to Resolver.lookup_records_async. Returns a non-empty list of records as GLib.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 ResolverError. If the operation was cancelled, error will be set to IOErrorEnum.CANCELLED.

Parameters:

result — the result passed to your GAsyncReadyCallback

do_lookup_service_async¶

def do_lookup_service_async(self, rrname: str, cancellable: Cancellable | None = ..., callback: Callable[[Resolver | None, AsyncResult], None] | None = ...) -> None

do_lookup_service_finish¶

def do_lookup_service_finish(self, result: AsyncResult) -> list[SrvTarget]

Retrieves the result of a previous call to Resolver.lookup_service_async.

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

Parameters:

result — the result passed to your GAsyncReadyCallback

do_reload¶

def do_reload(self) -> None

Properties¶

timeout¶

timeout: int  # read/write

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.

Signals¶

reload¶

def on_reload(self) -> None: ...

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