QHostInfo Class Reference

The QHostInfo class provides static functions for host name lookups. More...

#include <qhostinfo.h>

Public Types
enum	HostInfoError { NoError, HostNotFound, UnknownError }
	This enum describes the various errors that can occur when trying to resolve a host name. More...

Public Functions
QList< QHostAddress >	addresses () const
	Returns the list of IP addresses associated with hostName(). More...
HostInfoError	error () const
	Returns the type of error that occurred if the host name lookup failed; otherwise returns NoError. More...
QString	errorString () const
	If the lookup failed, this function returns a human readable description of the error; otherwise "Unknown error" is returned. More...
QString	hostName () const
	Returns the name of the host whose IP addresses were looked up. More...
int	lookupId () const
	Returns the ID of this lookup. More...
QHostInfo &	operator= (const QHostInfo &d)
	Assigns the data of the other object to this host info object, and returns a reference to it. More...
	QHostInfo (int lookupId=-1)
	Constructs an empty host info object with lookup ID id. More...
	QHostInfo (const QHostInfo &d)
	Constructs a copy of other. More...
void	setAddresses (const QList< QHostAddress > &addresses)
	Sets the list of addresses in this QHostInfo to addresses. More...
void	setError (HostInfoError error)
	Sets the error type of this QHostInfo to error. More...
void	setErrorString (const QString &errorString)
	Sets the human readable description of the error that occurred to str if the lookup failed. More...
void	setHostName (const QString &name)
	Sets the host name of this QHostInfo to hostName. More...
void	setLookupId (int id)
	Sets the ID of this lookup to id. More...
	~QHostInfo ()
	Destroys the host info object. More...

Static Public Functions
static void	abortHostLookup (int lookupId)
	Aborts the host lookup with the ID id, as returned by lookupHost(). More...
static QHostInfo	fromName (const QString &name)
	Looks up the IP address(es) for the given host name. More...
static QString	localDomainName ()
	Returns the DNS domain of this machine. More...
static QString	localHostName ()
	Returns the host name of this machine. More...
static int	lookupHost (const QString &name, QObject *receiver, const char *member)
	Looks up the IP address(es) associated with host name name, and returns an ID for the lookup. More...

Properties
QScopedPointer< QHostInfoPrivate >	d

Detailed Description

The QHostInfo class provides static functions for host name lookups.

Note

This class or function is reentrant.

Attention

Module: QtNetwork

QHostInfo uses the lookup mechanisms provided by the operating system to find the IP address(es) associated with a host name, or the host name associated with an IP address. The class provides two static convenience functions: one that works asynchronously and emits a signal once the host is found, and one that blocks and returns a QHostInfo object.

To look up a host's IP addresses asynchronously, call lookupHost(), which takes the host name or IP address, a receiver object, and a slot signature as arguments and returns an ID. You can abort the lookup by calling abortHostLookup() with the lookup ID.

Example:

// To find the IP address of qt.nokia.com
QHostInfo::lookupHost("qt.nokia.com",
                      this, SLOT(printResults(QHostInfo)));

// To find the host name for 4.2.2.1
QHostInfo::lookupHost("4.2.2.1",
                      this, SLOT(printResults(QHostInfo)));

The slot is invoked when the results are ready. The results are stored in a QHostInfo object. Call addresses() to get the list of IP addresses for the host, and hostName() to get the host name that was looked up.

If the lookup failed, error() returns the type of error that occurred. errorString() gives a human-readable description of the lookup error.

If you want a blocking lookup, use the QHostInfo::fromName() function:

QHostInfo info = QHostInfo::fromName("qt.nokia.com");

QHostInfo supports Internationalized Domain Names (IDNs) through the IDNA and Punycode standards.

To retrieve the name of the local host, use the static QHostInfo::localHostName() function.

Note

Since Qt 4.6.1 QHostInfo is using multiple threads for DNS lookup instead of one dedicated DNS thread. This improves performance, but also changes the order of signal emissions when using lookupHost() compared to previous versions of Qt.

