[getdns-api] getdns API version published

[Murray S. Kucherawy]

On Tue, Aug 20, 2013 at 11:36 AM, Paul Hoffman <paul.hoffman at vpnc.org>wrote:

> > 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.
>
> The text says "This can also be an IPv4 or IPv6 address for request types
> that take addresses instead of domain names, such as PTR." I thought that
> was clear but, if not, wording proposals are appreciated.
>

Right, my point is that PTR doesn't exactly take an IP address as-is.  I
may just be thinking at a different level than the document is talking.
Perhaps:

"This can also be an IPv4 or IPv6 address for request types that act on
addresses instead of domain names, such as PTR; the API will reformat the
query accordingly."


>
> > 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".
>
> Nope, these are bindata, not strings. At the top of section 2, it says
> "bindata is a struct to hold binary data. It is defined as { size_t size;
> uint8_t *binary_stuff; }."
>

Ah, right.


>
> > Are these case-sensitive?
>
> Yes.
>

It should say that.


>
> > Why not just refer to a char that contains '4' or '6', or the values for
> AF_INET or AF_INET6?
>
> That could have worked as well, but is not what was chosen.
>

Fair enough, just wondering.  Five bytes (or four) is easier to get wrong
than one.


>
> > I think both of these might benefit from having a PTR lookup example in
> Section 8.
>
> Sure, I can add an example like that.
>
> > 1.7 Canceling a callback
> >
> > In fact this really means the caller is canceling a previously initiated
> request, correct?
>
> Not necessarily.
>
> > 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.
>
> The application using the API shouldn't care whether or not the DNS
> request went out or not, just that the callback is cancelled. For example,
> assume that the DNS request returned but the cancellation comes in while
> doing DNSSEC validation: the application still wants the callback cancelled.
>

OK.  Just not a paradigm I'd seen before, I guess.

Thanks for the followup.

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