asyncns.h File Reference

Go to the source code of this file.

Typedefs
typedef struct asyncns	asyncns_t
	An opaque libasyncns session structure.
typedef struct asyncns_query	asyncns_query_t
	An opaque libasyncns query structure.
Functions
asyncns_t *	asyncns_new (unsigned n_proc)
	Allocate a new libasyncns session with n_proc worker processes/threads.
void	asyncns_free (asyncns_t *asyncns)
	Free a libasyncns session.
int	asyncns_fd (asyncns_t *asyncns)
	Return the UNIX file descriptor to select() for readability on.
int	asyncns_wait (asyncns_t *asyncns, int block)
	Process pending responses.
asyncns_query_t *	asyncns_getaddrinfo (asyncns_t *asyncns, const char *node, const char *service, const struct addrinfo *hints)
	Issue a name to address query on the specified session.
int	asyncns_getaddrinfo_done (asyncns_t *asyncns, asyncns_query_t *q, struct addrinfo **ret_res)
	Retrieve the results of a preceding asyncns_getaddrinfo() call.
asyncns_query_t *	asyncns_getnameinfo (asyncns_t *asyncns, const struct sockaddr *sa, socklen_t salen, int flags, int gethost, int getserv)
	Issue an address to name query on the specified session.
int	asyncns_getnameinfo_done (asyncns_t *asyncns, asyncns_query_t *q, char *ret_host, size_t hostlen, char *ret_serv, size_t servlen)
	Retrieve the results of a preceding asyncns_getnameinfo() call.
asyncns_query_t *	asyncns_res_query (asyncns_t *asyncns, const char *dname, int class, int type)
	Issue a resolver query on the specified session.
asyncns_query_t *	asyncns_res_search (asyncns_t *asyncns, const char *dname, int class, int type)
	Issue an resolver query on the specified session.
int	asyncns_res_done (asyncns_t *asyncns, asyncns_query_t *q, unsigned char **answer)
	Retrieve the results of a preceding asyncns_res_query() or asyncns_res_search call.
asyncns_query_t *	asyncns_getnext (asyncns_t *asyncns)
	Return the next completed query object.
int	asyncns_getnqueries (asyncns_t *asyncns)
	Return the number of query objects (completed or not) attached to this session.
void	asyncns_cancel (asyncns_t *asyncns, asyncns_query_t *q)
	Cancel a currently running query.
void	asyncns_freeaddrinfo (struct addrinfo *ai)
	Free the addrinfo structure as returned by asyncns_getaddrinfo_done().
void	asyncns_freeanswer (unsigned char *answer)
	Free the answer data as returned by asyncns_res_done().
int	asyncns_isdone (asyncns_t *asyncns, asyncns_query_t *q)
	Returns non-zero when the query operation specified by q has been completed.
void	asyncns_setuserdata (asyncns_t *asyncns, asyncns_query_t *q, void *userdata)
	Assign some opaque userdata with a query object.
void *	asyncns_getuserdata (asyncns_t *asyncns, asyncns_query_t *q)
	Return userdata assigned to a query object.

---

Typedef Documentation

typedef struct asyncns_query asyncns_query_t

An opaque libasyncns query structure.

Examples:

asyncns-test.c.

typedef struct asyncns asyncns_t

An opaque libasyncns session structure.

Examples:

asyncns-test.c.

---

Function Documentation

void asyncns_cancel	(	asyncns_t *	asyncns,
		asyncns_query_t *	q
	)

Cancel a currently running query.

q is is destroyed by this call and may not be used any futher.

int asyncns_fd

(

asyncns_t *

asyncns

)

Return the UNIX file descriptor to select() for readability on.

Use this function to integrate libasyncns with your custom main loop.

void asyncns_free

(

asyncns_t *

asyncns

)

Free a libasyncns session.

This destroys all attached asyncns_query_t objects automatically

Examples:

asyncns-test.c.

void asyncns_freeaddrinfo

(

struct addrinfo *

ai

)

Free the addrinfo structure as returned by asyncns_getaddrinfo_done().

Make sure to use this functions instead of the libc's freeaddrinfo()!

Examples:

asyncns-test.c.

void asyncns_freeanswer

(

unsigned char *

answer

)

Free the answer data as returned by asyncns_res_done().

Examples:

asyncns-test.c.

asyncns_query_t* asyncns_getaddrinfo	(	asyncns_t *	asyncns,
		const char *	node,
		const char *	service,
		const struct addrinfo *	hints
	)

