Socket Address Lookup by Name

Name

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

Synopsis



struct      GskNameResolver;
struct      GskNameResolverIface;
struct      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);
GskNameResolverTask* gsk_name_resolve       (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

struct GskNameResolver

struct GskNameResolver;

Opaque object representing an instance which implements the NameResolver interface.


struct GskNameResolverIface

struct GskNameResolverIface {

  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);
};

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

GObjectClass object_class

base class.

gpointer (*start_resolve) (GskNameResolver *resolver, GskNameResolverFamily family, const char *name, GskNameResolverSuccessFunc success, GskNameResolverFailureFunc failure, gpointer func_data, GDestroyNotify destroy)

method to start a name lookup.

gboolean (*cancel_resolve) (GskNameResolver *resolver, gpointer handle)

method to cancel a name lookup.


struct GskNameResolverTask

struct 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_resolve ()

GskNameResolverTask* gsk_name_resolve       (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.