Copyright | Will Thompson and Iñaki García Etxebarria |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria |
Safe Haskell | None |
Language | Haskell2010 |
- Exported types
- Methods
- getDefault
- getTimeout
- lookupByAddress
- lookupByAddressAsync
- lookupByAddressFinish
- lookupByName
- lookupByNameAsync
- lookupByNameFinish
- lookupByNameWithFlags
- lookupByNameWithFlagsAsync
- lookupByNameWithFlagsFinish
- lookupRecords
- lookupRecordsAsync
- lookupRecordsFinish
- lookupService
- lookupServiceAsync
- lookupServiceFinish
- setDefault
- setTimeout
- Properties
- Signals
The object that handles DNS resolution. Use [funcgio
.Resolver.get_default]
to get the default resolver.
GResolver
provides cancellable synchronous and asynchronous DNS
resolution, for hostnames (resolverLookupByAddress
,
resolverLookupByName
and their async variants) and SRV
(service) records (resolverLookupService
).
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 [funcgio
.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.
Synopsis
- newtype Resolver = Resolver (ManagedPtr Resolver)
- class (GObject o, IsDescendantOf Resolver o) => IsResolver o
- toResolver :: (MonadIO m, IsResolver o) => o -> m Resolver
- resolverGetDefault :: (HasCallStack, MonadIO m) => m Resolver
- resolverGetTimeout :: (HasCallStack, MonadIO m, IsResolver a) => a -> m Word32
- resolverLookupByAddress :: (HasCallStack, MonadIO m, IsResolver a, IsInetAddress b, IsCancellable c) => a -> b -> Maybe c -> m Text
- resolverLookupByAddressAsync :: (HasCallStack, MonadIO m, IsResolver a, IsInetAddress b, IsCancellable c) => a -> b -> Maybe c -> Maybe AsyncReadyCallback -> m ()
- resolverLookupByAddressFinish :: (HasCallStack, MonadIO m, IsResolver a, IsAsyncResult b) => a -> b -> m Text
- resolverLookupByName :: (HasCallStack, MonadIO m, IsResolver a, IsCancellable b) => a -> Text -> Maybe b -> m [InetAddress]
- resolverLookupByNameAsync :: (HasCallStack, MonadIO m, IsResolver a, IsCancellable b) => a -> Text -> Maybe b -> Maybe AsyncReadyCallback -> m ()
- resolverLookupByNameFinish :: (HasCallStack, MonadIO m, IsResolver a, IsAsyncResult b) => a -> b -> m [InetAddress]
- resolverLookupByNameWithFlags :: (HasCallStack, MonadIO m, IsResolver a, IsCancellable b) => a -> Text -> [ResolverNameLookupFlags] -> Maybe b -> m [InetAddress]
- resolverLookupByNameWithFlagsAsync :: (HasCallStack, MonadIO m, IsResolver a, IsCancellable b) => a -> Text -> [ResolverNameLookupFlags] -> Maybe b -> Maybe AsyncReadyCallback -> m ()
- resolverLookupByNameWithFlagsFinish :: (HasCallStack, MonadIO m, IsResolver a, IsAsyncResult b) => a -> b -> m [InetAddress]
- resolverLookupRecords :: (HasCallStack, MonadIO m, IsResolver a, IsCancellable b) => a -> Text -> ResolverRecordType -> Maybe b -> m [GVariant]
- resolverLookupRecordsAsync :: (HasCallStack, MonadIO m, IsResolver a, IsCancellable b) => a -> Text -> ResolverRecordType -> Maybe b -> Maybe AsyncReadyCallback -> m ()
- resolverLookupRecordsFinish :: (HasCallStack, MonadIO m, IsResolver a, IsAsyncResult b) => a -> b -> m [GVariant]
- resolverLookupService :: (HasCallStack, MonadIO m, IsResolver a, IsCancellable b) => a -> Text -> Text -> Text -> Maybe b -> m [SrvTarget]
- resolverLookupServiceAsync :: (HasCallStack, MonadIO m, IsResolver a, IsCancellable b) => a -> Text -> Text -> Text -> Maybe b -> Maybe AsyncReadyCallback -> m ()
- resolverLookupServiceFinish :: (HasCallStack, MonadIO m, IsResolver a, IsAsyncResult b) => a -> b -> m [SrvTarget]
- resolverSetDefault :: (HasCallStack, MonadIO m, IsResolver a) => a -> m ()
- resolverSetTimeout :: (HasCallStack, MonadIO m, IsResolver a) => a -> Word32 -> m ()
- constructResolverTimeout :: (IsResolver o, MonadIO m) => Word32 -> m (GValueConstruct o)
- getResolverTimeout :: (MonadIO m, IsResolver o) => o -> m Word32
- setResolverTimeout :: (MonadIO m, IsResolver o) => o -> Word32 -> m ()
- type ResolverReloadCallback = IO ()
- afterResolverReload :: (IsResolver a, MonadIO m) => a -> ((?self :: a) => ResolverReloadCallback) -> m SignalHandlerId
- onResolverReload :: (IsResolver a, MonadIO m) => a -> ((?self :: a) => ResolverReloadCallback) -> m SignalHandlerId
Exported types
Memory-managed wrapper type.
Instances
Eq Resolver Source # | |
GObject Resolver Source # | |
Defined in GI.Gio.Objects.Resolver | |
ManagedPtrNewtype Resolver Source # | |
Defined in GI.Gio.Objects.Resolver toManagedPtr :: Resolver -> ManagedPtr Resolver # | |
TypedObject Resolver Source # | |
Defined in GI.Gio.Objects.Resolver | |
HasParentTypes Resolver Source # | |
Defined in GI.Gio.Objects.Resolver | |
IsGValue (Maybe Resolver) Source # | Convert |
Defined in GI.Gio.Objects.Resolver | |
type ParentTypes Resolver Source # | |
Defined in GI.Gio.Objects.Resolver type ParentTypes Resolver = '[Object] |
class (GObject o, IsDescendantOf Resolver o) => IsResolver o Source #
Type class for types which can be safely cast to Resolver
, for instance with toResolver
.
Instances
(GObject o, IsDescendantOf Resolver o) => IsResolver o Source # | |
Defined in GI.Gio.Objects.Resolver |
toResolver :: (MonadIO m, IsResolver o) => o -> m Resolver Source #
Methods
Click to display all available methods, including inherited ones
Methods
bindProperty, bindPropertyFull, forceFloating, freezeNotify, getv, isFloating, lookupByAddress, lookupByAddressAsync, lookupByAddressFinish, lookupByName, lookupByNameAsync, lookupByNameFinish, lookupByNameWithFlags, lookupByNameWithFlagsAsync, lookupByNameWithFlagsFinish, lookupRecords, lookupRecordsAsync, lookupRecordsFinish, lookupService, lookupServiceAsync, lookupServiceFinish, notify, notifyByPspec, ref, refSink, runDispose, stealData, stealQdata, thawNotify, unref, watchClosure.
Getters
getData, getProperty, getQdata, getTimeout.
Setters
getDefault
:: (HasCallStack, MonadIO m) | |
=> m Resolver | Returns: the default |
getTimeout
:: (HasCallStack, MonadIO m, IsResolver a) | |
=> a |
|
-> m Word32 | Returns: the resolver timeout, in milliseconds, or |
Get the timeout applied to all resolver lookups. See Resolver:timeout.
Since: 2.78
lookupByAddress
resolverLookupByAddress Source #
:: (HasCallStack, MonadIO m, IsResolver a, IsInetAddress b, IsCancellable c) | |
=> a |
|
-> b |
|
-> Maybe c |
|
-> m Text | Returns: a hostname (either ASCII-only, or in ASCII-encoded
form), or |
Synchronously reverse-resolves address
to determine its
associated hostname.
If the DNS resolution fails, error
(if non-Nothing
) will be set to
a value from ResolverError
.
If cancellable
is non-Nothing
, it can be used to cancel the
operation, in which case error
(if non-Nothing
) will be set to
IOErrorEnumCancelled
.
Since: 2.22
lookupByAddressAsync
resolverLookupByAddressAsync Source #
:: (HasCallStack, MonadIO m, IsResolver a, IsInetAddress b, IsCancellable c) | |
=> a |
|
-> b |
|
-> Maybe c |
|
-> Maybe AsyncReadyCallback |
|
-> m () |
Begins asynchronously reverse-resolving address
to determine its
associated hostname, and eventually calls callback
, which must
call resolverLookupByAddressFinish
to get the final result.
Since: 2.22
lookupByAddressFinish
resolverLookupByAddressFinish Source #
:: (HasCallStack, MonadIO m, IsResolver a, IsAsyncResult b) | |
=> a |
|
-> b |
|
-> m Text | Returns: a hostname (either ASCII-only, or in ASCII-encoded
form), or |
Retrieves the result of a previous call to
resolverLookupByAddressAsync
.
If the DNS resolution failed, error
(if non-Nothing
) will be set to
a value from ResolverError
. If the operation was cancelled,
error
will be set to IOErrorEnumCancelled
.
Since: 2.22
lookupByName
:: (HasCallStack, MonadIO m, IsResolver a, IsCancellable b) | |
=> a |
|
-> Text |
|
-> Maybe b |
|
-> m [InetAddress] | Returns: a non-empty |
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 inetAddressNewFromString
).
On success, resolverLookupByName
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. socketListenerAddAddress
.
If the DNS resolution fails, error
(if non-Nothing
) will be set to a
value from ResolverError
and Nothing
will be returned.
If cancellable
is non-Nothing
, it can be used to cancel the
operation, in which case error
(if non-Nothing
) will be set to
IOErrorEnumCancelled
.
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.
Since: 2.22
lookupByNameAsync
resolverLookupByNameAsync Source #
:: (HasCallStack, MonadIO m, IsResolver a, IsCancellable b) | |
=> a |
|
-> Text |
|
-> Maybe b |
|
-> Maybe AsyncReadyCallback |
|
-> m () |
Begins asynchronously resolving hostname
to determine its
associated IP address(es), and eventually calls callback
, which
must call resolverLookupByNameFinish
to get the result.
See resolverLookupByName
for more details.
Since: 2.22
lookupByNameFinish
resolverLookupByNameFinish Source #
:: (HasCallStack, MonadIO m, IsResolver a, IsAsyncResult b) | |
=> a |
|
-> b |
|
-> m [InetAddress] | Returns: a |
Retrieves the result of a call to
resolverLookupByNameAsync
.
If the DNS resolution failed, error
(if non-Nothing
) will be set to
a value from ResolverError
. If the operation was cancelled,
error
will be set to IOErrorEnumCancelled
.
Since: 2.22
lookupByNameWithFlags
resolverLookupByNameWithFlags Source #
:: (HasCallStack, MonadIO m, IsResolver a, IsCancellable b) | |
=> a |
|
-> Text |
|
-> [ResolverNameLookupFlags] |
|
-> Maybe b |
|
-> m [InetAddress] | Returns: a non-empty |
This differs from resolverLookupByName
in that you can modify
the lookup behavior with flags
. For example this can be used to limit
results with ResolverNameLookupFlagsIpv4Only
.
Since: 2.60
lookupByNameWithFlagsAsync
resolverLookupByNameWithFlagsAsync Source #
:: (HasCallStack, MonadIO m, IsResolver a, IsCancellable b) | |
=> a |
|
-> Text |
|
-> [ResolverNameLookupFlags] |
|
-> Maybe b |
|
-> Maybe AsyncReadyCallback |
|
-> m () |
Begins asynchronously resolving hostname
to determine its
associated IP address(es), and eventually calls callback
, which
must call resolverLookupByNameWithFlagsFinish
to get the result.
See resolverLookupByName
for more details.
Since: 2.60
lookupByNameWithFlagsFinish
resolverLookupByNameWithFlagsFinish Source #
:: (HasCallStack, MonadIO m, IsResolver a, IsAsyncResult b) | |
=> a |
|
-> b |
|
-> m [InetAddress] | Returns: a |
Retrieves the result of a call to
resolverLookupByNameWithFlagsAsync
.
If the DNS resolution failed, error
(if non-Nothing
) will be set to
a value from ResolverError
. If the operation was cancelled,
error
will be set to IOErrorEnumCancelled
.
Since: 2.60
lookupRecords
resolverLookupRecords Source #
:: (HasCallStack, MonadIO m, IsResolver a, IsCancellable b) | |
=> a |
|
-> Text |
|
-> ResolverRecordType |
|
-> Maybe b |
|
-> m [GVariant] | Returns: a non-empty |
Synchronously performs a DNS record lookup for the given rrname
and returns
a list of records as GVariant
tuples. See ResolverRecordType
for
information on what the records contain for each recordType
.
If the DNS resolution fails, error
(if non-Nothing
) will be set to
a value from ResolverError
and Nothing
will be returned.
If cancellable
is non-Nothing
, it can be used to cancel the
operation, in which case error
(if non-Nothing
) will be set to
IOErrorEnumCancelled
.
Since: 2.34
lookupRecordsAsync
resolverLookupRecordsAsync Source #
:: (HasCallStack, MonadIO m, IsResolver a, IsCancellable b) | |
=> a |
|
-> Text |
|
-> ResolverRecordType |
|
-> Maybe b |
|
-> Maybe AsyncReadyCallback |
|
-> m () |
Begins asynchronously performing a DNS lookup for the given
rrname
, and eventually calls callback
, which must call
resolverLookupRecordsFinish
to get the final result. See
resolverLookupRecords
for more details.
Since: 2.34
lookupRecordsFinish
resolverLookupRecordsFinish Source #
:: (HasCallStack, MonadIO m, IsResolver a, IsAsyncResult b) | |
=> a |
|
-> b |
|
-> m [GVariant] | Returns: a non-empty |
Retrieves the result of a previous call to
resolverLookupRecordsAsync
. Returns a non-empty list of records as
GVariant
tuples. See ResolverRecordType
for information on what the
records contain.
If the DNS resolution failed, error
(if non-Nothing
) will be set to
a value from ResolverError
. If the operation was cancelled,
error
will be set to IOErrorEnumCancelled
.
Since: 2.34
lookupService
resolverLookupService Source #
:: (HasCallStack, MonadIO m, IsResolver a, IsCancellable b) | |
=> a |
|
-> Text |
|
-> Text |
|
-> Text |
|
-> Maybe b |
|
-> m [SrvTarget] | Returns: a non-empty |
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, resolverLookupService
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-Nothing
) will be set to
a value from ResolverError
and Nothing
will be returned.
If cancellable
is non-Nothing
, it can be used to cancel the
operation, in which case error
(if non-Nothing
) will be set to
IOErrorEnumCancelled
.
If you are planning to connect to the service, it is usually easier
to create a NetworkService
and use its SocketConnectable
interface.
Since: 2.22
lookupServiceAsync
resolverLookupServiceAsync Source #
:: (HasCallStack, MonadIO m, IsResolver a, IsCancellable b) | |
=> a |
|
-> Text |
|
-> Text |
|
-> Text |
|
-> Maybe b |
|
-> Maybe AsyncReadyCallback |
|
-> m () |
Begins asynchronously performing a DNS SRV lookup for the given
service
and protocol
in the given domain
, and eventually calls
callback
, which must call resolverLookupServiceFinish
to
get the final result. See resolverLookupService
for more
details.
Since: 2.22
lookupServiceFinish
resolverLookupServiceFinish Source #
:: (HasCallStack, MonadIO m, IsResolver a, IsAsyncResult b) | |
=> a |
|
-> b |
|
-> m [SrvTarget] | Returns: a non-empty |
Retrieves the result of a previous call to
resolverLookupServiceAsync
.
If the DNS resolution failed, error
(if non-Nothing
) will be set to
a value from ResolverError
. If the operation was cancelled,
error
will be set to IOErrorEnumCancelled
.
Since: 2.22
setDefault
:: (HasCallStack, MonadIO m, IsResolver a) | |
=> a |
|
-> m () |
Sets resolver
to be the application's default resolver (reffing
resolver
, and unreffing the previous default resolver, if any).
Future calls to resolverGetDefault
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.
Since: 2.22
setTimeout
:: (HasCallStack, MonadIO m, IsResolver a) | |
=> a |
|
-> Word32 |
|
-> m () |
Set the timeout applied to all resolver lookups. See Resolver:timeout.
Since: 2.78
Properties
timeout
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.
Since: 2.78
constructResolverTimeout :: (IsResolver o, MonadIO m) => Word32 -> m (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “timeout
” property. This is rarely needed directly, but it is used by new
.
getResolverTimeout :: (MonadIO m, IsResolver o) => o -> m Word32 Source #
Get the value of the “timeout
” property.
When overloading is enabled, this is equivalent to
get
resolver #timeout
setResolverTimeout :: (MonadIO m, IsResolver o) => o -> Word32 -> m () Source #
Set the value of the “timeout
” property.
When overloading is enabled, this is equivalent to
set
resolver [ #timeout:=
value ]
Signals
reload
type ResolverReloadCallback = IO () Source #
Emitted when the resolver notices that the system resolver configuration has changed.
afterResolverReload :: (IsResolver a, MonadIO m) => a -> ((?self :: a) => ResolverReloadCallback) -> m SignalHandlerId Source #
Connect a signal handler for the reload signal, to be run after the default handler. When overloading is enabled, this is equivalent to
after
resolver #reload callback
By default the object invoking the signal is not passed to the callback.
If you need to access it, you can use the implit ?self
parameter.
Note that this requires activating the ImplicitParams
GHC extension.
onResolverReload :: (IsResolver a, MonadIO m) => a -> ((?self :: a) => ResolverReloadCallback) -> m SignalHandlerId Source #
Connect a signal handler for the reload signal, to be run before the default handler. When overloading is enabled, this is equivalent to
on
resolver #reload callback