QHostInfo Class Reference

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

#include <qhostinfo.h>

Collaboration diagram for QHostInfo:

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

Static Public Member Functions
static int	lookupHost (const QString &name, const QObject *receiver, const char *member)
	Looks up the IP address(es) associated with host name name, and returns an ID for the lookup.
static void	abortHostLookup (int lookupId)
	Aborts the host lookup with the ID id, as returned by lookupHost().
static QHostInfo	fromName (const QString &name)
	Looks up the IP address(es) for the given host name.
static QString	localHostName ()
	Returns this machine's host name, if one is configured.
static QString	localDomainName ()
	Returns the DNS domain of this machine.
template<typename Functor >
static int	lookupHost (const QString &name, const typename QtPrivate::ContextTypeForFunctor< Functor >::ContextType *receiver, Functor &&func)
template<typename Functor >
static int	lookupHost (const QString &name, Functor &&slot)

Friends
QHostInfo Q_NETWORK_EXPORT	qt_qhostinfo_lookup (const QString &name, QObject *receiver, const char *member, bool *valid, int *id)

Detailed Description

The QHostInfo class provides static functions for host name lookups.

\reentrant \inmodule QtNetwork

QHostInfo finds 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-project.org
QHostInfo::lookupHost("qt-project.org", this, &MyWidget::printResults);
 
// To find the host name for 4.2.2.1
QHostInfo::lookupHost("4.2.2.1", this, &MyWidget::printResults);

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 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.

QHostInfo uses the mechanisms provided by the operating system to perform the lookup. As per \l {RFC 6724} there is no guarantee that all IP addresses registered for a domain or host will be returned.

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, {RFC 3492}, {RFC 6724}

Definition at line 18 of file qhostinfo.h.

Member Enumeration Documentation

HostInfoError

enum QHostInfo::HostInfoError

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

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

See also

error(), setError()

Enumerator
NoError
HostNotFound
UnknownError

Definition at line 22 of file qhostinfo.h.

Constructor & Destructor Documentation

QHostInfo() [1/3]

QHostInfo::QHostInfo ( int id = -1 )

explicit

Constructs an empty host info object with lookup ID id.

See also

lookupId()

Definition at line 530 of file qhostinfo.cpp.

References d.

QHostInfo() [2/3]

QHostInfo::QHostInfo

(

const QHostInfo &

d

)

Constructs a copy of other.

Definition at line 540 of file qhostinfo.cpp.

QHostInfo() [3/3]

QHostInfo::QHostInfo ( QHostInfo && other )

inlinenoexcept

Move-constructs a new QHostInfo from other.

Note

The moved-from object other is placed in a partially-formed state, in which the only valid operations are destruction and assignment of a new value.

Since

5.14

Definition at line 30 of file qhostinfo.h.

~QHostInfo()

QHostInfo::~QHostInfo

(

)

Destroys the host info object.

Definition at line 574 of file qhostinfo.cpp.

Member Function Documentation

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 320 of file qhostinfo.cpp.

Referenced by QAbstractSocket::connectToHost(), QAbstractSocket::disconnectFromHost(), and QAbstractSocket::waitForConnected().

Here is the caller graph for this function:

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 589 of file qhostinfo.cpp.

References d.

Referenced by QHttpNetworkConnectionPrivate::_q_hostLookupFinished(), if(), and setAddresses().

Here is the caller graph for this function:

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 634 of file qhostinfo.cpp.

References d.

Referenced by QHostInfoCache::put(), and setError().

Here is the caller graph for this function:

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 679 of file qhostinfo.cpp.

References d.

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 338 of file qhostinfo.cpp.

References QNetworkAccessManager::cache(), QHostInfoAgent::fromName(), QHostInfoAgent::lookup(), manager, and qDebug.

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

Here is the call graph for this function:

Here is the caller graph for this function:

hostName()

QString QHostInfo::hostName

(

)

const

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

See also

localHostName()

Definition at line 611 of file qhostinfo.cpp.

References d.

Referenced by setHostName().

Here is the caller graph for this function:

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 96 of file qhostinfo_unix.cpp.

References _PATH_RESCONF, QUrl::fromAce(), QString::indexOf(), line, maybeRefreshResolver(), QString::mid(), pos, qScopeGuard(), QIODeviceBase::ReadOnly, QFile::setFileName(), QString::startsWith(), state, QString::trimmed(), and QByteArrayView::trimmed().

Here is the call graph for this function:

localHostName()

QString QHostInfo::localHostName ( )

static

Returns this machine's host name, if one is configured.

Note that hostnames are not guaranteed to be globally unique, especially if they were configured automatically.

