InfNameResolver

InfNameResolver — Asynchronous DNS name lookup with support for SRV records

Stability Level

Unstable, unless otherwise indicated

Synopsis

#include <libinfinity/common/inf-name-resolver.h>

                    InfNameResolver;
struct              InfNameResolverClass;
InfNameResolver *   inf_name_resolver_new               (InfIo *io,
                                                         const gchar *hostname,
                                                         const gchar *service,
                                                         const gchar *srv);
const gchar *       inf_name_resolver_get_hostname      (InfNameResolver *resolver);
const gchar *       inf_name_resolver_get_service       (InfNameResolver *resolver);
const gchar *       inf_name_resolver_get_srv           (InfNameResolver *resolver);
gboolean            inf_name_resolver_start             (InfNameResolver *resolver,
                                                         GError **error);
gboolean            inf_name_resolver_lookup_backup     (InfNameResolver *resolver,
                                                         GError **error);
gboolean            inf_name_resolver_finished          (InfNameResolver *resolver);
guint               inf_name_resolver_get_n_addresses   (InfNameResolver *resolver);
const InfIpAddress * inf_name_resolver_get_address      (InfNameResolver *resolver,
                                                         guint index);
guint               inf_name_resolver_get_port          (InfNameResolver *resolver,
                                                         guint index);

Object Hierarchy

  GObject
   +----InfNameResolver

Properties

  "hostname"                 gchar*                : Read / Write / Construct
  "io"                       InfIo*                : Read / Write / Construct
  "service"                  gchar*                : Read / Write / Construct
  "srv"                      gchar*                : Read / Write / Construct

Signals

  "resolved"                                       : Run Last

Description

InfNameResolver provides a portable interface to look up DNS entries. When a resorver object has been created, the name lookup can be started with inf_name_resolver_start(), and once it finishes, the "resolved" signal is emitted. The inf_name_resolver_get_address() and inf_name_resolver_get_port() functions can then be used to obtain the result.

There can at most be one hostname lookup at a time. If you need more than one concurrent hostname lookup, use multiple InfNameResolver objects.

Details

InfNameResolver

typedef struct _InfNameResolver InfNameResolver;

InfNameResolver is an opaque data type. You should only access it via the public API functions.


struct InfNameResolverClass

struct InfNameResolverClass {
  /* Signals */
  void (*resolved)(InfNameResolver* connection,
                   const GError* error);
};

This structure contains the default signal handlers of InfNameResolver.

resolved ()

Default signal handler for the "resolved" signal.

inf_name_resolver_new ()

InfNameResolver *   inf_name_resolver_new               (InfIo *io,
                                                         const gchar *hostname,
                                                         const gchar *service,
                                                         const gchar *srv);

Creates a new InfNameResolver. Use inf_name_resolver_start() to start resolving the hostname.

If service is not NULL, it should be a decimal port number or a well-known service name that is translated into a port number, such as "http&quot. If srv is not NULL, the function will first attempt a SRV lookup, and fall back to a regular A/AAAA lookup in case no SRV record exists. Otherwise the SRV result is taken. If service is provided, it always overwrites the port number obtained from the hostname lookup.

The recommended procedure is to call this function with service equal to the port number entered by the user, or NULL if the user did not provide an explicit port number. If the resulting port number obtained with inf_name_resolver_get_port() is then different from 0, then use that port number, otherwise the default port number for the service.

io :

A InfIo object used to schedule events in the main thread.

hostname :

The hostname to look up.

service :

The name of the service to look up, or NULL.

srv :

The SRV record to look up, or NULL.

Returns :

A new InfNameResolver. Free with g_object_unref().

inf_name_resolver_get_hostname ()

const gchar *       inf_name_resolver_get_hostname      (InfNameResolver *resolver);

Returns the currently configured hostname that resolver will look up.

resolver :

A InfNameResolver.

Returns :

The currently configured hostname.

inf_name_resolver_get_service ()

const gchar *       inf_name_resolver_get_service       (InfNameResolver *resolver);

