QKnxNetIpServerDescriptionAgent Class

The QKnxNetIpServerDescriptionAgent class establishes a point-to-point connection with a KNXnet/IP server and requests its description. More...

Header: #include <QKnxNetIpServerDescriptionAgent>
qmake: QT += knx
Inherits: QObject

Public Types

enum Error { None, Network, NotIPv4, Timeout, Unknown }
enum State { NotRunning, Starting, Running, Stopping }

Public Functions

QKnxNetIpServerDescriptionAgent(const QHostAddress &localAddress, quint16 port, QObject *parent = nullptr)
QKnxNetIpServerDescriptionAgent(const QHostAddress &localAddress, QObject *parent = nullptr)
QKnxNetIpServerDescriptionAgent(QObject *parent = nullptr)
virtual ~QKnxNetIpServerDescriptionAgent()
QKnxNetIpServerDescriptionAgent::Error error() const
QString errorString() const
QHostAddress localAddress() const
quint16 localPort() const
quint8 multicastTtl() const
bool natAware() const
QKnxNetIpServerInfo serverDescription() const
void setLocalAddress(const QHostAddress &address)
void setLocalPort(quint16 port)
void setMulticastTtl(quint8 ttl)
void setNatAware(bool useNat)
void setTimeout(int msec)
QKnxNetIpServerDescriptionAgent::State state() const
int timeout() const

Public Slots

void start(const QHostAddress &address, quint16 port)
void start(const QKnxNetIpServerInfo &server)
void start(const QKnxNetIpHpai &server)
void stop()


void descriptionReceived(QKnxNetIpServerInfo server)
void errorOccurred(QKnxNetIpServerDescriptionAgent::Error error, QString errorString)
void finished()
void started()
void stateChanged(QKnxNetIpServerDescriptionAgent::State state)

Detailed Description

First, the QKnxNetIpServerDiscoveryAgent class is used to search the network for available KNXnet/IP devices. After successful discovery of such a device, the server needs to be chosen to fetch the description. This can be been done as illustrated by the following code snippet:

QKnxNetIpServerDescriptionAgent descriptionAgent;
QHostAddress clientLocalAddress = ...

auto server = discoveryAgent.discoveredServers()[0]; // for example

When the description is received from the server, the descriptionReceived() signal is emitted. The description received through this point-to-point connection may be more complete than the one sent during discovery.

See also Qt KNXnet/IP Connection Classes.

Member Type Documentation

enum QKnxNetIpServerDescriptionAgent::Error

This enum value holds the type of an error that occurred.

QKnxNetIpServerDescriptionAgent::None0No errors occurred.
QKnxNetIpServerDescriptionAgent::Network1A network error occurred.
QKnxNetIpServerDescriptionAgent::NotIPv42The network protocol used is not IPv4.
QKnxNetIpServerDescriptionAgent::Timeout3A timeout occurred while waiting for the description response.
QKnxNetIpServerDescriptionAgent::Unknown0x80An unknown error occurred.

enum QKnxNetIpServerDescriptionAgent::State

This enum value holds the state of the description agent.

QKnxNetIpServerDescriptionAgent::NotRunning0The description agent is not running.
QKnxNetIpServerDescriptionAgent::Starting1The description agent is starting up.
QKnxNetIpServerDescriptionAgent::Running2The description agent is running.
QKnxNetIpServerDescriptionAgent::Stopping3The description agent is stopping.

Member Function Documentation

QKnxNetIpServerDescriptionAgent::QKnxNetIpServerDescriptionAgent(const QHostAddress &localAddress, quint16 port, QObject *parent = nullptr)

Creates a KNXnet/IP server description agent with the host address localAddress, the port number port, and the parent parent.

Note: If the port number is already bound by a different process, description requests will fail.

QKnxNetIpServerDescriptionAgent::QKnxNetIpServerDescriptionAgent(const QHostAddress &localAddress, QObject *parent = nullptr)

Creates a KNXnet/IP server description agent with the host address localAddress and the parent parent.

QKnxNetIpServerDescriptionAgent::QKnxNetIpServerDescriptionAgent(QObject *parent = nullptr)

