QKnxNetIpServerDiscoveryAgent Class

The QKnxNetIpServerDiscoveryAgent class discovers KNXnet/IP servers by sending a search request in the network that the client is connected to. More...

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

Public Types

enum DiscoveryMode { CoreV1, CoreV2 }
flags DiscoveryModes
enum class Error { None, Network, NotIPv4, Timeout, Unknown }
flags InterfaceTypes
enum class ResponseType { Unicast, Multicast }
enum class State { NotRunning, Starting, Running, Stopping }

Public Functions

QKnxNetIpServerDiscoveryAgent(const QHostAddress &localAddress, quint16 port, QObject *parent = nullptr)
QKnxNetIpServerDiscoveryAgent(const QHostAddress &localAddress, QObject *parent = nullptr)
QKnxNetIpServerDiscoveryAgent(QObject *parent = nullptr)
virtual ~QKnxNetIpServerDiscoveryAgent() override
QVector<QKnxNetIpServerInfo> discoveredServers() const
QKnxNetIpServerDiscoveryAgent::DiscoveryModes discoveryMode() const
QKnxNetIpServerDiscoveryAgent::Error error() const
QString errorString() const
QVector<QKnxNetIpSrp> extendedSearchParameters() const
QHostAddress localAddress() const
quint16 localPort() const
quint8 multicastTtl() const
bool natAware() const
QKnxNetIpServerDiscoveryAgent::ResponseType responseType() const
int searchFrequency() const
void setDiscoveryMode(QKnxNetIpServerDiscoveryAgent::DiscoveryModes mode)
void setExtendedSearchParameters(const QVector<QKnxNetIpSrp> &srps)
void setLocalAddress(const QHostAddress &address)
void setLocalPort(quint16 port)
void setMulticastTtl(quint8 ttl)
void setNatAware(bool useNat)
void setResponseType(QKnxNetIpServerDiscoveryAgent::ResponseType type)
void setSearchFrequency(int timesPerMinute)
void setTimeout(int msec)
QKnxNetIpServerDiscoveryAgent::State state() const
int timeout() const

Public Slots

void start(QKnxNetIpServerDiscoveryAgent::InterfaceTypes types)
void start(const QVector<QHostAddress> &addresses)
void start(int timeout)
void start()
void stop()

Signals

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

Detailed Description

The agent may be set up with the Unicast response type to receive the answers from the different KNXnet/IP servers directly in a point-to-point manner. Typically, it should use the Multicast response type to ensure reception from KNXnet/IP servers that are on a different subnetwork.

Here is an example on how to use this discovery agent:

QKnxNetIpServerDiscoveryAgent agent;
QHostAddress clientLocalAddress = ...
agent.setLocalAddress(clientLocalAddress);
agent.start();

The discovery agent further provides the option to send extended search requests as specified by the KNX application note AN184. This allows the discovery client to include zero or more search request parameter (SRP) blocks to transfer additional information regarding the search. This can be used for example to restrict the set of devices that are expected to respond or to influence the type of device information blocks (DIBs) which the client is interested in.

Note: A combination of both discovery modes is permitted.

Here is an example on how to use this discovery agent with extended search features to indicate that the KNXnet/IP client is interested only in the response from the KNXnet/IP server with the given MAC address:

QHostAddress clientLocalAddress = ...
auto builder = QKnxNetIpSrpProxy::macAddressBuilder();

QKnxNetIpServerDiscoveryAgent agent(clientLocalAddress);
agent.setDiscoveryMode(QKnxNetIpServerDiscoveryAgent::DiscoveryMode::CoreV2);
agent.setExtendedSearchParameters({
    builder.setMac(QKnxByteArray::fromHex("bcaec56690f9")).create(),
    builder.setMac(QKnxByteArray::fromHex("4ccc6ae40000")).create()
});
agent.start();

To retrieve the list of discovered servers:

auto servers = agent.discoveredServers();

See also Qt KNXnet/IP Connection Classes.

