## Socket Address Lookup by Name

Socket Address Lookup by Name — A way to lookup addresses from names. (Like a generic DNS.)

## Synopsis

                        GskNameResolver;
                        GskNameResolverIface;
                        GskNameResolverTask;
    void                (*GskNameResolverSuccessFunc)       (GskSocketAddress *address,
                                                             gpointer func_data);
    void                (*GskNameResolverFailureFunc)       (GError *error,
                                                             gpointer func_data);
    enum                GskNameResolverFamily;
    GskNameResolverFamily  gsk_name_resolver_family_get_by_name
                                                            (const char *name);
    const char *        gsk_name_resolver_family_get_name   (GskNameResolverFamily family);
    void                gsk_name_resolver_lookup            (GskNameResolverFamily family,
                                                             const char *name,
                                                             GskNameResolverSuccessFunc success,
                                                             GskNameResolverFailureFunc failure,
                                                             gpointer func_data,
                                                             GDestroyNotify destroy);
    GskNameResolverTask * gsk_name_resolver_task_new        (GskNameResolverFamily family,
                                                             const char *name,
                                                             GskNameResolverSuccessFunc success,
                                                             GskNameResolverFailureFunc failure,
                                                             gpointer func_data,
                                                             GDestroyNotify destroy);
    void                gsk_name_resolver_task_cancel       (GskNameResolverTask *task);
    void                gsk_name_resolver_task_ref          (GskNameResolverTask *task);
    void                gsk_name_resolver_task_unref        (GskNameResolverTask *task);
    GskNameResolverFamily  gsk_name_resolver_family_unique  (const char *name);
    void                gsk_name_resolver_add_family_name   (GskNameResolverFamily family,
                                                             const char *name);
    GskNameResolver *   (*GskNameResolverFamilyHandler)     (gpointer data);
    void                gsk_name_resolver_add_family_resolver
                                                            (GskNameResolverFamily family,
                                                             GskNameResolver *resolver);
    void                gsk_name_resolver_add_family_handler
                                                            (GskNameResolverFamily family,
                                                             GskNameResolverFamilyHandler handler,
                                                             gpointer data,
                                                             GDestroyNotify destroy);

## Object Hierarchy

      GInterface
       +----GskNameResolver

## Known Implementations

GskNameResolver is implemented by GskDnsClient.

## Description

This code provides (1) a method to lookup an address given the type of address and its name, and (2) a way of registering new types of address families and namespaces.

## Details

### GskNameResolver

    typedef struct _GskNameResolver GskNameResolver;

Opaque object representing an instance which implements the NameResolver interface.

### GskNameResolverIface

    typedef struct {
      GObjectClass object_class;
      gpointer (*start_resolve)  (GskNameResolver           *resolver,
    			      GskNameResolverFamily      family,
                                  const char                *name,
                                  GskNameResolverSuccessFunc success,
                                  GskNameResolverFailureFunc failure,
                                  gpointer                   func_data,
                                  GDestroyNotify             destroy);
      gboolean (*cancel_resolve) (GskNameResolver           *resolver,
                                  gpointer                   handle);
    } GskNameResolverIface;

An interface that can be implemented by a class which provides name-lookups.

GObjectClass `object_class`; | base class.
`start_resolve` () | method to start a name lookup.
`cancel_resolve` () | method to cancel a name lookup.

### GskNameResolverTask

    typedef struct _GskNameResolverTask GskNameResolverTask;

An opaque type representing a name lookup (which may be running, or it may be succeeded, failed or been cancelled).

### GskNameResolverSuccessFunc ()

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

Function to call when an address has been successfully found for the name.

`address` : | the address corresponding to the name.
`func_data` : | data passed to `gsk_name_resolve()`.

### GskNameResolverFailureFunc ()

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

Function to call when a name lookup fails.

`error` : | what when wrong with the name lookup.
`func_data` : | data passed to `gsk_name_resolve()`.

### enum GskNameResolverFamily

    typedef enum
    {
      GSK_NAME_RESOLVER_FAMILY_NONE,
      GSK_NAME_RESOLVER_FAMILY_IPV4
    } GskNameResolverFamily;

Namespaces. This enum is extendable.

`GSK_NAME_RESOLVER_FAMILY_NONE` | An invalid namespace used to report errors. Must be 0.
`GSK_NAME_RESOLVER_FAMILY_IPV4` | The IPv4 namespace, used for practically all of the internet (in 2003)

### gsk_name_resolver_family_get_by_name ()

    GskNameResolverFamily  gsk_name_resolver_family_get_by_name
                                                            (const char *name);

Get the GskNameResolverFamily of a resolver namespace by ascii string.