Issue a name to address query on the specified session.

The arguments are compatible with the ones of libc's getaddrinfo(3). The function returns a new query object. When the query is completed you may retrieve the results using asyncns_getaddrinfo_done().

Examples:

asyncns-test.c.

int asyncns_getaddrinfo_done	(	asyncns_t *	asyncns,
		asyncns_query_t *	q,
		struct addrinfo **	ret_res
	)

Retrieve the results of a preceding asyncns_getaddrinfo() call.

Returns a addrinfo structure and a return value compatible with libc's getaddrinfo(3). The query object q is destroyed by this call and may not be used any further. Make sure to free the returned addrinfo structure with asyncns_freeaddrinfo() and not libc's freeaddrinfo(3)! If the query is not completed yet EAI_AGAIN is returned.

Examples:

asyncns-test.c.

asyncns_query_t* asyncns_getnameinfo	(	asyncns_t *	asyncns,
		const struct sockaddr *	sa,
		socklen_t	salen,
		int	flags,
		int	gethost,
		int	getserv
	)

Issue an address to name query on the specified session.

The arguments are compatible with the ones of libc's getnameinfo(3). The function returns a new query object. When the query is completed you may retrieve the results using asyncns_getnameinfo_done(). Set gethost (resp. getserv) to non-zero if you want to query the hostname (resp. the service name).

Examples:

asyncns-test.c.

int asyncns_getnameinfo_done	(	asyncns_t *	asyncns,
		asyncns_query_t *	q,
		char *	ret_host,
		size_t	hostlen,
		char *	ret_serv,
		size_t	servlen
	)

Retrieve the results of a preceding asyncns_getnameinfo() call.

Returns the hostname and the service name in ret_host and ret_serv. The query object q is destroyed by this call and may not be used any further. If the query is not completed yet EAI_AGAIN is returned.

Examples:

asyncns-test.c.

asyncns_query_t* asyncns_getnext

(

asyncns_t *

asyncns

)

Return the next completed query object.

If no query has been completed yet, return NULL. Please note that you need to run asyncns_wait() before this function will return sensible data.

int asyncns_getnqueries

(

asyncns_t *

asyncns

)

Return the number of query objects (completed or not) attached to this session.

void* asyncns_getuserdata	(	asyncns_t *	asyncns,
		asyncns_query_t *	q
	)

Return userdata assigned to a query object.

Use asyncns_setuserdata() to set this data. If no data has been set prior to this call it returns NULL.

int asyncns_isdone	(	asyncns_t *	asyncns,
		asyncns_query_t *	q
	)

Returns non-zero when the query operation specified by q has been completed.

Examples:

asyncns-test.c.

asyncns_t* asyncns_new

(

unsigned

n_proc

)

Allocate a new libasyncns session with n_proc worker processes/threads.

Examples:

asyncns-test.c.

int asyncns_res_done	(	asyncns_t *	asyncns,
		asyncns_query_t *	q,
		unsigned char **	answer
	)

Retrieve the results of a preceding asyncns_res_query() or asyncns_res_search call.

The query object q is destroyed by this call and may not be used any further. Returns a pointer to the answer of the res_query call. If the query is not completed yet -EAGAIN is returned, on failure -errno is returned, otherwise the length of answer is returned. Make sure to free the answer is a call to asyncns_freeanswer().

Examples:

asyncns-test.c.

asyncns_query_t* asyncns_res_query	(	asyncns_t *	asyncns,
		const char *	dname,
		int	class,
		int	type
	)

Issue a resolver query on the specified session.

The arguments are compatible with the ones of libc's res_query(3). The function returns a new query object. When the query is completed you may retrieve the results using asyncns_res_done().

Examples:

asyncns-test.c.

asyncns_query_t* asyncns_res_search	(	asyncns_t *	asyncns,
		const char *	dname,
		int	class,
		int	type
	)

Issue an resolver query on the specified session.

The arguments are compatible with the ones of libc's res_search(3). The function returns a new query object. When the query is completed you may retrieve the results using asyncns_res_done().

void asyncns_setuserdata	(	asyncns_t *	asyncns,
		asyncns_query_t *	q,
		void *	userdata
	)

Assign some opaque userdata with a query object.

int asyncns_wait	(	asyncns_t *	asyncns,
		int	block
	)

Process pending responses.

After this function is called you can get the next completed query object(s) using asyncns_getnext(). If block is non-zero wait until at least one response has been processed. If block is zero, process all pending responses and return.

Examples:

asyncns-test.c.