src/systemd/sd-resolve.h

   1 /*-*- Mode: C; c-basic-offset: 8; indent-tabs-mode: nil -*-*/
   2
   3 #ifndef foosdresolvehfoo
   4 #define foosdresolvehfoo
   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 sd-resolve allocate an sd_resolve_t object with
  37  * sd_resolve_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 sd_resolve_getaddrinfo() and
  40  * sd_resolve_getnameinfo(). Use sd_resolve_free() to shut down the worker
  41  * threads/processes.
  42  *
  43  * Since sd-resolve 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 sd-resolve session structure */
  48 typedef struct sd_resolve sd_resolve_t;
  49
  50 /** An opaque sd-resolve query structure */
  51 typedef struct sd_resolve_query sd_resolve_query_t;
  52
  53 /** Allocate a new sd-resolve session with n_proc worker processes/threads */
  54 sd_resolve_t* sd_resolve_new(unsigned n_proc);
  55
  56 /** Free a sd-resolve session. This destroys all attached
  57  * sd_resolve_query_t objects automatically */
  58 void sd_resolve_free(sd_resolve_t *resolve);
  59
  60 /** Return the UNIX file descriptor to select() for readability
  61  * on. Use this function to integrate sd-resolve with your custom main
  62  * loop. */
  63 int sd_resolve_fd(sd_resolve_t *resolve);
  64
  65 /** Process pending responses. After this function is called you can
  66  * get the next completed query object(s) using sd_resolve_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 sd_resolve_wait(sd_resolve_t *resolve, 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  * sd_resolve_getaddrinfo_done().*/
  77 sd_resolve_query_t* sd_resolve_getaddrinfo(sd_resolve_t *resolve, const char *node, const char *service, const struct addrinfo *hints);
  78
  79 /** Retrieve the results of a preceding sd_resolve_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 sd_resolve_freeaddrinfo() and not
  84  * libc's freeaddrinfo(3)! If the query is not completed yet EAI_AGAIN
  85  * is returned.*/
  86 int sd_resolve_getaddrinfo_done(sd_resolve_t *resolve, sd_resolve_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  * sd_resolve_getnameinfo_done(). Set gethost (resp. getserv) to non-zero
  93  * if you want to query the hostname (resp. the service name). */
  94 sd_resolve_query_t* sd_resolve_getnameinfo(sd_resolve_t *resolve, const struct sockaddr *sa, socklen_t salen, int flags, int gethost, int getserv);
  95
  96 /** Retrieve the results of a preceding sd_resolve_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 sd_resolve_getnameinfo_done(sd_resolve_t *resolve, sd_resolve_query_t* q, char *ret_host, size_t hostlen, char *ret_serv, size_t servlen);
 102
 103 /** Issue a resolveer 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  * sd_resolve_res_done().  */
 107 sd_resolve_query_t* sd_resolve_res_query(sd_resolve_t *resolve, const char *dname, int class, int type);
 108
 109 /** Issue an resolveer 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  * sd_resolve_res_done().  */
 113 sd_resolve_query_t* sd_resolve_res_search(sd_resolve_t *resolve, const char *dname, int class, int type);
 114
 115 /** Retrieve the results of a preceding sd_resolve_res_query() or
 116  * resolve_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 sd_resolve_freeanswer(). */
 122 int sd_resolve_res_done(sd_resolve_t *resolve, sd_resolve_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  * sd_resolve_wait() before this function will return sensible data.  */
 127 sd_resolve_query_t* sd_resolve_getnext(sd_resolve_t *resolve);
 128
 129 /** Return the number of query objects (completed or not) attached to
 130  * this session */
 131 int sd_resolve_getnqueries(sd_resolve_t *resolve);
 132
 133 /** Cancel a currently running query. q is is destroyed by this call
 134  * and may not be used any futher. */
 135 void sd_resolve_cancel(sd_resolve_t *resolve, sd_resolve_query_t* q);
 136
 137 /** Free the addrinfo structure as returned by
 138  * sd_resolve_getaddrinfo_done(). Make sure to use this functions instead
 139  * of the libc's freeaddrinfo()! */
 140 void sd_resolve_freeaddrinfo(struct addrinfo *ai);
 141
 142 /** Free the answer data as returned by sd_resolve_res_done().*/
 143 void sd_resolve_freeanswer(unsigned char *answer);
 144
 145 /** Returns non-zero when the query operation specified by q has been completed */
 146 int sd_resolve_isdone(sd_resolve_t *resolve, sd_resolve_query_t*q);
 147
 148 /** Assign some opaque userdata with a query object */
 149 void sd_resolve_setuserdata(sd_resolve_t *resolve, sd_resolve_query_t *q, void *userdata);
 150
 151 /** Return userdata assigned to a query object. Use
 152  * sd_resolve_setuserdata() to set this data. If no data has been set
 153  * prior to this call it returns NULL. */
 154 void* sd_resolve_getuserdata(sd_resolve_t *resolve, sd_resolve_query_t *q);
 155
 156 _SD_END_DECLARATIONS;
 157
 158 #endif