lib/libldns/ldns/net.h

   1 /*
   2  * net.h
   3  *
   4  * DNS Resolver definitions
   5  *
   6  * a Net::DNS like library for C
   7  *
   8  * (c) NLnet Labs, 2005-2006
   9  *
  10  * See the file LICENSE for the license
  11  */
  12
  13 #ifndef LDNS_NET_H
  14 #define LDNS_NET_H
  15
  16 #include <ldns/ldns.h>
  17 #include <sys/socket.h>
  18
  19 #ifdef __cplusplus
  20 extern "C" {
  21 #endif
  22
  23 #define LDNS_DEFAULT_TIMEOUT_SEC 5
  24 #define LDNS_DEFAULT_TIMEOUT_USEC 0
  25
  26 /**
  27  * \file
  28  *
  29  * Contains functions to send and receive packets over a network.
  30  */
  31
  32 /**
  33  * Sends a buffer to an ip using udp and return the response as a ldns_pkt
  34  * \param[in] qbin the ldns_buffer to be send
  35  * \param[in] to the ip addr to send to
  36  * \param[in] tolen length of the ip addr
  37  * \param[in] timeout the timeout value for the network
  38  * \param[out] answersize size of the packet
  39  * \param[out] result packet with the answer
  40  * \return status
  41  */
  42 ldns_status ldns_udp_send(uint8_t **result, ldns_buffer *qbin, const struct sockaddr_storage *to, socklen_t tolen, struct timeval timeout, size_t *answersize);
  43
  44 /**
  45  * Send an udp query and don't wait for an answer but return
  46  * the socket
  47  * \param[in] qbin the ldns_buffer to be send
  48  * \param[in] to the ip addr to send to
  49  * \param[in] tolen length of the ip addr
  50  * \param[in] timeout *unused*, was the timeout value for the network
  51  * \return the socket used or -1 on failure
  52  */
  53 int ldns_udp_bgsend2(ldns_buffer *qbin, const struct sockaddr_storage *to, socklen_t tolen, struct timeval timeout);
  54
  55 /**
  56  * Send an udp query and don't wait for an answer but return
  57  * the socket
  58  * This function has the flaw that it returns 0 on failure, but 0 could be a
  59  * valid socket.  Please use ldns_udp_bgsend2 instead of this function.
  60  * \param[in] qbin the ldns_buffer to be send
  61  * \param[in] to the ip addr to send to
  62  * \param[in] tolen length of the ip addr
  63  * \param[in] timeout *unused*, was the timeout value for the network
  64  * \return the socket used or 0 on failure
  65  */
  66 int ldns_udp_bgsend(ldns_buffer *qbin, const struct sockaddr_storage *to, socklen_t tolen, struct timeval timeout);
  67
  68 /**
  69  * Send an tcp query and don't wait for an answer but return
  70  * the socket
  71  * \param[in] qbin the ldns_buffer to be send
  72  * \param[in] to the ip addr to send to
  73  * \param[in] tolen length of the ip addr
  74  * \param[in] timeout the timeout value for the connect attempt
  75  * \return the socket used or -1 on failure
  76  */
  77 int ldns_tcp_bgsend2(ldns_buffer *qbin, const struct sockaddr_storage *to, socklen_t tolen, struct timeval timeout);
  78
  79 /**
  80  * Send an tcp query and don't wait for an answer but return
  81  * the socket
  82  * This function has the flaw that it returns 0 on failure, but 0 could be a
  83  * valid socket.  Please use ldns_tcp_bgsend2 instead of this function.
  84  * \param[in] qbin the ldns_buffer to be send
  85  * \param[in] to the ip addr to send to
  86  * \param[in] tolen length of the ip addr
  87  * \param[in] timeout the timeout value for the connect attempt
  88  * \return the socket used or 0 on failure
  89  */
  90 int ldns_tcp_bgsend(ldns_buffer *qbin, const struct sockaddr_storage *to, socklen_t tolen, struct timeval timeout);
  91
  92 /**
  93  * Sends a buffer to an ip using tcp and return the response as a ldns_pkt
  94  * \param[in] qbin the ldns_buffer to be send
  95  * \param[in] qbin the ldns_buffer to be send
  96  * \param[in] to the ip addr to send to
  97  * \param[in] tolen length of the ip addr
  98  * \param[in] timeout the timeout value for the network
  99  * \param[out] answersize size of the packet
 100  * \param[out] result packet with the answer
 101  * \return status
 102  */
 103 ldns_status ldns_tcp_send(uint8_t **result, ldns_buffer *qbin, const struct sockaddr_storage *to, socklen_t tolen, struct timeval timeout, size_t *answersize);
 104
 105 /**
 106  * Sends ptk to the nameserver at the resolver object. Returns the data
 107  * as a ldns_pkt
 108  *
 109  * \param[out] pkt packet received from the nameserver
 110  * \param[in] r the resolver to use
 111  * \param[in] query_pkt the query to send
 112  * \return status
 113  */
 114 ldns_status ldns_send(ldns_pkt **pkt, ldns_resolver *r, const ldns_pkt *query_pkt);
 115
 116 /**
 117  * Sends and ldns_buffer (presumably containing a packet to the nameserver at the resolver object. Returns the data
 118  * as a ldns_pkt
 119  *
 120  * \param[out] pkt packet received from the nameserver
 121  * \param[in] r the resolver to use
 122  * \param[in] qb the buffer to send
 123  * \param[in] tsig_mac the tsig MAC to authenticate the response with (NULL to do no TSIG authentication)
 124  * \return status
 125  */
 126 ldns_status ldns_send_buffer(ldns_pkt **pkt, ldns_resolver *r, ldns_buffer *qb, ldns_rdf *tsig_mac);
 127
 128 /**
 129  * Create a tcp socket to the specified address
 130  * \param[in] to ip and family
 131  * \param[in] tolen length of to
 132  * \param[in] timeout timeout for the connect attempt
 133  * \return a socket descriptor or -1 on failure
 134  */
 135 int ldns_tcp_connect2(const struct sockaddr_storage *to, socklen_t tolen, struct timeval timeout);
 136
 137 /**
 138  * Create a tcp socket to the specified address
 139  * This function has the flaw that it returns 0 on failure, but 0 could be a
 140  * valid socket.  Please use ldns_tcp_connect2 instead of this function.
 141  * \param[in] to ip and family
 142  * \param[in] tolen length of to
 143  * \param[in] timeout timeout for the connect attempt
 144  * \return a socket descriptor or 0 on failure
 145  */
 146 int ldns_tcp_connect(const struct sockaddr_storage *to, socklen_t tolen, struct timeval timeout);
 147
 148 /**
 149  * Create a udp socket to the specified address
 150  * \param[in] to ip and family
 151  * \param[in] timeout *unused*, was timeout for the socket
 152  * \return a socket descriptor or -1 on failure
 153  */
 154 int ldns_udp_connect2(const struct sockaddr_storage *to, struct timeval timeout);
 155
 156 /**
 157  * Create a udp socket to the specified address
 158  * This function has the flaw that it returns 0 on failure, but 0 could be a
 159  * valid socket.  Please use ldns_udp_connect2 instead of this function.
 160  * \param[in] to ip and family
 161  * \param[in] timeout *unused*, was timeout for the socket
 162  * \return a socket descriptor or 0 on failure
 163  */
 164 int ldns_udp_connect(const struct sockaddr_storage *to, struct timeval timeout);
 165
 166 /**
 167  * send a query via tcp to a server. Don't want for the answer
 168  *
 169  * \param[in] qbin the buffer to send
 170  * \param[in] sockfd the socket to use
 171  * \param[in] to which ip to send it
 172  * \param[in] tolen socketlen
 173  * \return number of bytes sent
 174  */
 175 ssize_t ldns_tcp_send_query(ldns_buffer *qbin, int sockfd, const struct sockaddr_storage *to, socklen_t tolen);
 176
 177 /**
 178  * send a query via udp to a server. Don;t want for the answer
 179  *
 180  * \param[in] qbin the buffer to send
 181  * \param[in] sockfd the socket to use
 182  * \param[in] to which ip to send it
 183  * \param[in] tolen socketlen
 184  * \return number of bytes sent
 185  */
 186 ssize_t ldns_udp_send_query(ldns_buffer *qbin, int sockfd, const struct sockaddr_storage *to, socklen_t tolen);
 187
 188 /**
 189  * Gives back a raw packet from the wire and reads the header data from the given
 190  * socket. Allocates the data (of size size) itself, so don't forget to free
 191  *
 192  * \param[in] sockfd the socket to read from
 193  * \param[out] size the number of bytes that are read
 194  * \param[in] timeout the time allowed between packets.
 195  * \return the data read
 196  */
 197 uint8_t *ldns_tcp_read_wire_timeout(int sockfd, size_t *size, struct timeval timeout);
 198
 199 /**
 200  * This routine may block. Use ldns_tcp_read_wire_timeout, it checks timeouts.
 201  * Gives back a raw packet from the wire and reads the header data from the given
 202  * socket. Allocates the data (of size size) itself, so don't forget to free
 203  *
 204  * \param[in] sockfd the socket to read from
 205  * \param[out] size the number of bytes that are read
 206  * \return the data read
 207  */
 208 uint8_t *ldns_tcp_read_wire(int sockfd, size_t *size);
 209
 210 /**
 211  * Gives back a raw packet from the wire and reads the header data from the given
 212  * socket. Allocates the data (of size size) itself, so don't forget to free
 213  *
 214  * \param[in] sockfd the socket to read from
 215  * \param[in] fr the address of the client (if applicable)
 216  * \param[in] *frlen the length of the client's addr (if applicable)
 217  * \param[out] size the number of bytes that are read
 218  * \return the data read
 219  */
 220 uint8_t *ldns_udp_read_wire(int sockfd, size_t *size, struct sockaddr_storage *fr, socklen_t *frlen);
 221
 222 /**
 223  * returns the native sockaddr representation from the rdf.
 224  * \param[in] rd the ldns_rdf to operate on
 225  * \param[in] port what port to use. 0 means; use default (53)
 226  * \param[out] size what is the size of the sockaddr_storage
 227  * \return struct sockaddr* the address in the format so other
 228  * functions can use it (sendto)
 229  */
 230 struct sockaddr_storage * ldns_rdf2native_sockaddr_storage(const ldns_rdf *rd, uint16_t port, size_t *size);
 231
 232 /**
 233  * returns an rdf with the sockaddr info. works for ip4 and ip6
 234  * \param[in] sock the struct sockaddr_storage to convert
 235  * \param[in] port what port was used. When NULL this is not set
 236  * \return ldns_rdf* with the address
 237  */
 238 ldns_rdf * ldns_sockaddr_storage2rdf(const struct sockaddr_storage *sock, uint16_t *port);
 239
 240 /**
 241  * Prepares the resolver for an axfr query
 242  * The query is sent and the answers can be read with ldns_axfr_next
 243  * \param[in] resolver the resolver to use
 244  * \param[in] domain the domain to axfr
 245  * \param[in] c the class to use
 246  * \return ldns_status the status of the transfer
 247  */
 248 ldns_status ldns_axfr_start(ldns_resolver *resolver, const ldns_rdf *domain, ldns_rr_class c);
 249
 250 #ifdef __cplusplus
 251 }
 252 #endif
 253
 254 #endif  /* LDNS_NET_H */