InfNameResolver

InfNameResolver — Asynchronous DNS name lookup with support for SRV records

Stability Level

Unstable, unless otherwise indicated

Functions

Properties

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

Signals

void resolved Run Last

Types and Values

Object Hierarchy

    GObject
    ╰── InfNameResolver

Includes

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

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.

Functions

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.

[constructor]

Parameters

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.

[allow-none]

srv

The SRV record to look up, or NULL.

[allow-none]

Returns

A new InfNameResolver. Free with g_object_unref().

[transfer full]


inf_name_resolver_get_hostname ()

const gchar *
inf_name_resolver_get_hostname (InfNameResolver *resolver);

Returns the currently configured hostname that resolver will look up.

Parameters

resolver

A InfNameResolver.

 

Returns

The currently configured hostname.

[allow-none]


inf_name_resolver_get_service ()

const gchar *
inf_name_resolver_get_service (InfNameResolver *resolver);

Returns the currently configured service that resolver will look up.

Parameters

resolver

A InfNameResolver.

 

Returns

The currently configured service.

[allow-none]


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.

Parameters

resolver

A InfNameResolver.

 

Returns

The currently configured SRV record.

[allow-none]


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.

Parameters

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.

Parameters

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().

Parameters

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.

Parameters

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 index th address looked up in the last hostname resolution operation.

Parameters

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.

[transfer none]


inf_name_resolver_get_port ()

guint
inf_name_resolver_get_port (InfNameResolver *resolver,
                            guint index);

Returns the index th 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.

Parameters

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.

Types and Values

struct InfNameResolver

struct 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.

Members

resolved ()

Default signal handler for the “resolved” signal.

 

Property Details

The “hostname” property

  “hostname”                 gchar *

The hostname to be looked up.

Owner: InfNameResolver

Flags: Read / Write / Construct

Default value: NULL


The “io” property

  “io”                       InfIo *

I/O handler.

Owner: InfNameResolver

Flags: Read / Write / Construct


The “service” property

  “service”                  gchar *

The expected service at the remote endpoint.

Owner: InfNameResolver

Flags: Read / Write / Construct

Default value: NULL


The “srv” property

  “srv”                      gchar *

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

Owner: InfNameResolver

Flags: Read / Write / Construct

Default value: NULL

Signal Details

The “resolved” signal

void
user_function (InfNameResolver *resolver,
               GError          *error,
               gpointer         user_data)

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.

Parameters

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.

 

Flags: Run Last