Member Type Documentation

enum QKnxNetIpServerDiscoveryAgent::DiscoveryMode
flags QKnxNetIpServerDiscoveryAgent::DiscoveryModes

This enum type holds the mode that the agent is set up with to send search request messages. A combination of both values is permitted.

ConstantValueDescription
QKnxNetIpServerDiscoveryAgent::CoreV10x01The server uses search request frames as specified in KNXnet/IP Core Version 1 to discover KNXnet/IP devices.
QKnxNetIpServerDiscoveryAgent::CoreV20x02The server uses extended search request frames as specified in KNXnet/IP Core Version 2 to discover KNXnet/IP devices.

This enum was introduced or modified in Qt 5.12.

The DiscoveryModes type is a typedef for QFlags<DiscoveryMode>. It stores an OR combination of DiscoveryMode values.

enum class QKnxNetIpServerDiscoveryAgent::Error

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

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

enum class QKnxNetIpServerDiscoveryAgent::ResponseType

This enum type holds the response type that the agent is set up with to receive search response messages.

ConstantValueDescription
QKnxNetIpServerDiscoveryAgent::ResponseType::Unicast0x00Receive responses in a point-to-point manner.
QKnxNetIpServerDiscoveryAgent::ResponseType::Multicast0x01Collect responses from multicast messages.

enum class QKnxNetIpServerDiscoveryAgent::State

This enum value holds the state of the discovery agent.

ConstantValueDescription
QKnxNetIpServerDiscoveryAgent::State::NotRunning0The discovery agent is not running.
QKnxNetIpServerDiscoveryAgent::State::Starting1The discovery agent is starting up.
QKnxNetIpServerDiscoveryAgent::State::Running2The discovery agent is running.
QKnxNetIpServerDiscoveryAgent::State::Stopping3The discovery agent is stopping.

Member Function Documentation

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

Creates a KNXnet/IP server discovery 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, discovery will fail.

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

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

QKnxNetIpServerDiscoveryAgent::QKnxNetIpServerDiscoveryAgent(QObject *parent = nullptr)

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

[signal] void QKnxNetIpServerDiscoveryAgent::deviceDiscovered(QKnxNetIpServerInfo server)

This signal is emitted when the server server is discovered.

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

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

[signal] void QKnxNetIpServerDiscoveryAgent::finished()

This signal is emitted when the discovery agent has finished discovering servers.

[slot] void QKnxNetIpServerDiscoveryAgent::start(QKnxNetIpServerDiscoveryAgent::InterfaceTypes types)

Starts a server discovery agent with the network interfaces specified by the list of interface types types.

Note: Does not emit the errorOccurred signal.

[slot] void QKnxNetIpServerDiscoveryAgent::start(const QVector<QHostAddress> &addresses)

Starts a server discovery agent with the network interfaces specified by the list of local host addresses.

Note: Does not emit the errorOccurred signal.

[slot] void QKnxNetIpServerDiscoveryAgent::start(int timeout)

Starts a server discovery agent with the timeout timeout.

See also setTimeout() and timeout().

[slot] void QKnxNetIpServerDiscoveryAgent::start()

Starts a server discovery agent.

[signal] void QKnxNetIpServerDiscoveryAgent::started()

This signal is emitted when the discovery agent starts discovering servers.

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

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

[slot] void QKnxNetIpServerDiscoveryAgent::stop()

Stops a server discovery agent.

[override virtual] QKnxNetIpServerDiscoveryAgent::~QKnxNetIpServerDiscoveryAgent()

Deletes a KNXnet/IP server discovery agent.

QVector<QKnxNetIpServerInfo> QKnxNetIpServerDiscoveryAgent::discoveredServers() const

Returns a list of servers that were discovered.

QKnxNetIpServerDiscoveryAgent::DiscoveryModes QKnxNetIpServerDiscoveryAgent::discoveryMode() const

