DNS Lookups

DNS Lookups — Performing DNS queries.

Synopsis




struct      GTcpDNSEntry;
void        (*GTcpDNSCallbackFunc)          (const GTcpDNSEntry *entry,
                                             gpointer user_data);
typedef     GTcpDNSHandle;
#define     GTCP_DNS_INVALID_HANDLE
GTcpDNSHandle gtcp_dns_get                  (const gchar *address,
                                             GTcpDNSCallbackFunc callback,
                                             gpointer user_data);
void        gtcp_dns_cancel                 (GTcpDNSHandle handle);
void        gtcp_dns_entry_free             (GTcpDNSEntry *entry);
GTcpDNSEntry* gtcp_dns_entry_copy           (const GTcpDNSEntry *src);

Description

These methods provide a means to asynchronously perform DNS lookups on hostnames or reverse DNS lookups on addresses. This typically does not need to be done, as GTcpConnection and GTcpServer perform these lookups automatically, as directed or needed.

Details

struct GTcpDNSEntry

struct GTcpDNSEntry {

	GTcpLookupStatus status;

	gchar *hostname;
	GSList *aliases;
	GSList *ip_addresses;
};

The GTcpDNSEntry struct is an enhanced version of the standard hostent struct.

GTcpLookupStatus statusThe status code of the lookup (see GTcpLookupStatus and gtcp_error_get_lookup_status_message()).
gchar *hostnameThe cannonical hostname (may be NULL if there is no DNS record for this hostname or address).
GSList *aliasesThe list of hostname aliases for this DNS record (if any).
GSList *ip_addressesThe list of IP addresses for this DNS record (if any).

GTcpDNSCallbackFunc ()

void        (*GTcpDNSCallbackFunc)          (const GTcpDNSEntry *entry,
                                             gpointer user_data);

This function prototype is used for callbacks from a gtcp_dns_get() asynchronous lookup. The entry should be freed when it is no longer needed.

entry :The GTcpDNSEntry struct for this DNS record.
user_data :The user data passed to gtcp_dns_get().

GTcpDNSHandle

typedef glong GTcpDNSHandle;

A GTcpDNSHandle is used to cancel a callback for a particular lookup attempt.


GTCP_DNS_INVALID_HANDLE

#define GTCP_DNS_INVALID_HANDLE	-1

If an internal or programming error is encountered in gtcp_dns_get(), this value will be returned.


gtcp_dns_get ()

GTcpDNSHandle gtcp_dns_get                  (const gchar *address,
                                             GTcpDNSCallbackFunc callback,
                                             gpointer user_data);

This function performs an asynchronous DNS lookup (or reverse lookup) on the hostname or IP address in address. Note that the callback may be called before this function returns if the DNS record for address is in the cache.

address : the local address to get the GTcpDNSEntry for.
callback : the callback to be called when the lookup has completed.
user_data : the user data to pass to the callback.
Returns : a GTcpDNSHandle used to cancel a callback.

Since 1.0


gtcp_dns_cancel ()

void        gtcp_dns_cancel                 (GTcpDNSHandle handle);

This function prevents an asynchronous DNS lookup (or reverse lookup) from calling it's callback unless it has already been called. NOTE: This function will not actually stop a DNS lookup, only prevent the callback associated with handle from being called. (The lookup will still finish and the results will still be cached.)

handle : a GTcpDNSHandle for a running lookup.

Since 1.0


gtcp_dns_entry_free ()

void        gtcp_dns_entry_free             (GTcpDNSEntry *entry);

This function frees a GTcpDNSEntry returned in the callback from a call to gtcp_dns_get().

entry : the GTcpDNSEntry to free.

Since 1.0


gtcp_dns_entry_copy ()

GTcpDNSEntry* gtcp_dns_entry_copy           (const GTcpDNSEntry *src);

Copies an existing a GTcpDNSEntry. The returned data should be freed with gtcp_dns_entry_free() when no longer needed.

src : the entry to copy.
Returns : a copy of src.

Since 1.0