Since Qt 4.6.3 QHostInfo is using a small internal 60 second DNS cache for performance improvements.

See also

QAbstractSocket, {http://www.rfc-editor.org/rfc/rfc3492.txt}{RFC 3492}

Definition at line 58 of file qhostinfo.h.

Enumerations

HostInfoError

enum QHostInfo::HostInfoError

This enum describes the various errors that can occur when trying to resolve a host name.

• NoError The lookup was successful.
• HostNotFound No IP addresses were found for the host.
• UnknownError An unknown error occurred.

See also

error(), setError()

Enumerator
NoError
HostNotFound
UnknownError

Definition at line 61 of file qhostinfo.h.

                       {
        NoError,
        HostNotFound,
        UnknownError
    };

Constructors and Destructors

QHostInfo() [1/2]

QHostInfo::QHostInfo

(

int

id = -1

)

Constructs an empty host info object with lookup ID id.

See also

lookupId()

Definition at line 331 of file qhostinfo.cpp.

    : d(new QHostInfoPrivate)
{
    d->lookupId = id;
}

QHostInfo() [2/2]

QHostInfo::QHostInfo

(

const QHostInfo &

d

)

Constructs a copy of other.

Definition at line 340 of file qhostinfo.cpp.

    : d(new QHostInfoPrivate(*other.d.data()))
{
}

~QHostInfo()

QHostInfo::~QHostInfo

(

)

Destroys the host info object.

Definition at line 358 of file qhostinfo.cpp.

{
}

Functions

abortHostLookup()

void QHostInfo::abortHostLookup ( int  id )

static

Aborts the host lookup with the ID id, as returned by lookupHost().

See also

lookupHost(), lookupId()

Definition at line 255 of file qhostinfo.cpp.

Referenced by QAbstractSocket::connectToHostImplementation(), QAbstractSocket::disconnectFromHostImplementation(), and QAbstractSocket::waitForConnected().

{
    theHostInfoLookupManager()->abortLookup(id);
}

addresses()

QList< QHostAddress > QHostInfo::addresses

(

)

const

Returns the list of IP addresses associated with hostName().

This list may be empty.

Example:

QHostInfo info;
...
if (!info.addresses().isEmpty()) {
    QHostAddress address = info.addresses().first();
    // use the first IP address
}

See also

hostName(), error()

Definition at line 372 of file qhostinfo.cpp.

Referenced by QAbstractSocketPrivate::_q_startConnecting(), QHostInfoAgent::fromName(), setAddresses(), and translateWSAError().

{
    return d->addrs;
}

error()

QHostInfo::HostInfoError QHostInfo::error

(

)

const

Returns the type of error that occurred if the host name lookup failed; otherwise returns NoError.

See also

setError(), errorString()

Definition at line 413 of file qhostinfo.cpp.

Referenced by QHostInfoAgent::fromName(), QHostInfoCache::put(), setError(), and translateWSAError().

{
    return d->err;
}

errorString()

QString QHostInfo::errorString

(

)

const

If the lookup failed, this function returns a human readable description of the error; otherwise "Unknown error" is returned.

See also

setErrorString(), error()

Definition at line 454 of file qhostinfo.cpp.

Referenced by QHostInfoAgent::fromName(), and translateWSAError().

{
    return d->errorStr;
}

fromName()

QHostInfo QHostInfo::fromName ( const QString &  name )

static

Looks up the IP address(es) for the given host name.

The function blocks during the lookup which means that execution of the program is suspended until the results of the lookup are ready. Returns the result of the lookup in a QHostInfo object.

If you pass a literal IP address to name instead of a host name, QHostInfo will search for the domain name for the IP (i.e., QHostInfo will perform a reverse lookup). On success, the returned QHostInfo will contain both the resolved domain name and IP addresses for the host name.

See also

lookupHost()

Definition at line 273 of file qhostinfo.cpp.

Referenced by QSslSocketPrivate::_q_connectedSlot(), and QAbstractSocket::waitForConnected().

{
#if defined QHOSTINFO_DEBUG
    qDebug("QHostInfo::fromName(\"%s\")",name.toLatin1().constData());
#endif

    QHostInfo hostInfo = QHostInfoAgent::fromName(name);
    QAbstractHostInfoLookupManager* manager = theHostInfoLookupManager();
    manager->cache.put(name, hostInfo);
    return hostInfo;
}

hostName()

QString QHostInfo::hostName

(

)

const

Returns the name of the host whose IP addresses were looked up.

See also

localHostName()

Definition at line 392 of file qhostinfo.cpp.

Referenced by QHostInfoAgent::fromName(), setHostName(), and translateWSAError().

{
    return d->hostName;
}

localDomainName()

QString QHostInfo::localDomainName ( )

static

Returns the DNS domain of this machine.

Note: DNS domains are not related to domain names found in Windows networks.

See also

hostName()

Definition at line 333 of file qhostinfo_unix.cpp.

Referenced by interfaceListing().

{
#if !defined(Q_OS_VXWORKS)
    resolveLibrary();
    if (local_res_ninit) {
        // using thread-safe version
        res_state_ptr state = res_state_ptr(qMalloc(sizeof(*state)));
        Q_CHECK_PTR(state);
        memset(state, 0, sizeof(*state));
        local_res_ninit(state);
        QString domainName = QUrl::fromAce(state->defdname);
        if (domainName.isEmpty())
            domainName = QUrl::fromAce(state->dnsrch[0]);
        local_res_nclose(state);
        qFree(state);

        return domainName;
    }

    if (local_res_init && local_res) {
        // using thread-unsafe version

#if defined(QT_NO_GETADDRINFO)
        // We have to call res_init to be sure that _res was initialized
        // So, for systems without getaddrinfo (which is thread-safe), we lock the mutex too
        QMutexLocker locker(::getHostByNameMutex());
#endif
        local_res_init();
        QString domainName = QUrl::fromAce(local_res->defdname);
        if (domainName.isEmpty())
            domainName = QUrl::fromAce(local_res->dnsrch[0]);
        return domainName;
    }
#endif
    // nothing worked, try doing it by ourselves:
    QFile resolvconf;
#if defined(_PATH_RESCONF)
    resolvconf.setFileName(QFile::decodeName(_PATH_RESCONF));
#else
    resolvconf.setFileName(QLatin1String("/etc/resolv.conf"));
#endif
    if (!resolvconf.open(QIODevice::ReadOnly))
        return QString();       // failure

    QString domainName;
    while (!resolvconf.atEnd()) {
        QByteArray line = resolvconf.readLine().trimmed();
        if (line.startsWith("domain "))
            return QUrl::fromAce(line.mid(sizeof "domain " - 1).trimmed());

        // in case there's no "domain" line, fall back to the first "search" entry
        if (domainName.isEmpty() && line.startsWith("search ")) {
            QByteArray searchDomain = line.mid(sizeof "search " - 1).trimmed();
            int pos = searchDomain.indexOf(' ');
            if (pos != -1)
                searchDomain.truncate(pos);
            domainName = QUrl::fromAce(searchDomain);
        }
    }

    // return the fallen-back-to searched domain
    return domainName;
}

localHostName()

QString QHostInfo::localHostName ( )

static

Returns the host name of this machine.

See also

hostName()

Definition at line 324 of file qhostinfo_unix.cpp.

Referenced by translateWSAError().

{
    char hostName[512];
    if (gethostname(hostName, sizeof(hostName)) == -1)
        return QString();
    hostName[sizeof(hostName) - 1] = '\0';
    return QString::fromLocal8Bit(hostName);
}

lookupHost()

int QHostInfo::lookupHost ( const QString &  name, QObject *  receiver, const char *  member  )

static

Looks up the IP address(es) associated with host name name, and returns an ID for the lookup.

When the result of the lookup is ready, the slot or signal member in receiver is called with a QHostInfo argument. The QHostInfo object can then be inspected to get the results of the lookup.

The lookup is performed by a single function call, for example:

QHostInfo::lookupHost("www.kde.org",
                      this, SLOT(lookedUp(QHostInfo)));

The implementation of the slot prints basic information about the addresses returned by the lookup, or reports an error if it failed:

void MyWidget::lookedUp(const QHostInfo &host)
{
    if (host.error() != QHostInfo::NoError) {
        qDebug() << "Lookup failed:" << host.errorString();
        return;
    }

    foreach (const QHostAddress &address, host.addresses())
        qDebug() << "Found address:" << address.toString();
}

If you pass a literal IP address to name instead of a host name, QHostInfo will search for the domain name for the IP (i.e., QHostInfo will perform a reverse lookup). On success, the resulting QHostInfo will contain both the resolved domain name and IP addresses for the host name. Example:

QHostInfo::lookupHost("4.2.2.1",
                      this, SLOT(lookedUp(QHostInfo)));

Note

There is no guarantee on the order the signals will be emitted if you start multiple requests with lookupHost().

See also

abortHostLookup(), addresses(), error(), fromName()

Definition at line 156 of file qhostinfo.cpp.

Referenced by qt_qhostinfo_lookup().

{
#if defined QHOSTINFO_DEBUG
    qDebug("QHostInfo::lookupHost(\"%s\", %p, %s)",
           name.toLatin1().constData(), receiver, member ? member + 1 : 0);
#endif

    if (!QAbstractEventDispatcher::instance(QThread::currentThread())) {
        qWarning("QHostInfo::lookupHost() called with no event dispatcher");
        return -1;
    }

    qRegisterMetaType<QHostInfo>("QHostInfo");

    int id = theIdCounter.fetchAndAddRelaxed(1); // generate unique ID

    if (name.isEmpty()) {
        if (!receiver)
            return -1;

        QHostInfo hostInfo(id);
        hostInfo.setError(QHostInfo::HostNotFound);
        hostInfo.setErrorString(QCoreApplication::translate("QHostInfo", "No host name given"));
        QScopedPointer<QHostInfoResult> result(new QHostInfoResult);
        QObject::connect(result.data(), SIGNAL(resultsReady(QHostInfo)),
                         receiver, member, Qt::QueuedConnection);
        result.data()->emitResultsReady(hostInfo);
        return id;
    }

#ifndef Q_OS_SYMBIAN
    QHostInfoLookupManager *manager = theHostInfoLookupManager();

    if (manager) {
        // the application is still alive
        if (manager->cache.isEnabled()) {
            // check cache first
            bool valid = false;
            QHostInfo info = manager->cache.get(name, &valid);
            if (valid) {
                if (!receiver)
                    return -1;

                info.setLookupId(id);
                QHostInfoResult result;
                QObject::connect(&result, SIGNAL(resultsReady(QHostInfo)), receiver, member, Qt::QueuedConnection);
                result.emitResultsReady(info);
                return id;
            }
        }

        // cache is not enabled or it was not in the cache, do normal lookup
        QHostInfoRunnable* runnable = new QHostInfoRunnable(name, id);
        if (receiver)
            QObject::connect(&runnable->resultEmitter, SIGNAL(resultsReady(QHostInfo)), receiver, member, Qt::QueuedConnection);
        manager->scheduleLookup(runnable);
    }
#else
    QSymbianHostInfoLookupManager *manager = theHostInfoLookupManager();

    if (manager) {
        // the application is still alive
        if (manager->cache.isEnabled()) {
            // check cache first
            bool valid = false;
            QHostInfo info = manager->cache.get(name, &valid);
            if (valid) {
                info.setLookupId(id);
                QHostInfoResult result;
                QObject::connect(&result, SIGNAL(resultsReady(QHostInfo)), receiver, member, Qt::QueuedConnection);
                result.emitResultsReady(info);
                return id;
            }
        }

        // cache is not enabled or it was not in the cache, do normal lookup
#ifndef QT_NO_BEARERMANAGEMENT
        QSharedPointer<QNetworkSession> networkSession;
        QVariant v(receiver->property("_q_networksession"));
        if (v.isValid())
            networkSession = qvariant_cast< QSharedPointer<QNetworkSession> >(v);
#endif

        QSymbianHostResolver *symbianResolver = 0;
        QT_TRAP_THROWING(symbianResolver = new QSymbianHostResolver(name, id, networkSession));
        QObject::connect(&symbianResolver->resultEmitter, SIGNAL(resultsReady(QHostInfo)), receiver, member, Qt::QueuedConnection);
        manager->scheduleLookup(symbianResolver);
    }
#endif

    return id;
}

lookupId()

int QHostInfo::lookupId

(

)

const

Returns the ID of this lookup.

See also

setLookupId(), abortHostLookup(), hostName()

Definition at line 433 of file qhostinfo.cpp.

Referenced by QAbstractSocketPrivate::_q_startConnecting().

{
    return d->lookupId;
}

operator=()

QHostInfo & QHostInfo::operator=

(

const QHostInfo &

d

)

Assigns the data of the other object to this host info object, and returns a reference to it.

Definition at line 349 of file qhostinfo.cpp.

{
    *d.data() = *other.d.data();
    return *this;
}

setAddresses()

void QHostInfo::setAddresses

(

const QList< QHostAddress > &

addresses

)

Sets the list of addresses in this QHostInfo to addresses.

See also

addresses()

Definition at line 382 of file qhostinfo.cpp.

Referenced by QAbstractSocket::connectToHostImplementation(), QHostInfoAgent::fromName(), and translateWSAError().

{
    d->addrs = addresses;
}

setError()

void QHostInfo::setError

(

HostInfoError

error

)

Sets the error type of this QHostInfo to error.

See also

error(), errorString()

Definition at line 423 of file qhostinfo.cpp.

Referenced by QHostInfoAgent::fromName(), lookupHost(), and translateWSAError().

{
    d->err = error;
}

setErrorString()

void QHostInfo::setErrorString

(

const QString &

str

)

Sets the human readable description of the error that occurred to str if the lookup failed.

See also

errorString(), setError()

Definition at line 465 of file qhostinfo.cpp.

Referenced by QHostInfoAgent::fromName(), lookupHost(), and translateWSAError().

{
    d->errorStr = str;
}

setHostName()

void QHostInfo::setHostName

(

const QString &

hostName

)

Sets the host name of this QHostInfo to hostName.

See also

hostName()

Definition at line 402 of file qhostinfo.cpp.

Referenced by QHostInfoAgent::fromName(), and translateWSAError().

{
    d->hostName = hostName;
}

setLookupId()

void QHostInfo::setLookupId

(

int

id

)

Sets the ID of this lookup to id.

See also

lookupId(), lookupHost()

Definition at line 443 of file qhostinfo.cpp.

Referenced by lookupHost(), and QHostInfoRunnable::run().

{
    d->lookupId = id;
}

Properties

d

QScopedPointer<QHostInfoPrivate> QHostInfo::d

private

Definition at line 95 of file qhostinfo.h.

Referenced by addresses(), error(), errorString(), hostName(), lookupId(), operator=(), QHostInfo(), setAddresses(), setError(), setErrorString(), setHostName(), and setLookupId().

---

The documentation for this class was generated from the following files:

• /src/network/kernel/qhostinfo.h
• /src/network/kernel/qhostinfo.cpp
• /src/network/kernel/qhostinfo_unix.cpp
• /src/network/kernel/qhostinfo_win.cpp
• /src/network/kernel/qnetworkinterface_win.cpp