#ifndef ADNS_H_INCLUDED
#define ADNS_H_INCLUDED
+#ifdef __cplusplus
+extern "C" { /* I really dislike this - iwj. */
+#endif
#include <stdio.h>
#include <sys/socket.h>
#include <netinet/in.h>
+#include <sys/types.h>
+#include <sys/time.h>
+#include <unistd.h>
/* All struct in_addr anywhere in adns are in NETWORK byte order. */
* first adns_submit or _transact call using the same adns_state after
* it became invalid, so you may compare it for equality with other
* query handles until you next call _query or _transact.
+ *
+ * _submit and _synchronous return ENOSYS if they don't understand the
+ * query type.
*/
void adns_finish(adns_state ads);
*/
-struct adns_query adns_forallqueries_begin(adns_state ads, void **context_r);
-struct adns_query adns_forallqueries_next(adns_state ads, adns_query, void **context_r);
+void adns_forallqueries_begin(adns_state ads);
+adns_query adns_forallqueries_next(adns_state ads, void **context_r);
/* Iterator functions, which you can use to loop over the outstanding
- * (submitted but not yet successfuly checked/waited) queries. Each
- * function returns a query handle and a corresponding context pointer,
- * or returns 0 setting *context_r to 0 if there are no (more) queries.
- * There is no need to explicitly finish an iteration. context_r may be 0.
+ * (submitted but not yet successfuly checked/waited) queries.
*
- * IMPORTANT: you MUST NOT call ANY other adns function with the same
- * adns_state, or with a query in the same adns_state, while you are
- * doing one of these iterations. After such a call the iterator
- * value has undefined meaning and must not be used.
+ * You can only have one iteration going at once. You may call _begin
+ * at any time; after that, an iteration will be in progress. You may
+ * only call _next when an iteration is in progress - anything else
+ * may coredump. The iteration remains in progress until _next
+ * returns 0, indicating that all the queries have been walked over,
+ * or ANY other adns function is called with the same adns_state (or a
+ * query in the same adns_state). There is no need to explicitly
+ * finish an iteration.
+ *
+ * context_r may be 0. *context_r may not be set when _next returns 0.
*/
/*
* listen for more structs then *nfds_io will be set to the number
* required and _beforepoll will return ERANGE.
*
- * NOTE that if now is 0, adns may acquire additional fds from one
- * call to the next, so you must put adns_beforepoll in a loop, rather
- * than assuming that the second call (with the buffer size requested
- * by the first) will not return ERANGE.
- *
* You may call _beforepoll with fds==0 and *nfds_io 0, in which case
* adns will fill in the number of fds that it might be interested in
- * in *nfds_io, and always return 0.
+ * in *nfds_io, and always return either 0 (if it is not interested in
+ * any fds) or ERANGE (if it is).
+ *
+ * NOTE that (unless timeout_io is 0) adns may acquire additional fds
+ * from one call to the next, so you must put adns_beforepoll in a
+ * loop, rather than assuming that the second call (with the buffer
+ * size requested by the first) will not return ERANGE.
*
* adns only ever sets POLLIN, POLLOUT and POLLPRI in its pollfd
* structs, and only ever looks at those bits. POLLPRI is required to
- * detect TCP Urgent Data, which should not be used by a DNS server,
+ * detect TCP Urgent Data (which should not be used by a DNS server)
* so that adns can know that the TCP stream is now useless.
*
* In any case, *timeout_io should be a timeout value as for poll(2),
* which adns will modify downwards as required. If the caller does
- * not plan to block then *timeout_io should be 0 on entry.
+ * not plan to block then *timeout_io should be 0 on entry, or
+ * alternatively, timeout_io may be 0. (Alternatively, the caller may
+ * use _beforeselect with timeout_io==0 to find out about file
+ * descriptors, and use _firsttimeout is used to find out when adns
+ * might want to time something out.)
*
* adns_beforepoll will return 0 on success, and will not fail for any
* reason other than the fds buffer being too small (ERANGE).
*
- * If *now is not 0 then this call will never actually do any I/O, or
- * change the fds that adns is using or the timeouts it wants. In any
- * case it won't block.
+ * This call will never actually do any I/O, or change the fds that
+ * adns is using or the timeouts it wants; and in any case it won't
+ * block.
*/
#define ADNS_POLLFDS_RECOMMENDED 2
* not returned by the same adns library.
*/
+#ifdef __cplusplus
+} /* end of extern "C" */
+#endif
#endif
~ianmdlvl / adns.git / blobdiff