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-2014 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
  29 #include "_sd-common.h"
  30
  31 _SD_BEGIN_DECLARATIONS;
  32
  33 /** An opaque sd-resolve session structure */
  34 typedef struct sd_resolve sd_resolve;
  35
  36 /** An opaque sd-resolve query structure */
  37 typedef struct sd_resolve_query sd_resolve_query;
  38
  39 /** Allocate a new sd-resolve session */
  40 int sd_resolve_new(sd_resolve **ret);
  41
  42 /** Free a sd-resolve session. This destroys all attached
  43  * sd_resolve_query objects automatically */
  44 sd_resolve* sd_resolve_unref(sd_resolve *resolve);
  45
  46 /** Return the UNIX file descriptor to poll() for events on. Use this
  47  * function to integrate sd-resolve with your custom main loop. */
  48 int sd_resolve_get_fd(sd_resolve *resolve);
  49
  50 /** Return the poll() events (a combination of flags like POLLIN,
  51  * POLLOUT, ...) to check for. */
  52 int sd_resolve_get_events(sd_resolve *resolve);
  53
  54 /** Return the poll() timeout to pass. Returns (uint64_t) -1 as time
  55  * out if no time out is needed */
  56 int sd_resolve_get_timeout(sd_resolve *resolve, uint64_t *timeout_usec);
  57
  58 /** Process pending responses. After this function is called you can
  59  * get the next completed query object(s) using
  60  * sd_resolve_get_next(). */
  61 int sd_resolve_process(sd_resolve *resolve);
  62
  63 /** Wait for a resolve event to complete */
  64 int sd_resolve_wait(sd_resolve *resolve, uint64_t timeout_usec);
  65
  66 /** Issue a name to address query on the specified session. The
  67  * arguments are compatible with the ones of libc's
  68  * getaddrinfo(3). The function returns a new query object. When the
  69  * query is completed you may retrieve the results using
  70  * sd_resolve_getaddrinfo_done(). */
  71 int sd_resolve_getaddrinfo(sd_resolve *resolve, const char *node, const char *service, const struct addrinfo *hints, sd_resolve_query **q);
  72
  73 /** Retrieve the results of a preceding sd_resolve_getaddrinfo()
  74  * call. Returns a addrinfo structure and a return value compatible
  75  * with libc's getaddrinfo(3). The query object q is destroyed by this
  76  * call and may not be used any further. Make sure to free the
  77  * returned addrinfo structure with sd_resolve_freeaddrinfo() and not
  78  * libc's freeaddrinfo(3)! If the query is not completed yet EAI_AGAIN
  79  * is returned. */
  80 int sd_resolve_getaddrinfo_done(sd_resolve_query* q, struct addrinfo **ret_ai);
  81
  82 /** Free the addrinfo structure as returned by
  83  * sd_resolve_getaddrinfo_done(). Make sure to use this functions instead
  84  * of the libc's freeaddrinfo()! */
  85 void sd_resolve_freeaddrinfo(struct addrinfo *ai);
  86
  87 /** Issue an address to name query on the specified session. The
  88  * arguments are compatible with the ones of libc's
  89  * getnameinfo(3). The function returns a new query object. When the
  90  * query is completed you may retrieve the results using
  91  * sd_resolve_getnameinfo_done(). Set gethost (resp. getserv) to non-zero
  92  * if you want to query the hostname (resp. the service name). */
  93 int sd_resolve_getnameinfo(sd_resolve *resolve, const struct sockaddr *sa, socklen_t salen, int flags, int gethost, int getserv, sd_resolve_query **q);
  94
  95 /** Retrieve the results of a preceding sd_resolve_getnameinfo()
  96  * call. Returns the hostname and the service name in ret_host and
  97  * ret_serv. The query object q is destroyed by this call and may not
  98  * be used any further. If the query is not completed yet EAI_AGAIN is
  99  * returned. */
 100 int sd_resolve_getnameinfo_done(sd_resolve_query* q, char **ret_host, char **ret_serv);
 101
 102 /** Issue a resolver query on the specified session. The arguments are
 103  * compatible with the ones of libc's res_query(3). The function returns a new
 104  * query object. When the query is completed you may retrieve the results using
 105  * sd_resolve_res_done().  */
 106 int sd_resolve_res_query(sd_resolve *resolve, const char *dname, int class, int type, sd_resolve_query **q);
 107
 108 /** Issue an resolver query on the specified session. The arguments are
 109  * compatible with the ones of libc's res_search(3). The function returns a new
 110  * query object. When the query is completed you may retrieve the results using
 111  * sd_resolve_res_done().  */
 112 int sd_resolve_res_search(sd_resolve *resolve, const char *dname, int class, int type, sd_resolve_query **q);
 113
 114 /** Retrieve the results of a preceding sd_resolve_res_query() or
 115  * resolve_res_search call.  The query object q is destroyed by this
 116  * call and may not be used any further. Returns a pointer to the
 117  * answer of the res_query call. If the query is not completed yet
 118  * -EAGAIN is returned, on failure -errno is returned, otherwise the
 119  * length of answer is returned. */
 120 int sd_resolve_res_done(sd_resolve_query* q, unsigned char **answer);
 121
 122 /** Return the next completed query object. If no query has been
 123  * completed yet, return NULL. Please note that you need to run
 124  * sd_resolve_wait() before this function will return sensible data.  */
 125 int sd_resolve_get_next(sd_resolve *resolve, sd_resolve_query **q);
 126
 127 /** Return the number of query objects (completed or not) attached to
 128  * this session */
 129 int sd_resolve_get_n_queries(sd_resolve *resolve);
 130
 131 /** Cancel a currently running query. q is is destroyed by this call
 132  * and may not be used any futher. */
 133 int sd_resolve_cancel(sd_resolve_query* q);
 134
 135 /** Returns non-zero when the query operation specified by q has been completed */
 136 int sd_resolve_is_done(sd_resolve_query*q);
 137
 138 /** Assign some opaque userdata with a query object */
 139 void* sd_resolve_set_userdata(sd_resolve_query *q, void *userdata);
 140
 141 /** Return userdata assigned to a query object. Use
 142  * sd_resolve_setuserdata() to set this data. If no data has been set
 143  * prior to this call it returns NULL. */
 144 void* sd_resolve_get_userdata(sd_resolve_query *q);
 145
 146 _SD_END_DECLARATIONS;
 147
 148 #endif