## soup-dns

soup-dns — Low-level DNS routines

## Synopsis

    void        soup_dns_init                   (void);
    char*       soup_dns_ntop                   (struct sockaddr *sa);
    typedef     SoupDNSLookup;
    SoupDNSLookup* soup_dns_lookup_name         (const char *name);
    SoupDNSLookup* soup_dns_lookup_address      (struct sockaddr *sockaddr);
    gboolean    soup_dns_lookup_resolve         (SoupDNSLookup *lookup);
    void        (*SoupDNSCallback)              (SoupDNSLookup *lookup,
                                                 gboolean success,
                                                 gpointer user_data);
    void        soup_dns_lookup_resolve_async   (SoupDNSLookup *lookup,
                                                 GMainContext *async_context,
                                                 SoupDNSCallback callback,
                                                 gpointer user_data);
    void        soup_dns_lookup_cancel          (SoupDNSLookup *lookup);
    char*       soup_dns_lookup_get_hostname    (SoupDNSLookup *lookup);
    struct sockaddr* soup_dns_lookup_get_address
                                                (SoupDNSLookup *lookup);
    void        soup_dns_lookup_free            (SoupDNSLookup *lookup);

## Description

## Details

### soup_dns_init ()

    void        soup_dns_init                   (void);

Initializes the libsoup DNS system. Must be called before any other soup_dns method is called. Normally this gets called automatically by SoupAddress's class_init function.

### soup_dns_ntop ()

    char*       soup_dns_ntop                   (struct sockaddr *sa);

Converts `sa`'s address into textual form (eg, "141.213.8.59"), like the standard library function `inet_ntop()`, except that the returned string must be freed.

`sa` : | pointer to a sockaddr
Returns : | the text form or `sa`, which must be freed.

### SoupDNSLookup

    typedef struct SoupDNSLookup SoupDNSLookup;

An opaque type that represents a DNS lookup operation.

### soup_dns_lookup_name ()

    SoupDNSLookup* soup_dns_lookup_name         (const char *name);

Creates a SoupDNSLookup for `name`. This should be passed to `soup_dns_lookup_resolve()` or `soup_dns_lookup_resolve_async()`.

`name` : | a hostname (eg, "www.gnome.org") or physical address (eg, "12.107.209.247").
Returns : | a SoupDNSLookup, which should eventually be freed with `soup_dns_lookup_free()`.

### soup_dns_lookup_address ()

    SoupDNSLookup* soup_dns_lookup_address      (struct sockaddr *sockaddr);

Creates a SoupDNSLookup for `sockaddr`. This should be passed to `soup_dns_lookup_resolve()` or `soup_dns_lookup_resolve_async()`.

`sockaddr` : | pointer to a sockaddr
Returns : | a SoupDNSLookup, which should eventually be freed with `soup_dns_lookup_free()`

### soup_dns_lookup_resolve ()

    gboolean    soup_dns_lookup_resolve         (SoupDNSLookup *lookup);

Synchronously resolves `lookup`. You can cancel a pending resolution using `soup_dns_lookup_cancel()`.

`lookup` : | a SoupDNSLookup
Returns : | success or failure.

### SoupDNSCallback ()

    void        (*SoupDNSCallback)              (SoupDNSLookup *lookup,
                                                 gboolean success,
                                                 gpointer user_data);

The callback function passed to `soup_dns_lookup_resolve_async()`.

`lookup` : | the completed lookup
`success` : | `TRUE` if `lookup` completed successfully, `FALSE` if it failed
`user_data` : | the data passed to `soup_dns_lookup_resolve_async()`

### soup_dns_lookup_resolve_async ()

    void        soup_dns_lookup_resolve_async   (SoupDNSLookup *lookup,
                                                 GMainContext *async_context,
                                                 SoupDNSCallback callback,
                                                 gpointer user_data);

Tries to asynchronously resolve `lookup`. Invokes `callback` when it has succeeded or failed. You can cancel a pending resolution using `soup_dns_lookup_cancel()`.

`lookup` : | a SoupDNSLookup
`async_context` : | GMainContext to call `callback` in
`callback` : | callback to call when `lookup` is resolved
`user_data` : | data to pass to `callback`;

### soup_dns_lookup_cancel ()

    void        soup_dns_lookup_cancel          (SoupDNSLookup *lookup);

Cancels `lookup`. If `lookup` was running synchronously in another thread, it will immediately return `FALSE`. If `lookup` was running asynchronously, its callback function will not be called.

`lookup` : | a SoupDNSLookup

### soup_dns_lookup_get_hostname ()

    char*       soup_dns_lookup_get_hostname    (SoupDNSLookup *lookup);

Gets the hostname of `lookup`.

`lookup` : | a SoupDNSLookup
Returns : | the hostname, which the caller owns and must free, or `NULL` if `lookup` has not been completely resolved.

### soup_dns_lookup_get_address ()

    struct sockaddr* soup_dns_lookup_get_address
                                                (SoupDNSLookup *lookup);

Gets the address of `lookup`.

`lookup` : | a SoupDNSLookup
Returns : | the address, which the caller owns and must free, or `NULL` if `lookup` has not been completely resolved.

### soup_dns_lookup_free ()

    void        soup_dns_lookup_free            (SoupDNSLookup *lookup);

Frees `lookup`. If `lookup` is still running, it will be canceled first.

`lookup` : | a SoupDNSLookup