gi-gio-2.0.19: Gio bindings

Copyright | Will Thompson Iñaki García Etxebarria and Jonas Platte
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria (garetxe@gmail.com)
Safe Haskell | None
Language | Haskell2010

GI.Gio.Objects.Resolver

Contents

- Exported types
- Methods
  - getDefault
  - lookupByAddress
  - lookupByAddressAsync
  - lookupByAddressFinish
  - lookupByName
  - lookupByNameAsync
  - lookupByNameFinish
  - lookupByNameWithFlags
  - lookupByNameWithFlagsAsync
  - lookupByNameWithFlagsFinish
  - lookupRecords
  - lookupRecordsAsync
  - lookupRecordsFinish
  - lookupService
  - lookupServiceAsync
  - lookupServiceFinish
  - setDefault
- Signals
  - reload

Description

`Resolver` 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 `Resolver` functionality that also implement `SocketConnectable`, making it easy to connect to a remote host/service.

Synopsis

- newtype Resolver = Resolver (ManagedPtr Resolver)
- class GObject o => IsResolver o
- toResolver :: (MonadIO m, IsResolver o) => o -> m Resolver
- noResolver :: Maybe Resolver
- resolverGetDefault :: (HasCallStack, MonadIO m) => m Resolver
- 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 ()
- type C_ResolverReloadCallback = Ptr () -> Ptr () -> IO ()
- type ResolverReloadCallback = IO ()
- afterResolverReload :: (IsResolver a, MonadIO m) => a -> ResolverReloadCallback -> m SignalHandlerId
- genClosure_ResolverReload :: ResolverReloadCallback -> IO Closure
- mk_ResolverReloadCallback :: C_ResolverReloadCallback -> IO (FunPtr C_ResolverReloadCallback)
- noResolverReloadCallback :: Maybe ResolverReloadCallback
- onResolverReload :: (IsResolver a, MonadIO m) => a -> ResolverReloadCallback -> m SignalHandlerId
- wrap_ResolverReloadCallback :: ResolverReloadCallback -> C_ResolverReloadCallback

# Exported types

newtype Resolver Source #

Memory-managed wrapper type.

Constructors

Resolver (ManagedPtr Resolver) |

Instances

GObject Resolver Source # |
Instance details Defined in GI.Gio.Objects.Resolver Methods gobjectType :: Resolver -> IO GType Source #
IsObject Resolver Source # |
Instance details Defined in GI.Gio.Objects.Resolver
IsResolver Resolver Source # |
Instance details Defined in GI.Gio.Objects.Resolver

class GObject o => IsResolver o Source #

Type class for types which can be safely cast to `Resolver`, for instance with `toResolver`.

Instances

(GObject a, (UnknownAncestorError Resolver a :: Constraint)) => IsResolver a Source # |
Instance details Defined in GI.Gio.Objects.Resolver
IsResolver Resolver Source # |
Instance details Defined in GI.Gio.Objects.Resolver

toResolver :: (MonadIO m, IsResolver o) => o -> m Resolver Source #

Cast to `Resolver`, for types for which this is known to be safe. For general casts, use `castTo`.

noResolver :: Maybe Resolver Source #

A convenience alias for `Nothing` :: `Maybe` `Resolver`.

# Methods

## getDefault

resolverGetDefault Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> m Resolver | Returns: the 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.

Since: 2.22

## lookupByAddress

resolverLookupByAddress Source #

Arguments

:: (HasCallStack, MonadIO m, IsResolver a, IsInetAddress b, IsCancellable c) |
=> a | `resolver`: a `Resolver`
-> b | `address`: the address to reverse-resolve
-> Maybe c | `cancellable`: a `Cancellable`, or `Nothing`
-> m Text | Returns: a hostname (either ASCII-only, or in ASCII-encoded form), or `Nothing` on error. (Can throw `GError`)

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 #

Arguments

