Contents

• Public Types
• Public Functions
• Signals
• Detailed Description

Detailed Description

TheQ3Dns class provides asynchronous DNS lookups.

Both Windows and Unix provide synchronous DNS lookups; Windows provides some asynchronous support too. At the time of writing neither operating system provides asynchronous support for anything other than hostname-to-address mapping.

Q3Dns rectifies this shortcoming, by providing asynchronous caching lookups for the record types that we expect modern GUI applications to need in the near future.

The class isnot straightforward to use (although it is much simpler than the native APIs);Q3Socket provides much easier to use TCP connection facilities. The aim ofQ3Dns is to provide a correct and small API to the DNS and nothing more. (We use "correctness" to mean that the DNS information is correctly cached, and correctly timed out.)

The API comprises a constructor, functions to set the DNS node (the domain in DNS terminology) and record type (setLabel() andsetRecordType()), the corresponding get functions, anisWorking() function to determine whetherQ3Dns is working or reading, aresultsReady() signal and query functions for the result.

There is one query function for eachRecordType, namelyaddresses(),mailServers(),servers(),hostNames() andtexts(). There are also two generic query functions:canonicalName() returns the name you'll presumably end up using (the exact meaning of this depends on the record type) andqualifiedNames() returns a list of the fully qualified nameslabel() maps to.

Member Type Documentation

enum Q3Dns::RecordType

This enum type defines the record typesQ3Dns can handle. The DNS provides many more; these are the ones we've judged to be in current use, useful for GUI programs and important enough to support right away:

We expect that some support for theRFC 2535 extensions will be added in future versions.

Member Function Documentation

Q3Dns::Q3Dns()

Constructs a DNS query object with invalid settings for both the label and the search type.

Q3Dns::Q3Dns(constQString & label,RecordType rr = A)

Constructs a DNS query object that will return record typerr information aboutlabel.

The DNS lookup is started the next time the application enters the event loop. When the result is found the signalresultsReady() is emitted.

rr defaults toA, IPv4 addresses.

Q3Dns::Q3Dns(constQHostAddress & address,RecordType rr = Ptr)

Constructs a DNS query object that will return record typerr information about host addressaddress. The label is set to the IN-ADDR.ARPA domain name. This is useful in combination with thePtr record type (e.g. if you want to look up a hostname for a given address).

The DNS lookup is started the next time the application enters the event loop. When the result is found the signalresultsReady() is emitted.

rr defaults toPtr, that maps addresses to hostnames.

[virtual]Q3Dns::~Q3Dns()

Destroys the DNS query object and frees its allocated resources.

Q3ValueList<QHostAddress> Q3Dns::addresses() const

Returns a list of the addresses for this name if thisQ3Dns object has arecordType() ofQ3Dns::A orQ3Dns::Aaaa and the answer is available; otherwise returns an empty list.

As a special case, iflabel() is a valid numeric IP address, this function returns that address.

Note that if you want to iterate over the list, you should iterate over a copy, e.g.

Q3ValueList<QHostAddress> list= myDns.addresses();Q3ValueList<QHostAddress>::Iterator it= list.begin();while( it!= list.end() ) {    myProcessing(*it );++it;}

QString Q3Dns::canonicalName() const

Returns the canonical name for this DNS node. (This works regardless of whatrecordType() is set to.)

If the canonical name isn't known, this function returns a null string.

The canonical name of a DNS node is its full name, or the full name of the target of its CNAME. For example, if l.trolltech.com is a CNAME to lillian.troll.no, and the search path forQ3Dns is "trolltech.com", then the canonical name for all of "lillian", "l", "lillian.troll.no." and "l.trolltech.com" is "lillian.troll.no.".

QStringList Q3Dns::hostNames() const

Returns a list of host names if the record type isPtr.

Note that if you want to iterate over the list, you should iterate over a copy, e.g.

QStringList list= myDns.hostNames();QStringList::Iterator it= list.begin();while( it!= list.end() ) {    myProcessing(*it );++it;}

bool Q3Dns::isWorking() const

Returns true ifQ3Dns is doing a lookup for this object (i.e. if it does not already have the necessary information); otherwise returns false.

Q3Dns emits theresultsReady() signal when the status changes to false.

QString Q3Dns::label() const

Returns the domain name for which this object returns information.

See alsosetLabel().

Q3ValueList<MailServer> Q3Dns::mailServers() const

Returns a list of mail servers if the record type isMx. The classQ3Dns::MailServer contains the following public variables:

• QStringQ3Dns::MailServer::name
• Q_UINT16Q3Dns::MailServer::priority

Note that if you want to iterate over the list, you should iterate over a copy, e.g.

Q3ValueList<Q3Dns::MailServer> list= myDns.mailServers();Q3ValueList<Q3Dns::MailServer>::Iterator it= list.begin();while( it!= list.end() ) {    myProcessing(*it );++it;}

QStringList Q3Dns::qualifiedNames() const

Returns a list of the fully qualified nameslabel() maps to.

Note that if you want to iterate over the list, you should iterate over a copy, e.g.

QStringList list= myDns.qualifiedNames();QStringList::Iterator it= list.begin();while( it!= list.end() ) {    myProcessing(*it );++it;}

RecordType Q3Dns::recordType() const

Returns the record type of this DNS query object.

See alsosetRecordType() andRecordType.

[signal]void Q3Dns::resultsReady()

This signal is emitted when results are available for one of thequalifiedNames().

Q3ValueList<Server> Q3Dns::servers() const

Returns a list of servers if the record type isSrv. The classQ3Dns::Server contains the following public variables:

• QStringQ3Dns::Server::name
• Q_UINT16Q3Dns::Server::priority
• Q_UINT16Q3Dns::Server::weight
• Q_UINT16Q3Dns::Server::port

Note that if you want to iterate over the list, you should iterate over a copy, e.g.

Q3ValueList<Q3Dns::Server> list= myDns.servers();Q3ValueList<Q3Dns::Server>::Iterator it= list.begin();while( it!= list.end() ) {    myProcessing(*it );++it;}

[virtual]void Q3Dns::setLabel(constQString & label)

Sets this DNS query object to query for information aboutlabel.

This does not change therecordType(), but itsisWorking() status will probably change as a result.

The DNS lookup is started the next time the application enters the event loop. When the result is found the signalresultsReady() is emitted.

See alsolabel().

[virtual]void Q3Dns::setLabel(constQHostAddress & address)

This is an overloaded function.

Sets this DNS query object to query for information about the host addressaddress. The label is set to the IN-ADDR.ARPA domain name. This is useful in combination with thePtr record type (e.g. if you want to look up a hostname for a given address).

[virtual]void Q3Dns::setRecordType(RecordType rr = A)

Sets this object to query for record typerr records.

The DNS lookup is started the next time the application enters the event loop. When the result is found the signalresultsReady() is emitted.

See alsorecordType() andRecordType.

QStringList Q3Dns::texts() const

Returns a list of texts if the record type isTxt.

Note that if you want to iterate over the list, you should iterate over a copy, e.g.

QStringList list= myDns.texts();QStringList::Iterator it= list.begin();while( it!= list.end() ) {    myProcessing(*it );++it;}