Legacy Document

Inside Macintosh: Networking With Open Transport / Part 2 - Open Transport Reference

Chapter 29 - TCP/IP Services Reference / Functions

Retrieving DNS Query Information /

OTInetQuery

Executes a generic DNS query.

C INTERFACE

OSStatus OTInetQuery(InetSvcRef ref,
                     char* name, 
                     UInt16 qClass, 
                     UInt16 qType, 
                     char* buf, 
                     size_t buflen, 
                     void** argv,
                     size_t argvlen,
                     OTFlags flags);

C++ INTERFACE

OSStatus TInternetServices::Query(char* name,
                     UInt16 qClass, 
                     UInt16 qType,
                     char* buf, 
                     size_t buflen, 
                     void** argv, 
                     size_t argvlen,
                     OTFlags flags)

PARAMETERS

ref

The internet services reference you obtained when you opened the TCP/IP service provider.

name

A pointer to the fully qualified domain name or IP address for which you are issuing the query.

qClass

The numeric value for the DNS resource record class, such as Inet or Hesiod. 255 is a wildcard.

qType

The numeric value for the DNS resource record type, such as CNAME and PTR,. 255 is a wildcard.

buf

A pointer to the buffer in which to store one or more DNS query information structures (DNSQueryInfo). Open Transport fits as many complete structures into the buffer as it can; incomplete structures are not returned.

buflen

The size (in bytes) of the buffer.

argv

A pointer to an empty pointer array that Open Transport uses to return a set of pointers to the individual DNS query information structures returned. This parameter is optional, specify nil if you don't want to use this array.

argvlen

The length of the argv buffer.

flags

Reserved. Set to 0.

function result

A result code. See Appendix B for more information.

DISCUSSION

The OTInetQuery function allows you to use the Domain Name Resolver (DNR) for generic domain name service (DNS) queries. You can ask query any type and class, and Open Transport returns as many responses as it can fit in the buffer you provide.

The argv and argvlen parameters are optional. If provided, Open Transport uses the argv buffer to return pointers to the locations of individual DNSQueryInfo structures written into the buffer pointed to by the buf parameter. For example, if you set argvlen to 5 and your query receives three answers, the value of argv[0] would be a pointer to the first answer in the answer buffer, the value of argv[1] would be a pointer to the second answer, the value of argv[2] would be a pointer to the third answer, and the rest of the argv array would have null pointers.

If you call OTInetQuery asynchronously, Open Transport calls your notifier with a T_DNRQUERYCOMPLETE event when the call completes. When using asynchronous mode, you must not modify the buf or argv structures before the function completes.

The OTInetQuery function works with both known and unknown query classes and types. Open Transport expands compressed answers for the Inet query class and known query types before returning them into the answer buffer. Answers that are resource records of unknown class and type are put into the answer buffer unparsed because Open Transport assumes that DNS compression is not used.

Open Transport provides simplified functions for the most commonly made queries such as name-to-address (A), address-to-name (PTR), system CPU and OS (HINFO), and mail exchange (MX) queries. These are the OTInetStringToAddress, OTInetAddressToName, OTInetSysInfo, and OTInetMailExchange functions, respectively. The information obtained is the same using either type of function, although in some cases the simplified functions limit the maximum number of answers that can be returned.

Currently, only answers of type PTR, A, and CNAME are cached by OpenTransport. OpenTransport does not use this cached information to resolve address-to-name translations because doing so would defeat server load balancing schemes.