QDns Class Reference
[network module]

Detailed Description

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.

QDns 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 is not straightforward to use (although it is much simpler than the native APIs); QSocket provides much easier to use TCP connection facilities. The aim of QDns 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() and setRecordType()), the corresponding get functions, an isWorking() function to determine whether QDns is working or reading, a resultsReady() signal and query functions for the result.

There is one query function for each RecordType, namely addresses(), mailServers(), servers(), hostNames() and texts(). 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) and qualifiedNames() returns a list of the fully qualified names label() maps to.

See also QSocket and Input/Output and Networking.

Member Type Documentation

QDns::RecordType

This enum type defines the record types QDns 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:

• QDns::None - No information. This exists only so that QDns can have a default.
• QDns::A - IPv4 addresses. By far the most common type.
• QDns::Aaaa - IPv6 addresses. So far mostly unused.
• QDns::Mx - Mail eXchanger names. Used for mail delivery.
• QDns::Srv - SeRVer names. Generic record type for finding servers. So far mostly unused.
• QDns::Cname - Canonical names. Maps from nicknames to the true name (the canonical name) for a host.
• QDns::Ptr - name PoinTeRs. Maps from IPv4 or IPv6 addresses to hostnames.
• QDns::Txt - arbitrary TeXT for domains.

We expect that some support for the RFC-2535 extensions will be added in future versions.

Member Function Documentation

QDns::QDns ()

QDns::QDns ( const QString & label, RecordType rr = A )

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

rr defaults to A, IPv4 addresses.

QDns::QDns ( const QHostAddress & address, RecordType rr = Ptr )

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

rr defaults to Ptr, that maps addresses to hostnames.

QDns::~QDns () [virtual]

QValueList<QHostAddress> QDns::addresses () const

As a special case, if label() 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.

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

QString QDns::canonicalName () const

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 for QDns is "trolltech.com", then the canonical name for all of "lillian", "l", "lillian.troll.no." and "l.trolltech.com" is "lillian.troll.no.".

QStringList QDns::hostNames () const

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 QDns::isWorking () const

QDns emits the resultsReady() signal when the status changes to FALSE.

Example: network/mail/smtp.cpp.

QString QDns::label () const

Returns the domain name for which this object returns information.

See also setLabel().

QValueList<MailServer> QDns::mailServers () const

• QString QDns::MailServer::name
• Q_UINT16 QDns::MailServer::priority

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

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

Example: network/mail/smtp.cpp.

QStringList QDns::qualifiedNames () const

Returns a list of the fully qualified names label() 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 QDns::recordType () const

Returns the record type of this DNS query object.

See also setRecordType() and RecordType.

void QDns::resultsReady () [signal]

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

Example: network/mail/smtp.cpp.

QValueList<Server> QDns::servers () const

• QString QDns::Server::name
• Q_UINT16 QDns::Server::priority
• Q_UINT16 QDns::Server::weight
• Q_UINT16 QDns::Server::port

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

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

void QDns::setLabel ( const QString & label ) [virtual]

This does not change the recordType(), but its isWorking() 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 signal resultsReady() is emitted.

void QDns::setLabel ( const QHostAddress & address ) [virtual]

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

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

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

See also RecordType.

QStringList QDns::texts () const

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;
    }
    

This file is part of the Qt toolkit. Copyright © 1995-2003 Trolltech. All Rights Reserved.