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.