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