liboop: oop_adns_submit(), oop_adns_cancel()

## oop_adns_submit(), oop_adns_cancel()

    #include <oop.h>
    #include <adns.h>
    #include <oop-adns.h>

    /* Callback function prototype. */
    typedef void *oop_adns_call(oop_adapter_adns *adapter,adns_answer *answer,void *data);

    /* Submit an asynchronous DNS query. */
    oop_adns_query *oop_adns_submit(
            oop_adapter_adns *adapter,
            const char *owner,adns_rrtype type,adns_queryflags flags,
            oop_adns_call *call,void *user);

    /* Cancel a running query. */
    void oop_adns_cancel(oop_adns_query *query);

### Arguments.

oop_adapter_adns *adns
  The adns adapter to use for the query.

adns_answer *answer
  The answer to the query (status and RR data). Refer to the adns documentation for details.

const char *owner
  The DNS domain name to query.

adns_rrtype type
  The DNS Resource Record type to query. Refer to the adns documentation for the list of valid RR types.

adns_queryflags flags
  Flags for the DNS query. Refer to the adns documentation for details.

oop_call_fd *call
  The callback function (event sink) to use for reporting query succcess or failure.

void *user
  User data passed through to the callback function.

oop_adns_query *query
  The query to cancel.

### Description.

oop_adns_submit
  This function begins a DNS query using an adns adapter. Most of the parameters are passed directly to adns. The query will be processed asynchronously using the event source specified when the adapter was created; when it completes (successfully or not), the specified callback will be invoked.

  On malloc failure or catastrophic system error, NULL will be returned. (Simple name resolution errors, such as not finding the name, do not result in a NULL query; instead, the callback is invoked with an error status.)

  The returned pointer is valid (and may be used to cancel the query) until either the query is cancelled or the callback is invoked (the query completes).

oop_adns_cancel
  Stop processing a query started with oop_adns_submit (above). This must be called with a non-NULL pointer returned from oop_adns_submit before the query has completed (and the callback function invoked). Any query may only be cancelled once. All resources associated with the query will be released.

oop_adns_call
  Called when the query completes, successfully or not. Performs a user-specific action with the results of the query. All resources associated with the query will be released before the function is called, except for the answer structure itself. (The user is responsible for freeing the answer structure, as per the conventions established by adns. Note that adns does not use oop_alloc!) Should return OOP_CONTINUE if the event loop should continue operating; any other value (including OOP_HALT) will cause termination of the event loop.

liboop reference