libval_async

libval_async(3)               Programmer's Manual              libval_async(3)



NAME
       val_async_submit() - submits a request for asynchronous processing of
       DNS queries.

       val_async_select_info() - set the appropriate file descriptors for
       outstanding asynchronous requests.

       val_async_check_wait() - handle timeouts or processes DNS responses to
       outstanding queries.

       val_async_cancel() - cancel an asynchronous query request.

       val_async_cancel_all() - cancel all asynchronous queries for a given
       context.

SYNOPSIS
       #include <validator/validator.h>

       typedef int (*val_async_event_cb)(val_async_status *async_status,
                           int event, val_context_t *context,
                           void *cb_data, val_cb_params_t *cbp);

       int val_async_submit(val_context_t *context,
                           const char * name, int class,
                           int type, unsigned int flags,
                           val_async_event_cb callback, void *cb_data,
                           val_async_status **async_status);

       int val_async_select_info(val_context_t *context,
                           fd_set *fds,
                           int *num_fds,
                           struct timeval *timeout);

       int val_async_check_wait(val_context_t *context,
                           fd_set *pending_desc, int *nfds,
                           struct timeval *tv, unsigned int flags);

       int val_async_cancel(val_context_t *context,
                           val_async_status *as,
                           unsigned int flags);

       int val_async_cancel_all(val_context_t *context,
                           unsigned int flags);

DESCRIPTION
       The asynchronous DNSSEC validator API allows an application to submit
       multiple requests, which can be processed in parallel. In most cases,
       this will result in validation completing much sooner than a series of
       synchronous requests.

       The ctx parameter in the various functions below specifies the
       validation context, which can be set to NULL for default values (see
       libval(3) and dnsval.conf for more details on validation contexts and
       alidation policy).

       The val_async_submit() function submits a request for asynchronous
       processing of DNS queries for the data associated with the given domain
       name, class and type.  The async_status object uniquely identifies a
       particular request and provides a handle for future operations on that
       asynchronous request, including cancelling it prior to lookup
       completion.

       The flags parameter affects when and how often the callback is called.
       The following flags are defined.

       VAL_AS_IGNORE_CACHE
           Don't use any internal cache for answers to this query.

       VAL_AS_NO_NEW_QUERIES
           Don't send any new queries. Answers will be returned from the
           internal cache.

       VAL_AS_NO_ANSWERS
           Caller doesn't care about the answer results.  This can be used for
           priming the cache.

       VAL_AS_NO_CALLBACKS
           Don't call any callbacks.

       VAL_AS_NO_CANCEL_CALLBACKS
           Call callbacks with results, but don't call any callbacks when the
           request is canceled.

       VAL_AS_INTERIM_CALLBACKS
           Call the callback function with interim results. If this flag is
           not specified, the callback function will only be called when all
           validation results are ready.

       When results from the asynchronous call become available, the callback
       function (if non-NULL) will be called with the cb_data value,
       originally supplied to the val_async_submit() call, as one of its
       arguments.  The results from the lookup are returned in cb_data, which
       is a pointer to the val_cb_params_t structure shown below.

           typedef struct val_cb_params_s {
               val_status_t             val_status;
               char                    *name;
               int                      class_h;
               int                      type_h;
               int                      retval;
               struct val_result_chain *results;
               struct val_answer_chain *answers;
           } val_cb_params_t;

       The val_cb_params_t structure contains the orginal query parameters in
       name, class_h and type_h respectively, the return value for the lookup
       operation in retval, pointers to the results and answers chains (see
       libval(3) for more details), and the final validation status of the
       lookup operation in val_status.  The application must release the
       memory associated with results and answers using the
       val_free_result_chain() and val_free_answer_chain() respectively (see
       libval(3) for more details).

       On completion of the asynchronous lookup operation, an event code is
       returned in event.  The following event types are defined:

       VAL_AS_EVENT_COMPLETED
           The request was completed.

       VAL_AS_EVENT_INTERIM
           The request is still being processed, but some interim results are
           available.

       VAL_AS_EVENT_CANCELED
           The request was canceled. The val_status, results and answers
           members of the callback parameter structure are undefined.

       The val_async_select_info() function examines all outstanding
       asynchronous requests for the given context and sets the appropriate
       file descriptors, timeout value and maximum file descriptor value in
       preparation for a call to select(3).

       The file descriptor for each socket awating a response is set in the
       fds parameter and max_fd is set to the highest file descriptor number
       of any pending asynchronous request unless that value is less than the
       current vaule of max_fd, in which case it is left unchanged. The
       timeout field is set to the lowest timeout value of any pending
       asynchronous query timeout which is less than the current value in this
       field by the application.

       After the application calls select(3), it must also call
       val_async_check_wait() with the fd_set and the number of ready file
       descriptors, ndfs, returned by select(). The val_async_check_wait()
       function handles timeouts or processes DNS responses to outstanding
       queries.  It also call callbacks for completed requests.

       val_async_check_wait() provides two modes of operation.  The first is
       for use with an application that has its own select() loop.  The
       applications sets its own file descriptors, calls
       val_async_select_info() to set file descriptors for pending queries and
       calls select(). The fds and nfds parameters from select are passed in
       to val_async_check_wait and the timeout value is ignored.  If responses
       for a file descriptor are processed, the the appropriate file
       descriptor in fds is cleared and nfds is decremented.

       In the second mode of operation, the application can set fds and nfds
       to NULL specify a value for timeout. Here, val_async_select_info() and
       select() are called internally and any responses received before the
       timeout value expires are processed.

       The val_async_cancel() function can be used to cancel the asynchronous
       request identified by its handle as, while val_async_cancel_all() can
       be used to cancel all asynchronous requests associated with a given
       context. The following flag may be set for the cancellation request.

       VAL_AS_CANCEL_NO_CALLBACKS
           Do not call completed or cancelled callbacks.

RETURN VALUES
       The val_async_submit() function returns VAL_NO_ERROR on success and one
       of VAL_RESOURCE_UNAVAILABLE, VAL_BAD_ARGUMENT or VAL_INTERNAL_ERROR on
       failure.

       val_async_select_info() returns VAL_NO_ERROR on success and
       VAL_BAD_ARGUMENT if an illegal argument was passed to the function.

       val_async_check_wait() returns 0 when no pending requests are found and
       a positive integer when requests are still pending.  A value less than
       zero on error.

       val_async_cancel() and val_async_cancel_all() return VAL_NO_ERROR on
       success.

COPYRIGHT
       Copyright 2004-2013 SPARTA, Inc.  All rights reserved.  See the COPYING
       file included with the DNSSEC-Tools package for details.

AUTHORS
       Robert Story

SEE ALSO
       libval(3)

       draft-hayatnagarkar-dnsext-validator-api

       http://www.dnssec-tools.org



perl v5.12.4                      2013-03-11                   libval_async(3)