mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-10-30 07:52:17 +01:00
c94d3f9288
GResolver provides asynchronous (and synchronous-but-cancellable) APIs for resolving hostnames, reverse-resolving IP addresses back to hostnames, and resolving SRV records. Part of #548466.
164 lines
7.0 KiB
C
164 lines
7.0 KiB
C
#ifndef fooasyncnshfoo
|
|
#define fooasyncnshfoo
|
|
|
|
/***
|
|
This file is part of libasyncns.
|
|
|
|
Copyright 2005-2008 Lennart Poettering
|
|
|
|
libasyncns is free software; you can redistribute it and/or modify
|
|
it under the terms of the GNU Lesser General Public License as
|
|
published by the Free Software Foundation, either version 2.1 of the
|
|
License, or (at your option) any later version.
|
|
|
|
libasyncns is distributed in the hope that it will be useful, but
|
|
WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
Lesser General Public License for more details.
|
|
|
|
You should have received a copy of the GNU Lesser General Public
|
|
License along with libasyncns. If not, see
|
|
<http://www.gnu.org/licenses/>.
|
|
***/
|
|
|
|
#include <sys/types.h>
|
|
#include <sys/socket.h>
|
|
#include <netdb.h>
|
|
|
|
/** \mainpage
|
|
*
|
|
* \section moo Method of operation
|
|
*
|
|
* To use libasyncns allocate an _g_asyncns_t object with
|
|
* _g_asyncns_new(). This will spawn a number of worker threads (or processes, depending on what is available) which
|
|
* are subsequently used to process the queries the controlling
|
|
* program issues via _g_asyncns_getaddrinfo() and
|
|
* _g_asyncns_getnameinfo(). Use _g_asyncns_free() to shut down the worker
|
|
* threads/processes.
|
|
*
|
|
* Since libasyncns may fork off new processes you have to make sure that
|
|
* your program is not irritated by spurious SIGCHLD signals.
|
|
*/
|
|
|
|
/** \example asyncns-test.c
|
|
* An example program */
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/** An opaque libasyncns session structure */
|
|
typedef struct asyncns _g_asyncns_t;
|
|
|
|
/** An opaque libasyncns query structure */
|
|
typedef struct _g_asyncns_query _g_asyncns_query_t;
|
|
|
|
/** Allocate a new libasyncns session with n_proc worker processes/threads */
|
|
_g_asyncns_t* _g_asyncns_new(unsigned n_proc);
|
|
|
|
/** Free a libasyncns session. This destroys all attached
|
|
* _g_asyncns_query_t objects automatically */
|
|
void _g_asyncns_free(_g_asyncns_t *asyncns);
|
|
|
|
/** Return the UNIX file descriptor to select() for readability
|
|
* on. Use this function to integrate libasyncns with your custom main
|
|
* loop. */
|
|
int _g_asyncns_fd(_g_asyncns_t *asyncns);
|
|
|
|
/** Process pending responses. After this function is called you can
|
|
* get the next completed query object(s) using _g_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. */
|
|
int _g_asyncns_wait(_g_asyncns_t *asyncns, int block);
|
|
|
|
/** 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
|
|
* _g_asyncns_getaddrinfo_done().*/
|
|
_g_asyncns_query_t* _g_asyncns_getaddrinfo(_g_asyncns_t *asyncns, const char *node, const char *service, const struct addrinfo *hints);
|
|
|
|
/** Retrieve the results of a preceding _g_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 _g_asyncns_freeaddrinfo() and not
|
|
* libc's freeaddrinfo(3)! If the query is not completed yet EAI_AGAIN
|
|
* is returned.*/
|
|
int _g_asyncns_getaddrinfo_done(_g_asyncns_t *asyncns, _g_asyncns_query_t* q, struct addrinfo **ret_res);
|
|
|
|
/** 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
|
|
* _g_asyncns_getnameinfo_done(). Set gethost (resp. getserv) to non-zero
|
|
* if you want to query the hostname (resp. the service name). */
|
|
_g_asyncns_query_t* _g_asyncns_getnameinfo(_g_asyncns_t *asyncns, const struct sockaddr *sa, socklen_t salen, int flags, int gethost, int getserv);
|
|
|
|
/** Retrieve the results of a preceding _g_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. */
|
|
int _g_asyncns_getnameinfo_done(_g_asyncns_t *asyncns, _g_asyncns_query_t* q, char *ret_host, size_t hostlen, char *ret_serv, size_t servlen);
|
|
|
|
/** 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
|
|
* _g_asyncns_res_done(). */
|
|
_g_asyncns_query_t* _g_asyncns_res_query(_g_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
|
|
* _g_asyncns_res_done(). */
|
|
_g_asyncns_query_t* _g_asyncns_res_search(_g_asyncns_t *asyncns, const char *dname, int class, int type);
|
|
|
|
/** Retrieve the results of a preceding _g_asyncns_res_query() or
|
|
* _g_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 _g_asyncns_freeanswer(). */
|
|
int _g_asyncns_res_done(_g_asyncns_t *asyncns, _g_asyncns_query_t* q, unsigned char **answer);
|
|
|
|
/** Return the next completed query object. If no query has been
|
|
* completed yet, return NULL. Please note that you need to run
|
|
* _g_asyncns_wait() before this function will return sensible data. */
|
|
_g_asyncns_query_t* _g_asyncns_getnext(_g_asyncns_t *asyncns);
|
|
|
|
/** Return the number of query objects (completed or not) attached to
|
|
* this session */
|
|
int _g_asyncns_getnqueries(_g_asyncns_t *asyncns);
|
|
|
|
/** Cancel a currently running query. q is is destroyed by this call
|
|
* and may not be used any futher. */
|
|
void _g_asyncns_cancel(_g_asyncns_t *asyncns, _g_asyncns_query_t* q);
|
|
|
|
/** Free the addrinfo structure as returned by
|
|
* _g_asyncns_getaddrinfo_done(). Make sure to use this functions instead
|
|
* of the libc's freeaddrinfo()! */
|
|
void _g_asyncns_freeaddrinfo(struct addrinfo *ai);
|
|
|
|
/** Free the answer data as returned by _g_asyncns_res_done().*/
|
|
void _g_asyncns_freeanswer(unsigned char *answer);
|
|
|
|
/** Returns non-zero when the query operation specified by q has been completed */
|
|
int _g_asyncns_isdone(_g_asyncns_t *asyncns, _g_asyncns_query_t*q);
|
|
|
|
/** Assign some opaque userdata with a query object */
|
|
void _g_asyncns_setuserdata(_g_asyncns_t *asyncns, _g_asyncns_query_t *q, void *userdata);
|
|
|
|
/** Return userdata assigned to a query object. Use
|
|
* _g_asyncns_setuserdata() to set this data. If no data has been set
|
|
* prior to this call it returns NULL. */
|
|
void* _g_asyncns_getuserdata(_g_asyncns_t *asyncns, _g_asyncns_query_t *q);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif
|