src/systemd/sd-dns.h

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