1libval_async(3) Programmer's Manual libval_async(3)
2
6 val_async_submit() - submits a request for asynchronous processing of
7 DNS queries.
8 val_async_select_info() - set the appropriate file descriptors for
10 outstanding asynchronous requests.
11 val_async_check_wait() - handle timeouts or processes DNS responses to
13 outstanding queries.
14 val_async_cancel() - cancel an asynchronous query request.
16 val_async_cancel_all() - cancel all asynchronous queries for a given
18 context.
19
21 #include <validator/validator.h>
22 typedef int (*val_async_event_cb)(val_async_status *async_status,
24 int event, val_context_t *context,
25 void *cb_data, val_cb_params_t *cbp);
26 int val_async_submit(val_context_t *context,
28 const char * name, int class,
29 int type, unsigned int flags,
30 val_async_event_cb callback, void *cb_data,
31 val_async_status **async_status);
32 int val_async_select_info(val_context_t *context,
34 fd_set *fds,
35 int *num_fds,
36 struct timeval *timeout);
37 int val_async_check_wait(val_context_t *context,
39 fd_set *pending_desc, int *nfds,
40 struct timeval *tv, unsigned int flags);
41 int val_async_cancel(val_context_t *context,
43 val_async_status *as,
44 unsigned int flags);
45 int val_async_cancel_all(val_context_t *context,
47 unsigned int flags);
48
50 The asynchronous DNSSEC validator API allows an application to submit
51 multiple requests, which can be processed in parallel. In most cases,
52 this will result in validation completing much sooner than a series of
53 synchronous requests.
54 The ctx parameter in the various functions below specifies the
56 validation context, which can be set to NULL for default values (see
57 libval(3) and dnsval.conf for more details on validation contexts and
58 alidation policy).
59 The val_async_submit() function submits a request for asynchronous
61 processing of DNS queries for the data associated with the given domain
62 name, class and type. The async_status object uniquely identifies a
63 particular request and provides a handle for future operations on that
64 asynchronous request, including cancelling it prior to lookup
65 completion.
66 The flags parameter affects when and how often the callback is called.
68 The following flags are defined.
69 VAL_AS_IGNORE_CACHE
71 Don't use any internal cache for answers to this query.
72 VAL_AS_NO_NEW_QUERIES
74 Don't send any new queries. Answers will be returned from the
75 internal cache.
76 VAL_AS_NO_ANSWERS
78 Caller doesn't care about the answer results. This can be used for
79 priming the cache.
80 VAL_AS_NO_CALLBACKS
82 Don't call any callbacks.
83 VAL_AS_NO_CANCEL_CALLBACKS
85 Call callbacks with results, but don't call any callbacks when the
86 request is canceled.
87 VAL_AS_INTERIM_CALLBACKS
89 Call the callback function with interim results. If this flag is
90 not specified, the callback function will only be called when all
91 validation results are ready.
92 When results from the asynchronous call become available, the callback
94 function (if non-NULL) will be called with the cb_data value,
95 originally supplied to the val_async_submit() call, as one of its
96 arguments. The results from the lookup are returned in cb_data, which
97 is a pointer to the val_cb_params_t structure shown below.
98 typedef struct val_cb_params_s {
100 val_status_t val_status;
101 char *name;
102 int class_h;
103 int type_h;
104 int retval;
105 struct val_result_chain *results;
106 struct val_answer_chain *answers;
107 } val_cb_params_t;
108 The val_cb_params_t structure contains the orginal query parameters in
110 name, class_h and type_h respectively, the return value for the lookup
111 operation in retval, pointers to the results and answers chains (see
112 libval(3) for more details), and the final validation status of the
113 lookup operation in val_status. The application must release the
114 memory associated with results and answers using the
115 val_free_result_chain() and val_free_answer_chain() respectively (see
116 libval(3) for more details).
117 On completion of the asynchronous lookup operation, an event code is
119 returned in event. The following event types are defined:
120 VAL_AS_EVENT_COMPLETED
122 The request was completed.
123 VAL_AS_EVENT_INTERIM
125 The request is still being processed, but some interim results are
126 available.
127 VAL_AS_EVENT_CANCELED
129 The request was canceled. The val_status, results and answers
130 members of the callback parameter structure are undefined.
131 The val_async_select_info() function examines all outstanding
133 asynchronous requests for the given context and sets the appropriate
134 file descriptors, timeout value and maximum file descriptor value in
135 preparation for a call to select(3).
136 The file descriptor for each socket awating a response is set in the
138 fds parameter and max_fd is set to the highest file descriptor number
139 of any pending asynchronous request unless that value is less than the
140 current vaule of max_fd, in which case it is left unchanged. The
141 timeout field is set to the lowest timeout value of any pending
142 asynchronous query timeout which is less than the current value in this
143 field by the application.
144 After the application calls select(3), it must also call
146 val_async_check_wait() with the fd_set and the number of ready file
147 descriptors, ndfs, returned by select(). The val_async_check_wait()
148 function handles timeouts or processes DNS responses to outstanding
149 queries. It also call callbacks for completed requests.
150 val_async_check_wait() provides two modes of operation. The first is
152 for use with an application that has its own select() loop. The
153 applications sets its own file descriptors, calls
154 val_async_select_info() to set file descriptors for pending queries and
155 calls select(). The fds and nfds parameters from select are passed in
156 to val_async_check_wait and the timeout value is ignored. If responses
157 for a file descriptor are processed, the the appropriate file
158 descriptor in fds is cleared and nfds is decremented.
159 In the second mode of operation, the application can set fds and nfds
161 to NULL specify a value for timeout. Here, val_async_select_info() and
162 select() are called internally and any responses received before the
163 timeout value expires are processed.
164 The val_async_cancel() function can be used to cancel the asynchronous
166 request identified by its handle as, while val_async_cancel_all() can
167 be used to cancel all asynchronous requests associated with a given
168 context. The following flag may be set for the cancellation request.
169 VAL_AS_CANCEL_NO_CALLBACKS
171 Do not call completed or cancelled callbacks.
172
174 The val_async_submit() function returns VAL_NO_ERROR on success and one
175 of VAL_RESOURCE_UNAVAILABLE, VAL_BAD_ARGUMENT or VAL_INTERNAL_ERROR on
176 failure.
177 val_async_select_info() returns VAL_NO_ERROR on success and
179 VAL_BAD_ARGUMENT if an illegal argument was passed to the function.
180 val_async_check_wait() returns 0 when no pending requests are found and
182 a positive integer when requests are still pending. A value less than
183 zero on error.
184 val_async_cancel() and val_async_cancel_all() return VAL_NO_ERROR on
186 success.
187
189 Copyright 2004-2013 SPARTA, Inc. All rights reserved. See the COPYING
190 file included with the DNSSEC-Tools package for details.
191
193 Robert Story
194
196 libval(3)
197 draft-hayatnagarkar-dnsext-validator-api
199 http://www.dnssec-tools.org
201perl v5.12.4 2013-03-11 libval_async(3)