| P_net_async_dns 3porty | 2012-01-25 | libporty manual |
|---|
P_net_async_dns
#include <libporty/net_async/abgproc.h>int P_net_async_dns (P_net_socket * fd );
int P_net_async_dns_req (P_net_socket fd , P_net_async_dns_req_t * req );
int P_net_async_dns_read (void ** buf , P_net_socket fd );
int P_net_async_dns_parse (void ** buf , P_net_async_dns_req_t * ans );
int P_net_async_dns_destroy (void ** buf , P_net_socket fd );Link with -lporty_net_async
P_net_async_dns creates an asyncron dns resolver (thread or process, depending on what the system offers). Communication protocol is a simple line based text stream on fd. Normally the caller will not try to parse that directly but calls the req, read, parse functions of P_Net_async_dns.It is possible to create multiple resolvers and use them in parallel. The resolver calls blocking functions P_dns4_name_to_IP nd P_dns4_IP_to_name.nl;
The following high level functions are provided for easier parsing of the protocol. None of these calls will ever block.
P_net_async_dns_req sends request req to the resolver. The caller should P_poll or the resolver fd and when it becomes readable call P_net_async_dns_read . buf shall be a pointer initialized to NULL before the first call. After calling P_net_async_dns_read , the caller should call P_net_async_dns_parse in a loop until it returns -1, and examine fields of output argument ans after each call.
If the application calls P_net_async_dns only, simply closing the fd will kill and uninitialize the associated background resolver. If any of the other (high level) functions are called as well, uninitialization should be done by calling P_net_async_dns_destroy , which in turn will free buff and destroys the background resolver (closes fd ).
The caller may pass on multiple requests to the resolver, which will process and answer the requests in order. However, to make it easier for the caller to pair up requests with answers, an optional cookie field is provided in both the request and the answer; the caller may set the cookie to arbitrary value and the answer will contain the same cookie.
Struct P_net_async_dns_req_t has the following fields:
P_net_async_dns_outcome_t values are:
union cookie; request/answer cookie; an union for different types char *hostname; char *ip_addr; exactly one of these should be NULL in a request; both will be filled in in the answer P_net_async_dns_outcome_t outcome; status code of the action
P_NET_DNS_OUT_OK = 0 success P_NET_DNS_OUT_PROTOCOL = 1 protocol is not supported (can't be triggered by high level calls at the moment) P_NET_DNS_OUT_NUMARGS = 2 not enough arguments (should not happen when using high level calls) P_NET_DNS_OUT_COMMAND = 3 invalid command (protocol error; should not happen when using high level calls) P_NET_DNS_OUT_RESOLV = 4 resolver failure - request is valid, but can not be resolved P_NET_DNS_OUT_INTERNAL = -1 internal error in the parser
All calls return 0 on success or a negative number on failure.
| P_net_async_dns 3porty | 2012-01-25 | libporty manual |
|---|