[getdns-api] Fwd: getdns API version published

[Murray S. Kucherawy]

Hi there,

A few long overdue observations about the API document.  I found these
during WG sessions in Berlin.  Nothing major, just a few things that
probably need to be clarified or tweaked.

-MSK


1.1 getdns_general()

The "name" argument can be an IP address.  That's passed as a string (e.g.,
"127.0.0.1\0"), correct?  I assume so since it's a (const char *) and not a
(void *) and there's no address family argument, but I ask because you name
PTR, which one might take to mean the caller should in fact pass
"1.0.0.127.in-addr.arpa\0" or similar.

1.3 getdns_hostname()

In the dictionary through which the address family is defined, the family
is apparently presented as a string, either "IPv4\0" or "IPv6\0".  Are
these case-sensitive?  Why not just refer to a char that contains '4' or
'6', or the values for AF_INET or AF_INET6?

I think both of these might benefit from having a PTR lookup example in
Section 8.

1.7 Canceling a callback

In fact this really means the caller is canceling a previously initiated
request, correct?  The callback may or may not already have been executed;
this call guarantees that if it hasn't been hit, it will be hit now, which
satisfies the post-condition that it's always called once.  But the other
main effect here is that the DNS request, if it has not already completed,
is canceled.  I guess the reason this tripped me up is that I would expect
this to be expressed as a cancellation of the DNS query, not of the
callback.

3. Extensions

What's supposed to be in the empty bullet before 3.1?

4.1 Structure of DNS replies_tree

The API will convert an A record (for example) into an "ipv4_address" (as a
32-bit quantity) but also leave the raw form there.  However, for names
(e.g., the name in the question section), only the raw form is there.  That
seems like it would be a common conversion nearly all callers will need to
do.  Why force them to call the conversion, rather than just provide a
decoded form in the replies_tree?

6.4 example

I haven't gone through all the example code yet, but I did find this:

this_ret = getdns_list_get_length(just_the_addresses_ptr,
num_addresses_ptr);  // Ignore any error

It looks like the second argument there should be prefixed by "&".  I think
I saw at least one other place where this needed to be done as well.  I
will make a full pass through the code examples, and I'll do my best not to
put it off until I'm sitting in a WG in Vancouver to do it.

8.3 Contexts for Basic Resolution

I think getdns_context_set_dns_transport() is missing another value, which
is something to start with UDP, but on fallback to TCP, bolt the connection
up.  It's there for the TCP-only case, but not for the upgrade case.  It
might be better to use a bitmask here, e.g., UDP | TCP |
PERSISTENT_CONNECTIONS.

In terms of timeouts, does that mean the way to have different timeouts for
different queries is to establish different contexts, each with its own
timeout?

If you limit the count of outstanding queries, what blocks, exactly?  I
have a couple of ideas about how this could work and I can't tell what's
meant here:  (a) A new request will get queued, and actually sent when some
other stuff has resolved; (b) The API call that enqueues a new request will
itself block until something else resolves.

More later (or not),

-MSK
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.vpnc.org/pipermail/getdns-api/attachments/20130819/21853604/attachment.html>