:: (HasCallStack, MonadIO m, IsResolver a, IsInetAddress b, IsCancellable c) |
=> a | `resolver`: a `Resolver`
-> b | `address`: the address to reverse-resolve
-> Maybe c | `cancellable`: a `Cancellable`, or `Nothing`
-> Maybe AsyncReadyCallback | `callback`: callback to call after resolution completes
-> 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 #

Arguments

:: (HasCallStack, MonadIO m, IsResolver a, IsAsyncResult b) |
=> a | `resolver`: a `Resolver`
-> b | `result`: the result passed to your `AsyncReadyCallback`
-> m Text | Returns: a hostname (either ASCII-only, or in ASCII-encoded form), or `Nothing` on error. (Can throw `GError`)

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

resolverLookupByName Source #

Arguments

:: (HasCallStack, MonadIO m, IsResolver a, IsCancellable b) |
=> a | `resolver`: a `Resolver`
-> Text | `hostname`: the hostname to look up
-> Maybe b | `cancellable`: a `Cancellable`, or `Nothing`
-> m [InetAddress] | Returns: a non-empty `List` of `InetAddress`, or `Nothing` 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.) (Can throw `GError`)

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 #

Arguments

:: (HasCallStack, MonadIO m, IsResolver a, IsCancellable b) |
=> a | `resolver`: a `Resolver`
-> Text | `hostname`: the hostname to look up the address of
-> Maybe b | `cancellable`: a `Cancellable`, or `Nothing`
-> Maybe AsyncReadyCallback | `callback`: callback to call after resolution completes
-> 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 #

Arguments

:: (HasCallStack, MonadIO m, IsResolver a, IsAsyncResult b) |
=> a | `resolver`: a `Resolver`
-> b | `result`: the result passed to your `AsyncReadyCallback`
-> m [InetAddress] | Returns: a `List` of `InetAddress`, or `Nothing` on error. See `resolverLookupByName` for more details. (Can throw `GError`)

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 #

Arguments

:: (HasCallStack, MonadIO m, IsResolver a, IsCancellable b) |
=> a | `resolver`: a `Resolver`
-> Text | `hostname`: the hostname to look up
-> [ResolverNameLookupFlags] | `flags`: extra `ResolverNameLookupFlags` for the lookup
-> Maybe b | `cancellable`: a `Cancellable`, or `Nothing`
-> m [InetAddress] | Returns: a non-empty `List` of `InetAddress`, or `Nothing` 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.) (Can throw `GError`)

This differs from `resolverLookupByName` in that you can modify the lookup behavior with `flags`. For example this can be used to limit results with `G_RESOLVER_NAME_LOOKUP_FLAGS_IPV4_ONLY`.

Since: 2.60

## lookupByNameWithFlagsAsync

resolverLookupByNameWithFlagsAsync Source #

Arguments

:: (HasCallStack, MonadIO m, IsResolver a, IsCancellable b) |
=> a | `resolver`: a `Resolver`
-> Text | `hostname`: the hostname to look up the address of
-> [ResolverNameLookupFlags] | `flags`: extra `ResolverNameLookupFlags` for the lookup
-> Maybe b | `cancellable`: a `Cancellable`, or `Nothing`
-> Maybe AsyncReadyCallback | `callback`: callback to call after resolution completes
-> 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 #

Arguments

:: (HasCallStack, MonadIO m, IsResolver a, IsAsyncResult b) |
=> a | `resolver`: a `Resolver`
-> b | `result`: the result passed to your `AsyncReadyCallback`
-> m [InetAddress] | Returns: a `List` of `InetAddress`, or `Nothing` on error. See `resolverLookupByName` for more details. (Can throw `GError`)

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 #

Arguments