Creates a KNXnet/IP server description agent with the parent parent.

[signal] void QKnxNetIpServerDescriptionAgent::descriptionReceived(QKnxNetIpServerInfo server)

This signal is emitted when the description of server is received.

[signal] void QKnxNetIpServerDescriptionAgent::errorOccurred(QKnxNetIpServerDescriptionAgent::Error error, QString errorString)

This signal is emitted when the error error with the message errorString occurs.

[signal] void QKnxNetIpServerDescriptionAgent::finished()

This signal is emitted when the description agent has finished.

[slot] void QKnxNetIpServerDescriptionAgent::start(const QHostAddress &address, quint16 port)

Starts the server description agent at the host address address and port number port.

[slot] void QKnxNetIpServerDescriptionAgent::start(const QKnxNetIpServerInfo &server)

Starts the server description agent server.

[slot] void QKnxNetIpServerDescriptionAgent::start(const QKnxNetIpHpai &server)

Starts the server description agent server.

[signal] void QKnxNetIpServerDescriptionAgent::started()

This signal is emitted when the description agent starts.

[signal] void QKnxNetIpServerDescriptionAgent::stateChanged(QKnxNetIpServerDescriptionAgent::State state)

This signal is emitted when the state of the description agent changes to state.

[slot] void QKnxNetIpServerDescriptionAgent::stop()

Stops a server description agent.

[virtual] QKnxNetIpServerDescriptionAgent::~QKnxNetIpServerDescriptionAgent()

Deletes a KNXnet/IP server description agent.

QKnxNetIpServerDescriptionAgent::Error QKnxNetIpServerDescriptionAgent::error() const

Returns the type of an error that occurred when receiving the server description.

QString QKnxNetIpServerDescriptionAgent::errorString() const

Returns a human-readable string that describes an error.

QHostAddress QKnxNetIpServerDescriptionAgent::localAddress() const

Returns the host address of a description agent.

See also setLocalAddress().

quint16 QKnxNetIpServerDescriptionAgent::localPort() const

Returns the port number used by a description agent.

See also setLocalPort().

quint8 QKnxNetIpServerDescriptionAgent::multicastTtl() const

Returns the time to live (TTL) used for multicast search response messages. TTL is the maximum number of IP routers that may route the message. Each IP router that the message passes decrements the TTL by one. When the TTL has reached zero, the message is discarded.

See also setMulticastTtl().

bool QKnxNetIpServerDescriptionAgent::natAware() const

Returns true if the server description agent uses network address translation (NAT).

See also setNatAware().

QKnxNetIpServerInfo QKnxNetIpServerDescriptionAgent::serverDescription() const

Returns a description of a server.

void QKnxNetIpServerDescriptionAgent::setLocalAddress(const QHostAddress &address)

Sets the host address of a description agent to address.

Note: If the address changes during a description request, the new address will not be used until the next run.

See also localAddress().

void QKnxNetIpServerDescriptionAgent::setLocalPort(quint16 port)

Sets the port number used by a description agent to port.

Note: If the port changes during a description request, the new port will not be used until the next run.

See also localPort().

void QKnxNetIpServerDescriptionAgent::setMulticastTtl(quint8 ttl)

Sets the TTL used for multicasting to ttl. The value 1 means that the message does not leave the local network.

See also multicastTtl().

void QKnxNetIpServerDescriptionAgent::setNatAware(bool useNat)

Sets whether the server description agent is using NAT to useNat.

Note: If the setting changes during a description request, it will not be used until the next run.

See also natAware().

void QKnxNetIpServerDescriptionAgent::setTimeout(int msec)

Sets the timeout for the description agent to msec. If msec is -1, the agent will not timeout and has to be terminated by calling the stop function.

See also timeout.

QKnxNetIpServerDescriptionAgent::State QKnxNetIpServerDescriptionAgent::state() const

Returns the state of a KNXnet/IP server description agent.

int QKnxNetIpServerDescriptionAgent::timeout() const

Returns the timeout value used by the description agent to wait for incoming search response messages. The default value is 3000 milliseconds.

See also setTimeout.

© 2019 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.