<div dir="ltr"><div>Hi there,<br><br>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.<br>
<br></div>-MSK<br><div><div><br><br><div class="gmail_quote">1.1 getdns_general()<br><div dir="ltr"><div><div><div><div><div><div><div><div><div><div><div><div><div><div><div><div><div>
<br></div>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.<br>
<br></div>1.3 getdns_hostname()<br><br></div>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?<br>
<br></div><div>I think both of these might benefit from having a PTR lookup example in Section 8.<br></div><div><br></div>1.7 Canceling a callback<br><br></div>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.<br>
<br></div>3. Extensions<br></div><div><br></div>What's supposed to be in the empty bullet before 3.1?<br><br></div>4.1 Structure of DNS replies_tree<br><br></div>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?<br>
<br></div>6.4 example<br><br></div>I haven't gone through all the example code yet, but I did find this:<br><br><pre><span>this_ret</span> <span>=</span> <span>getdns_list_get_length</span><span>(</span><span>just_the_addresses_ptr</span><span>,</span> <span>num_addresses_ptr</span><span>);</span> <span>// Ignore any error<br>
<br></span></pre></div>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.<br>
<br></div>8.3 Contexts for Basic Resolution<br><br></div>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.<br>
<br></div>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?<br><br></div>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.<br>
<br></div><div>More later (or not),<br><br></div>-MSK<br></div></div></div></div></div>