dns.h File Reference

Asynchronous DNS resolver library. More...

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Go to the source code of this file.

Data Structures
struct	dns_address_t
	Structure representing a resolved network address. More...
struct	dns_result_t
	Structure containing DNS resolution results. More...
struct	dns_config_t
	Configuration structure for DNS resolver. More...

Typedefs
typedef struct dns_resolver	dns_resolver_t
	Opaque handle for DNS resolver instance.
typedef struct dns_request	dns_request_t
	Opaque handle for individual DNS request.
typedef void(*	dns_callback_t) (dns_result_t *result, void *user_data)
	Callback function type for asynchronous DNS resolution.

Functions
dns_resolver_t *	dns_resolver_create (const dns_config_t *config)
	Create a new DNS resolver instance.
void	dns_resolver_destroy (dns_resolver_t *resolver)
	Destroy a DNS resolver instance.
dns_request_t *	dns_resolve_async (dns_resolver_t *resolver, const char *hostname, const char *service, dns_callback_t callback, void *user_data)
	Start asynchronous DNS resolution.
bool	dns_request_cancel (dns_request_t *request)
	Cancel a pending DNS request.
void	dns_resolver_process (dns_resolver_t *resolver)
	Process pending DNS operations.
void	dns_result_free (dns_result_t *result)
	Free DNS result structure.
const char *	dns_error_string (int error_code)
	Get human-readable error message.
dns_config_t	dns_config_default (void)
	Get default configuration.

Detailed Description

Asynchronous DNS resolver library.

This library provides a high-performance asynchronous DNS resolver with support for both IPv4 and IPv6 addresses. It allows for concurrent DNS queries with configurable timeouts and preferences.

Typedef Documentation

dns_callback_t

typedef void(* dns_callback_t) (dns_result_t *result, void *user_data)

Callback function type for asynchronous DNS resolution.

This function is called when a DNS resolution completes (either successfully or with an error). The result structure contains the resolution results.

Parameters

result	Pointer to the DNS resolution result
user_data	User-provided data passed to the callback

Note

The result structure must be freed using dns_result_free()

This callback may be called from a different thread

dns_request_t

typedef struct dns_request dns_request_t

Opaque handle for individual DNS request.

This structure represents a single DNS resolution request. It can be used to cancel pending requests.

dns_resolver_t

typedef struct dns_resolver dns_resolver_t

Opaque handle for DNS resolver instance.

This structure contains the internal state of the DNS resolver. Users should not access its members directly.

Function Documentation

dns_config_default()

dns_config_t dns_config_default

(

void

)

Get default configuration.

Returns a configuration structure initialized with default values. This can be used as a starting point for custom configurations.

Returns

Default configuration structure

See also

dns_resolver_create()

dns_error_string()

const char * dns_error_string

(

int

error_code

)

Get human-readable error message.

Returns a string description of the specified error code.

Parameters

error_code

Error code from dns_result_t

Returns

Pointer to error message string (never NULL)

Note

The returned string is statically allocated and should not be freed

dns_request_cancel()

bool dns_request_cancel

(

dns_request_t *

request

)

Cancel a pending DNS request.

Attempts to cancel a pending DNS resolution request. If successful, the callback will not be called for this request.

Parameters

request

Pointer to request handle

Returns

true if the request was successfully cancelled, false otherwise

Note

This function may fail if the request has already completed

Warning

Do not use the request pointer after calling this function

dns_resolve_async()

dns_request_t * dns_resolve_async	(	dns_resolver_t *	resolver,
		const char *	hostname,
		const char *	service,
		dns_callback_t	callback,
		void *	user_data )

Start asynchronous DNS resolution.

Initiates an asynchronous DNS resolution for the specified hostname. The callback function will be called when the resolution completes.

Parameters

resolver	DNS resolver instance
hostname	Hostname to resolve (null-terminated string)
service	Service name or port number (may be NULL)
callback	Callback function to call when resolution completes
user_data	User data to pass to the callback function

Returns

Pointer to request handle, or NULL on failure

Note

The returned request handle can be used to cancel the request

See also

dns_request_cancel()

dns_callback_t

dns_resolver_create()

dns_resolver_t * dns_resolver_create

(

const dns_config_t *

config

)

Create a new DNS resolver instance.

Creates and initializes a new DNS resolver with the specified configuration. The resolver must be destroyed with dns_resolver_destroy() when no longer needed.

Parameters

config

Pointer to configuration structure (NULL for default config)

Returns

Pointer to new resolver instance, or NULL on failure

See also

dns_resolver_destroy()

dns_config_default()

dns_resolver_destroy()

void dns_resolver_destroy

(

dns_resolver_t *

resolver

)

Destroy a DNS resolver instance.

Destroys the resolver and frees all associated resources. Any pending requests will be cancelled automatically.

Parameters

resolver

Pointer to resolver instance (may be NULL)

Warning

Do not use the resolver pointer after calling this function

See also

dns_resolver_create()

dns_resolver_process()

void dns_resolver_process

(

dns_resolver_t *

resolver

)

Process pending DNS operations.

This function must be called regularly (typically in your main event loop) to process completed DNS operations and invoke callbacks. It is non-blocking and will return immediately if no operations are ready.

Parameters

resolver

DNS resolver instance

Note

This function should be called frequently for timely callback execution

Thread-safe: can be called from multiple threads

dns_result_free()

void dns_result_free

(

dns_result_t *

result

)

Free DNS result structure.

Frees all memory associated with a DNS result structure, including the addresses array and hostname string.

Parameters

result

Pointer to result structure (may be NULL)

Note

This function must be called for each result passed to callbacks

Warning

Do not use the result pointer after calling this function