gio/libasyncns/asyncns.h

   1 #ifndef fooasyncnshfoo
   2 #define fooasyncnshfoo
   3
   4 /***
   5   This file is part of libasyncns.
   6
   7   Copyright 2005-2008 Lennart Poettering
   8
   9   libasyncns is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU Lesser General Public License as
  11   published by the Free Software Foundation, either version 2.1 of the
  12   License, or (at your option) any later version.
  13
  14   libasyncns is distributed in the hope that it will be useful, but
  15   WITHOUT ANY WARRANTY; without even the implied warranty of
  16   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  17   Lesser General Public License for more details.
  18
  19   You should have received a copy of the GNU Lesser General Public
  20   License along with libasyncns. If not, see
  21   <http://www.gnu.org/licenses/>.
  22 ***/
  23
  24 #include <sys/types.h>
  25 #include <sys/socket.h>
  26 #include <netdb.h>
  27
  28 /** \mainpage
  29  *
  30  * \section moo Method of operation
  31  *
  32  * To use libasyncns allocate an _g_asyncns_t object with
  33  * _g_asyncns_new(). This will spawn a number of worker threads (or processes, depending on what is available) which
  34  * are subsequently used to process the queries the controlling
  35  * program issues via _g_asyncns_getaddrinfo() and
  36  * _g_asyncns_getnameinfo(). Use _g_asyncns_free() to shut down the worker
  37  * threads/processes.
  38  *
  39  * Since libasyncns may fork off new processes you have to make sure that
  40  * your program is not irritated by spurious SIGCHLD signals.
  41  */
  42
  43 /** \example asyncns-test.c
  44  * An example program */
  45
  46 #ifdef  __cplusplus
  47 extern "C" {
  48 #endif
  49
  50 /** An opaque libasyncns session structure */
  51 typedef struct asyncns _g_asyncns_t;
  52
  53 /** An opaque libasyncns query structure */
  54 typedef struct _g_asyncns_query _g_asyncns_query_t;
  55
  56 /** Allocate a new libasyncns session with n_proc worker processes/threads */
  57 _g_asyncns_t* _g_asyncns_new(unsigned n_proc);
  58
  59 /** Free a libasyncns session. This destroys all attached
  60  * _g_asyncns_query_t objects automatically */
  61 void _g_asyncns_free(_g_asyncns_t *asyncns);
  62
  63 /** Return the UNIX file descriptor to select() for readability
  64  * on. Use this function to integrate libasyncns with your custom main
  65  * loop. */
  66 int _g_asyncns_fd(_g_asyncns_t *asyncns);
  67
  68 /** Process pending responses. After this function is called you can
  69  * get the next completed query object(s) using _g_asyncns_getnext(). If
  70  * block is non-zero wait until at least one response has been
  71  * processed. If block is zero, process all pending responses and
  72  * return. */
  73 int _g_asyncns_wait(_g_asyncns_t *asyncns, int block);
  74
  75 /** Issue a name to address query on the specified session. The
  76  * arguments are compatible with the ones of libc's
  77  * getaddrinfo(3). The function returns a new query object. When the
  78  * query is completed you may retrieve the results using
  79  * _g_asyncns_getaddrinfo_done().*/
  80 _g_asyncns_query_t* _g_asyncns_getaddrinfo(_g_asyncns_t *asyncns, const char *node, const char *service, const struct addrinfo *hints);
  81
  82 /** Retrieve the results of a preceding _g_asyncns_getaddrinfo()
  83  * call. Returns a addrinfo structure and a return value compatible
  84  * with libc's getaddrinfo(3). The query object q is destroyed by this
  85  * call and may not be used any further. Make sure to free the
  86  * returned addrinfo structure with _g_asyncns_freeaddrinfo() and not
  87  * libc's freeaddrinfo(3)! If the query is not completed yet EAI_AGAIN
  88  * is returned.*/
  89 int _g_asyncns_getaddrinfo_done(_g_asyncns_t *asyncns, _g_asyncns_query_t* q, struct addrinfo **ret_res);
  90
  91 /** Issue an address to name query on the specified session. The
  92  * arguments are compatible with the ones of libc's
  93  * getnameinfo(3). The function returns a new query object. When the
  94  * query is completed you may retrieve the results using
  95  * _g_asyncns_getnameinfo_done(). Set gethost (resp. getserv) to non-zero
  96  * if you want to query the hostname (resp. the service name). */
  97 _g_asyncns_query_t* _g_asyncns_getnameinfo(_g_asyncns_t *asyncns, const struct sockaddr *sa, socklen_t salen, int flags, int gethost, int getserv);
  98
  99 /** Retrieve the results of a preceding _g_asyncns_getnameinfo()
 100  * call. Returns the hostname and the service name in ret_host and
 101  * ret_serv. The query object q is destroyed by this call and may not
 102  * be used any further. If the query is not completed yet EAI_AGAIN is
 103  * returned. */
 104 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);
 105
 106 /** Issue a resolver query on the specified session. The arguments are
 107  * compatible with the ones of libc's res_query(3). The function returns a new
 108  * query object. When the query is completed you may retrieve the results using
 109  * _g_asyncns_res_done().  */
 110 _g_asyncns_query_t* _g_asyncns_res_query(_g_asyncns_t *asyncns, const char *dname, int class, int type);
 111
 112 /** Issue an resolver query on the specified session. The arguments are
 113  * compatible with the ones of libc's res_search(3). The function returns a new
 114  * query object. When the query is completed you may retrieve the results using
 115  * _g_asyncns_res_done().  */
 116 _g_asyncns_query_t* _g_asyncns_res_search(_g_asyncns_t *asyncns, const char *dname, int class, int type);
 117
 118 /** Retrieve the results of a preceding _g_asyncns_res_query() or
 119  * _g_asyncns_res_search call.  The query object q is destroyed by this
 120  * call and may not be used any further. Returns a pointer to the
 121  * answer of the res_query call. If the query is not completed yet
 122  * -EAGAIN is returned, on failure -errno is returned, otherwise the
 123  * length of answer is returned. Make sure to free the answer is a
 124  * call to _g_asyncns_freeanswer(). */
 125 int _g_asyncns_res_done(_g_asyncns_t *asyncns, _g_asyncns_query_t* q, unsigned char **answer);
 126
 127 /** Return the next completed query object. If no query has been
 128  * completed yet, return NULL. Please note that you need to run
 129  * _g_asyncns_wait() before this function will return sensible data.  */
 130 _g_asyncns_query_t* _g_asyncns_getnext(_g_asyncns_t *asyncns);
 131
 132 /** Return the number of query objects (completed or not) attached to
 133  * this session */
 134 int _g_asyncns_getnqueries(_g_asyncns_t *asyncns);
 135
 136 /** Cancel a currently running query. q is is destroyed by this call
 137  * and may not be used any futher. */
 138 void _g_asyncns_cancel(_g_asyncns_t *asyncns, _g_asyncns_query_t* q);
 139
 140 /** Free the addrinfo structure as returned by
 141  * _g_asyncns_getaddrinfo_done(). Make sure to use this functions instead
 142  * of the libc's freeaddrinfo()! */
 143 void _g_asyncns_freeaddrinfo(struct addrinfo *ai);
 144
 145 /** Free the answer data as returned by _g_asyncns_res_done().*/
 146 void _g_asyncns_freeanswer(unsigned char *answer);
 147
 148 /** Returns non-zero when the query operation specified by q has been completed */
 149 int _g_asyncns_isdone(_g_asyncns_t *asyncns, _g_asyncns_query_t*q);
 150
 151 /** Assign some opaque userdata with a query object */
 152 void _g_asyncns_setuserdata(_g_asyncns_t *asyncns, _g_asyncns_query_t *q, void *userdata);
 153
 154 /** Return userdata assigned to a query object. Use
 155  * _g_asyncns_setuserdata() to set this data. If no data has been set
 156  * prior to this call it returns NULL. */
 157 void* _g_asyncns_getuserdata(_g_asyncns_t *asyncns, _g_asyncns_query_t *q);
 158
 159 #ifdef  __cplusplus
 160 }
 161 #endif
 162
 163 #endif