`name` : | the name of the namespace, as a c string.
Returns : | the family, or 0 on error.

### gsk_name_resolver_family_get_name ()

    const char *        gsk_name_resolver_family_get_name   (GskNameResolverFamily family);

Get the resolver-namespace as a printable c string.

`family` : | the namespace family to enquire about.
Returns : | the namespace's name as a c string.

### gsk_name_resolver_lookup ()

    void                gsk_name_resolver_lookup            (GskNameResolverFamily family,
                                                             const char *name,
                                                             GskNameResolverSuccessFunc success,
                                                             GskNameResolverFailureFunc failure,
                                                             gpointer func_data,
                                                             GDestroyNotify destroy);

Begin a non-cancellable name-lookup.

`family` : | name family to perform the lookup in.
`name` : | name to lookup.
`success` : | callback for successful name-lookup: this will be called with the GskSocketAddress that was found.
`failure` : | callback for failure. This is invoked with the GError object.
`func_data` : | data to call to the callbacks.
`destroy` : | function to be called after the callbacks are done.

### gsk_name_resolver_task_new ()

    GskNameResolverTask * gsk_name_resolver_task_new        (GskNameResolverFamily family,
                                                             const char *name,
                                                             GskNameResolverSuccessFunc success,
                                                             GskNameResolverFailureFunc failure,
                                                             gpointer func_data,
                                                             GDestroyNotify destroy);

Begin a name lookup. This may succeed before the function returns. It you wish to cancel a name resolution task, call `gsk_name_resolver_task_cancel()`. In any event, you must `gsk_name_resolver_task_unref()` once you are done with the handle. (This will NOT cause a running task to be cancelled.)

`family` : | name space to look the address up in.
`name` : | name within `family`'s namespace.
`success` : | function to be called with an appropriate GskSocketAddress once the name is successfully resolved.
`failure` : | function to call if the name lookup failed.
`func_data` : | data to pass to `success` or `failure`.
`destroy` : | optionally called after `success` or `failure`, to deallocate func_data usually.
Returns : | a reference to a GskNameResolverTask which can be used to cancel or query the task.

### gsk_name_resolver_task_cancel ()

    void                gsk_name_resolver_task_cancel       (GskNameResolverTask *task);

Stops the name lookup from continuing. Neither the success or failure functions will be invoked subsequently, but the destroy method will be.

`task` : | a running name resolution task to cancel.

### gsk_name_resolver_task_ref ()

    void                gsk_name_resolver_task_ref          (GskNameResolverTask *task);

Increase the reference count on a name-resolver task. This is mostly useless outside the resolver code.

`task` : | task whose reference count should be increased.

### gsk_name_resolver_task_unref ()

    void                gsk_name_resolver_task_unref        (GskNameResolverTask *task);

Decrease the reference count on a name-resolver task, freeing it if needed. This does NOT cancel the task. You MUST unref the task returned by `gsk_name_resolve()`.

`task` : | task whose reference count should be decreased.

### gsk_name_resolver_family_unique ()

    GskNameResolverFamily  gsk_name_resolver_family_unique  (const char *name);

Allocate a unique GskNameResolverFamily given a new name, or return the old GskNameResolverFamily if one already exists.

`name` : | name of a new namespace to register.
Returns : | the family corresponding to `name`.

### gsk_name_resolver_add_family_name ()

    void                gsk_name_resolver_add_family_name   (GskNameResolverFamily family,
                                                             const char *name);

Add a new nickname for the name resolver family.

The family is the name of the namespace.

`family` : | registered family to give a new name for.
`name` : | alias name for `family`.

### GskNameResolverFamilyHandler ()

    GskNameResolver *   (*GskNameResolverFamilyHandler)     (gpointer data);

Create a reference to a name-resolver on demand.

`data` : |
Returns : |

### gsk_name_resolver_add_family_resolver ()

    void                gsk_name_resolver_add_family_resolver
                                                            (GskNameResolverFamily family,
                                                             GskNameResolver *resolver);

Add a name-resolver that will handle a request of a given family.

`family` : | registered family to provide an alias for.
`resolver` : | name resolver to use for addresses in `family`.

### gsk_name_resolver_add_family_handler ()

    void                gsk_name_resolver_add_family_handler
                                                            (GskNameResolverFamily family,
                                                             GskNameResolverFamilyHandler handler,
                                                             gpointer data,
                                                             GDestroyNotify destroy);

Add a name-resolver that will handle a request of a given family.

`family` : | registered family to provide a resolver implementation for.
`handler` : | ...
`data` : | data to pass to `handler`
`destroy` : | function to call when the handler has deregistered.