Returns the search mode used to discover a KNXnet/IP server on the network and by default returns QKnxNetIpServerDiscoveryAgent::CoreV1.

This function was introduced in Qt 5.12.

See also setDiscoveryMode().

QKnxNetIpServerDiscoveryAgent::Error QKnxNetIpServerDiscoveryAgent::error() const

Returns the type of an error that occurred when discovering servers.

QString QKnxNetIpServerDiscoveryAgent::errorString() const

Returns a human-readable string that describes an error.

QVector<QKnxNetIpSrp> QKnxNetIpServerDiscoveryAgent::extendedSearchParameters() const

Returns the search request parameter (SRP) objects used in an extended search request.

This function was introduced in Qt 5.12.

See also setExtendedSearchParameters().

QHostAddress QKnxNetIpServerDiscoveryAgent::localAddress() const

Returns the host address of a discovery agent.

See also setLocalAddress().

quint16 QKnxNetIpServerDiscoveryAgent::localPort() const

Returns the port number used by a discovery agent.

See also setLocalPort().

quint8 QKnxNetIpServerDiscoveryAgent::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 QKnxNetIpServerDiscoveryAgent::natAware() const

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

See also setNatAware().

QKnxNetIpServerDiscoveryAgent::ResponseType QKnxNetIpServerDiscoveryAgent::responseType() const

Returns the response type of search response messages.

See also setResponseType().

int QKnxNetIpServerDiscoveryAgent::searchFrequency() const

Returns the frequency at which the discovery agent sends search request messages. The default value is 0.

See also setSearchFrequency.

void QKnxNetIpServerDiscoveryAgent::setDiscoveryMode(QKnxNetIpServerDiscoveryAgent::DiscoveryModes mode)

Sets the search mode used to discover a KNXnet/IP server on the network to mode. The function supports QKnxNetIpServerDiscoveryAgent::CoreV1, QKnxNetIpServerDiscoveryAgent::CoreV2, or a combination of both.

This function was introduced in Qt 5.12.

See also discoveryMode().

void QKnxNetIpServerDiscoveryAgent::setExtendedSearchParameters(const QVector<QKnxNetIpSrp> &srps)

Sets the extended search request parameter (SRP) objects to srps.

The discovery agent may include zero or more SRP objects to transfer additional information regarding the search (for example to restrict the set of KNXnet/IP servers that are expected to respond).

This function was introduced in Qt 5.12.

See also extendedSearchParameters(), QKnxNetIpSrpProxy::MacAddress, QKnxNetIpSrpProxy::ProgrammingMode, QKnxNetIpSrpProxy::SupportedFamily, and QKnxNetIpSrpProxy::RequestDibs.

void QKnxNetIpServerDiscoveryAgent::setLocalAddress(const QHostAddress &address)

Sets the host address of a discovery agent to address. To unset the local address use QHostAddress::Null.

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

See also localAddress().

void QKnxNetIpServerDiscoveryAgent::setLocalPort(quint16 port)

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

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

See also localPort().

void QKnxNetIpServerDiscoveryAgent::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 QKnxNetIpServerDiscoveryAgent::setNatAware(bool useNat)

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

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

See also natAware().

void QKnxNetIpServerDiscoveryAgent::setResponseType(QKnxNetIpServerDiscoveryAgent::ResponseType type)

Sets the response type of search response messages to type.

See also responseType().

void QKnxNetIpServerDiscoveryAgent::setSearchFrequency(int timesPerMinute)

Sets the frequency at which the discovery agent sends search request messages to timesPerMinute. The default value is 0.

See also timeout, setTimeout, and searchFrequency.

void QKnxNetIpServerDiscoveryAgent::setTimeout(int msec)

Sets the timeout for the discovery 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, searchFrequency, and setSearchFrequency.

QKnxNetIpServerDiscoveryAgent::State QKnxNetIpServerDiscoveryAgent::state() const

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

int QKnxNetIpServerDiscoveryAgent::timeout() const

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

See also setTimeout.

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