:: (HasCallStack, MonadIO m, IsResolver a, IsCancellable b) |
=> a | `resolver`: a `Resolver`
-> Text | `rrname`: the DNS name to lookup the record for
-> ResolverRecordType | `recordType`: the type of DNS record to lookup
-> Maybe b | `cancellable`: a `Cancellable`, or `Nothing`
-> m [GVariant] | Returns: a non-empty `List` of `GVariant`, or `Nothing` 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 `variantUnref` to do this.) (Can throw `GError`)

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 #

Arguments

:: (HasCallStack, MonadIO m, IsResolver a, IsCancellable b) |
=> a | `resolver`: a `Resolver`
-> Text | `rrname`: the DNS name to lookup the record for
-> ResolverRecordType | `recordType`: the type of DNS record to lookup
-> Maybe b | `cancellable`: a `Cancellable`, or `Nothing`
-> Maybe AsyncReadyCallback | `callback`: callback to call after resolution completes
-> 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 #

Arguments

:: (HasCallStack, MonadIO m, IsResolver a, IsAsyncResult b) |
=> a | `resolver`: a `Resolver`
-> b | `result`: the result passed to your `AsyncReadyCallback`
-> m [GVariant] | Returns: a non-empty `List` of `GVariant`, or `Nothing` 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 `variantUnref` to do this.) (Can throw `GError`)

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 #

Arguments

:: (HasCallStack, MonadIO m, IsResolver a, IsCancellable b) |
=> a | `resolver`: a `Resolver`
-> Text | `service`: the service type to look up (eg, "ldap")
-> Text | `protocol`: the networking protocol to use for `service` (eg, "tcp")
-> Text | `domain`: the DNS domain to look up the service in
-> Maybe b | `cancellable`: a `Cancellable`, or `Nothing`
-> m [SrvTarget] | Returns: a non-empty `List` of `SrvTarget`, or `Nothing` 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.) (Can throw `GError`)

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 #

Arguments

:: (HasCallStack, MonadIO m, IsResolver a, IsCancellable b) |
=> a | `resolver`: a `Resolver`
-> Text | `service`: the service type to look up (eg, "ldap")
-> Text | `protocol`: the networking protocol to use for `service` (eg, "tcp")
-> Text | `domain`: the DNS domain to look up the service in
-> Maybe b | `cancellable`: a `Cancellable`, or `Nothing`
-> Maybe AsyncReadyCallback | `callback`: callback to call after resolution completes
-> 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 #

Arguments

:: (HasCallStack, MonadIO m, IsResolver a, IsAsyncResult b) |
=> a | `resolver`: a `Resolver`
-> b | `result`: the result passed to your `AsyncReadyCallback`
-> m [SrvTarget] | Returns: a non-empty `List` of `SrvTarget`, or `Nothing` on error. See `resolverLookupService` for more details. (Can throw `GError`)

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

resolverSetDefault Source #

Arguments

:: (HasCallStack, MonadIO m, IsResolver a) |
=> a | `resolver`: the new default `Resolver`
-> 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

# Signals

## reload

type C_ResolverReloadCallback = Ptr () -> Ptr () -> IO () Source #

Type for the callback on the (unwrapped) C side.

type ResolverReloadCallback = IO () Source #

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

afterResolverReload :: (IsResolver a, MonadIO m) => 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

genClosure_ResolverReload :: ResolverReloadCallback -> IO Closure Source #

Wrap the callback into a `Closure`.

mk_ResolverReloadCallback :: C_ResolverReloadCallback -> IO (FunPtr C_ResolverReloadCallback) Source #

Generate a function pointer callable from C code, from a `C_ResolverReloadCallback`.

noResolverReloadCallback :: Maybe ResolverReloadCallback Source #

A convenience synonym for ``Nothing` :: `Maybe` `ResolverReloadCallback``.

onResolverReload :: (IsResolver a, MonadIO m) => 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

wrap_ResolverReloadCallback :: ResolverReloadCallback -> C_ResolverReloadCallback Source #

Wrap a `ResolverReloadCallback` into a `C_ResolverReloadCallback`.