## gskdnsresolver

gskdnsresolver — An interface that DNS resolvers provide.

## Synopsis

                        GskDnsResolverHints;
                        GskDnsResolverIface;
                        GskDnsResolver;
                        GskDnsResolverTask;
    void                (*GskDnsResolverLookupFunc)         (GskSocketAddress *address,
                                                             gpointer func_data);
    void                (*GskDnsResolverRevLookupFunc)      (const char *name,
                                                             gpointer func_data);
    void                (*GskDnsResolverResponseFunc)       (GSList *answers,
                                                             GSList *authority,
                                                             GSList *additional,
                                                             GSList *neg_questions,
                                                             gpointer func_data);
    void                (*GskDnsResolverFailFunc)           (GError *error,
                                                             gpointer func_data);
    GskDnsResolverTask * gsk_dns_resolver_resolve           (GskDnsResolver *resolver,
                                                             gboolean recursive,
                                                             GSList *dns_questions,
                                                             GskDnsResolverResponseFunc func,
                                                             GskDnsResolverFailFunc on_fail,
                                                             gpointer func_data,
                                                             GDestroyNotify destroy,
                                                             GskDnsResolverHints *hints);
    void                gsk_dns_resolver_cancel             (GskDnsResolver *resolver,
                                                             GskDnsResolverTask *task);
    GskDnsResolverTask * gsk_dns_resolver_lookup            (GskDnsResolver *resolver,
                                                             const char *name,
                                                             GskDnsResolverLookupFunc func,
                                                             GskDnsResolverFailFunc on_fail,
                                                             gpointer func_data,
                                                             GDestroyNotify destroy);
    GskDnsResolverTask * gsk_dns_resolver_rev_lookup        (GskDnsResolver *resolver,
                                                             const char *name,
                                                             GskDnsResolverRevLookupFunc func,
                                                             GskDnsResolverFailFunc on_fail,
                                                             gpointer func_data,
                                                             GDestroyNotify destroy);
    void                gsk_dns_resolver_add_name_resolver_iface
                                                            (GType type);

## Object Hierarchy

      GInterface
       +----GskDnsResolver

## Prerequisites

GskDnsResolver requires GObject.

## Known Implementations

GskDnsResolver is implemented by GskDnsClient.

## Description

This is an interface which classes that provide DNS lookups may implement. It provides an easy way to conform to the GskNameResolver interface.

## Details

### GskDnsResolverHints

    typedef struct {
      GskSocketAddress       *address;
    } GskDnsResolverHints;

### GskDnsResolverIface

    typedef struct {
      GTypeInterface base_iface;
      gpointer            (*resolve) (GskDnsResolver               *resolver,
    				  gboolean                      recursive,
    				  GSList                       *dns_questions,
    				  GskDnsResolverResponseFunc    func,
    				  GskDnsResolverFailFunc        on_fail,
    				  gpointer                      func_data,
    				  GDestroyNotify                destroy,
    				  GskDnsResolverHints          *optional_hints);
      void                (*cancel)  (GskDnsResolver               *resolver,
    				  gpointer                      task);
    } GskDnsResolverIface;

The interface for DNS resolvers.

GTypeInterface `base_iface`; |
`resolve` () | begin a name-resolution task. The pointer returned should identify the task to the resolver object, so that it can be cancelled. Alternatively, if the resolver can operate without blocking, it may return NULL, after having called the success or failure callback.
`cancel` () | a method to cancel a still running DNS task.

### GskDnsResolver

    typedef struct _GskDnsResolver GskDnsResolver;

Any object which implements this interface.

### GskDnsResolverTask

    typedef struct _GskDnsResolverTask GskDnsResolverTask;

An opaque structure which represents a DNS resolving task.

### GskDnsResolverLookupFunc ()

    void                (*GskDnsResolverLookupFunc)         (GskSocketAddress *address,
                                                             gpointer func_data);

Function to call when an address is found from a name.

`address` : | the address that was found.
`func_data` : | data passed to `gsk_dns_resolver_lookup()`.

### GskDnsResolverRevLookupFunc ()

    void                (*GskDnsResolverRevLookupFunc)      (const char *name,
                                                             gpointer func_data);