Returns the currently configured service that resolver will look up.

resolver :

A InfNameResolver.

Returns :

The currently configured service.

inf_name_resolver_get_srv ()

const gchar *       inf_name_resolver_get_srv           (InfNameResolver *resolver);

Returns the currently configured SRV record that resolver will look up.

resolver :

A InfNameResolver.

Returns :

The currently configured SRV record.

inf_name_resolver_start ()

gboolean            inf_name_resolver_start             (InfNameResolver *resolver,
                                                         GError **error);

Starts the name resolution for the hostname configured with resolver.

When the hostname lookup has finished, the "resolved" signal is emitted. The function can only be called again once this signal has been emitted. When this function is called, the previously looked up result can no longer be obtained with the inf_name_resolver_get_address() and inf_name_resolver_get_port() functions.

resolver :

A InfNameResolver.

error :

Location to store error information, if any.

Returns :

TRUE on success or FALSE if a (synchronous) error occurred.

inf_name_resolver_lookup_backup ()

gboolean            inf_name_resolver_lookup_backup     (InfNameResolver *resolver,
                                                         GError **error);

Tries to look up backup addresses for the configured hostname. This should be used if connecting to none of the initially reported addresses works. The function returns FALSE if there are no backup addresses available, or TRUE otherwise. If it returns TRUE, it the "resolved" signal will be emitted again, and when it is, more addresses might be available from the resolver object.

resolver :

A InfNameResolver.

error :

Location to store error information, if any, or NULL.

Returns :

TRUE if looking up backup addresses is attempted, or FALSE otherwise.

inf_name_resolver_finished ()

gboolean            inf_name_resolver_finished          (InfNameResolver *resolver);

Returns whether the resolver is currently looking up a hostname, or whether it is ready to start a new lookup with inf_name_resolver_start().

resolver :

A InfNameResolver.

Returns :

Whether a call to inf_name_resolver_start() can be made.

inf_name_resolver_get_n_addresses ()

guint               inf_name_resolver_get_n_addresses   (InfNameResolver *resolver);

Returns the number of resolved addresses that belongs to the hostname that was looked up.

resolver :

A InfNameResolver.

Returns :

The number of addresses available.

inf_name_resolver_get_address ()

const InfIpAddress * inf_name_resolver_get_address      (InfNameResolver *resolver,
                                                         guint index);

Returns the indexth address looked up in the last hostname resolution operation.

resolver :

A InfNameResolver.

index :

The index for which to return the address, in case multiple IP addresses correspond to the same hostname.

Returns :

The looked up InfIpAddress.

inf_name_resolver_get_port ()

guint               inf_name_resolver_get_port          (InfNameResolver *resolver,
                                                         guint index);

Returns the indexth port looked up in the last hostname resolution operation. This can be 0 if the service parameter in inf_name_resolver_start() has been set to NULL and no SRV record has been found.

resolver :

A InfNameResolver.

index :

The index for which to return the port, in case multiple IP addresses correspond to the same hostname.

Returns :

The looked up InfIpAddress.

Property Details

The "hostname" property

  "hostname"                 gchar*                : Read / Write / Construct

The hostname to be looked up.

Default value: NULL


The "io" property

  "io"                       InfIo*                : Read / Write / Construct

I/O handler.


The "service" property

  "service"                  gchar*                : Read / Write / Construct

The expected service at the remote endpoint.

Default value: NULL


The "srv" property

  "srv"                      gchar*                : Read / Write / Construct

The SRV record to look up for the given hostname, e.g. _jabber._tcp.

Default value: NULL

Signal Details

The "resolved" signal

void                user_function                      (InfNameResolver *resolver,
                                                        gpointer         error,
                                                        gpointer         user_data)      : Run Last

This signal is emitted when the hostname has been resolved. The function inf_name_resolver_get_address() and inf_name_resolver_get_port() can be called to obtain the resolved addresses.

resolver :

The InfNameResolver that has resolved a hostname.

error :

A description of the error that occurred, or NULL.

user_data :

user data set when the signal handler was connected.