This function does not guarantee the returned host name is a Fully Qualified Domain Name (FQDN). For that, use fromName() to resolve the returned name to an FQDN.

This function returns the same as QSysInfo::machineHostName().

See also

hostName(), localDomainName()

Definition at line 712 of file qhostinfo.cpp.

References QSysInfo::machineHostName().

Here is the call graph for this function:

lookupHost() [1/3]

int QHostInfo::lookupHost ( const QString & name, const 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:

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;
    }
 
    const auto addresses = host.addresses();
    for (const QHostAddress &address : 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:

Note

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

In Qt versions prior to 6.7, this function took receiver as (non-const) {QObject*}.

See also

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

Definition at line 229 of file qhostinfo.cpp.

References qWarning.

lookupHost() [2/3]

template<typename Functor >

static int QHostInfo::lookupHost ( const QString & name, const typename QtPrivate::ContextTypeForFunctor< Functor >::ContextType * receiver, Functor && func )

inlinestatic

Definition at line 68 of file qhostinfo.h.

References void.

lookupHost() [3/3]

template<typename Functor >

template< typename Functor > int QHostInfo::lookupHost ( const QString & name, Functor && functor )

inlinestatic

Since

5.9

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

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 functor is called with a QHostInfo argument. The QHostInfo object can then be inspected to get the results of the lookup.

The functor will be run in the thread that makes the call to lookupHost; that thread must have a running Qt event loop.

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 83 of file qhostinfo.h.

lookupId()

int QHostInfo::lookupId

(

)

const

Returns the ID of this lookup.

See also

setLookupId(), abortHostLookup(), hostName()

Definition at line 656 of file qhostinfo.cpp.

References d.

operator=() [1/2]

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 561 of file qhostinfo.cpp.

References other(), and Q_ASSERT.

Here is the call graph for this function:

operator=() [2/2]

QHostInfo & QHostInfo::operator= ( QHostInfo && other )

inlinenoexcept

Move-assigns other to this QHostInfo instance.

Note

The moved-from object other is placed in a partially-formed state, in which the only valid operations are destruction and assignment of a new value.

Since

5.10

Definition at line 32 of file qhostinfo.h.

References other(), and swap().

Here is the call graph for this function:

setAddresses()

void QHostInfo::setAddresses

(

const QList< QHostAddress > &

addresses

)

Sets the list of addresses in this QHostInfo to addresses.

See also

addresses()

Definition at line 600 of file qhostinfo.cpp.

References addresses(), and d.

Referenced by QAbstractSocket::connectToHost(), and QAbstractSocket::waitForConnected().

Here is the call graph for this function:

Here is the caller graph for this function:

setError()

void QHostInfo::setError

(

HostInfoError

error

)

Sets the error type of this QHostInfo to error.

See also

error(), errorString()

Definition at line 645 of file qhostinfo.cpp.

References d, and error().

Here is the call graph for this function:

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 691 of file qhostinfo.cpp.

References d, and str.

setHostName()

void QHostInfo::setHostName

(

const QString &

hostName

)

Sets the host name of this QHostInfo to hostName.

See also

hostName()

Definition at line 622 of file qhostinfo.cpp.

References d, and hostName().

Here is the call graph for this function:

setLookupId()

void QHostInfo::setLookupId

(

int

id

)

Sets the ID of this lookup to id.

See also

lookupId(), lookupHost()

Definition at line 667 of file qhostinfo.cpp.

References d.

swap()

void QHostInfo::swap ( QHostInfo & other )

inlinenoexcept

Swaps host-info other with this host-info.

This operation is very fast and never fails.

Since

5.10

Definition at line 35 of file qhostinfo.h.

References other(), and qt_ptr_swap().

Here is the call graph for this function:

Friends And Related Symbol Documentation

qt_qhostinfo_lookup

QHostInfo Q_NETWORK_EXPORT qt_qhostinfo_lookup ( const QString & name, QObject * receiver, const char * member, bool * valid, int * id )

friend

Definition at line 1060 of file qhostinfo.cpp.

---

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

• qtbase/src/network/kernel/qhostinfo.h (674dfdf226542cc33129899df9833847cb6f4629)
• qtbase/src/network/kernel/qhostinfo.cpp (4b3d6be5f5a175a4c66b527eb2df49d62dc30056)
• qtbase/src/network/kernel/qhostinfo_unix.cpp (cf066f7d0309819bbe1a16a41457c6e4dd11b534)
• qtbase/src/network/kernel/qnetworkinterface_win.cpp (05fc3aef53348fb58be6308076e000825b704e58)