Function to call when an name is found from an address.

`name` : | the name that was found.
`func_data` : | data passed to `gsk_dns_resolver_rev_lookup()`.

### GskDnsResolverResponseFunc ()

    void                (*GskDnsResolverResponseFunc)       (GSList *answers,
                                                             GSList *authority,
                                                             GSList *additional,
                                                             GSList *neg_questions,
                                                             gpointer func_data);

Handle a list of DNS results. This has all the sections of a GskDnsMessage except the questions.

`answers` : | Direct answers to the questions posed to `gsk_dns_resolver_resolve()`. (A GSList of GskDnsResourceRecord's)
`authority` : | Information about the authority of the `answers`. (A GSList of GskDnsResourceRecord's)
`additional` : | Supporting data, for example, the numeric address of a nameserver. (To try to save the client from making more queries.) (A GSList of GskDnsResourceRecord's)
`neg_questions` : |
`func_data` : | Data passed to `gsk_dns_resolver_resolve()`.

### GskDnsResolverFailFunc ()

    void                (*GskDnsResolverFailFunc)           (GError *error,
                                                             gpointer func_data);

Called when a DNS resolution fails.

`error` : | the error which caused the DNS query to fail.
`func_data` : | Data passed to `gsk_dns_resolver_resolve()`, `gsk_dns_resolver_lookup()` or `gsk_dns_resolver_rev_lookup()`.

### gsk_dns_resolver_resolve ()

    GskDnsResolverTask * gsk_dns_resolver_resolve           (GskDnsResolver *resolver,
                                                             gboolean recursive,
                                                             GSList *dns_questions,
                                                             GskDnsResolverResponseFunc func,
                                                             GskDnsResolverFailFunc on_fail,
                                                             gpointer func_data,
                                                             GDestroyNotify destroy,
                                                             GskDnsResolverHints *hints);

Begin a DNS lookup task.

`resolver` : | the DNS resolver which should begin processing the request.
`recursive` : | whether to use recursive name resolution on the server.
`dns_questions` : | list of GskDnsQuestion's to resolve.
`func` : | function which will be called with answers to the given questions.
`on_fail` : | function to call if the name cannot be resolved.
`func_data` : | data to pass to `func` and `on_fail`.
`destroy` : | function to call with the task is over.
`hints` : | flags to pass to the name resolver.
Returns : | a running DNS lookup task.

### gsk_dns_resolver_cancel ()

    void                gsk_dns_resolver_cancel             (GskDnsResolver *resolver,
                                                             GskDnsResolverTask *task);

Cancel a running DNS lookup task.

`resolver` : | a resolver which is running a DNS lookup task.
`task` : | a DNS lookup task to cancel.

### gsk_dns_resolver_lookup ()

    GskDnsResolverTask * gsk_dns_resolver_lookup            (GskDnsResolver *resolver,
                                                             const char *name,
                                                             GskDnsResolverLookupFunc func,
                                                             GskDnsResolverFailFunc on_fail,
                                                             gpointer func_data,
                                                             GDestroyNotify destroy);

Begin a simple DNS lookup, using the underlying general resolver.

TODO. IPv6 support.

`resolver` : | DNS client to ask questions.
`name` : | name of host to look up.
`func` : | function to call on successful name lookup.
`on_fail` : | function to call on name lookup failure.
`func_data` : | data to pass to `func` and `on_fail`.
`destroy` : | function to call when the task is destroyed.
Returns : | a running DNS lookup task.

### gsk_dns_resolver_rev_lookup ()

    GskDnsResolverTask * gsk_dns_resolver_rev_lookup        (GskDnsResolver *resolver,
                                                             const char *name,
                                                             GskDnsResolverRevLookupFunc func,
                                                             GskDnsResolverFailFunc on_fail,
                                                             gpointer func_data,
                                                             GDestroyNotify destroy);

`resolver` : |
`name` : |
`func` : |
`on_fail` : |
`func_data` : |
`destroy` : |
Returns : |

### gsk_dns_resolver_add_name_resolver_iface ()

    void                gsk_dns_resolver_add_name_resolver_iface
                                                            (GType type);

`type` : |

## See Also

GskDnsLocalResolver and GskDnsClient.