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.