InfNameResolver: libinfinity-0.7 Reference Manual

## InfNameResolver InfNameResolver — Asynchronous DNS name lookup with support for SRV records |

## Stability Level

Unstable, unless otherwise indicated

## Functions

InfNameResolver * | inf_name_resolver_new ()
const gchar * | inf_name_resolver_get_hostname ()
const gchar * | inf_name_resolver_get_service ()
const gchar * | inf_name_resolver_get_srv ()
gboolean | inf_name_resolver_start ()
gboolean | inf_name_resolver_lookup_backup ()
gboolean | inf_name_resolver_finished ()
guint | inf_name_resolver_get_n_addresses ()
const InfIpAddress * | inf_name_resolver_get_address ()
guint | inf_name_resolver_get_port ()

## 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

struct | InfNameResolver
struct | InfNameResolverClass

## 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