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 Error { None, Network, NotIPv4, Unknown }
enum ResponseType { Unicast, Multicast }
enum State { NotRunning, Starting, Running, Stopping }

Public Functions

QKnxNetIpServerDiscoveryAgent(QObject *parent = nullptr)
QKnxNetIpServerDiscoveryAgent(const QHostAddress &localAddress, QObject *parent = nullptr)
QKnxNetIpServerDiscoveryAgent(const QHostAddress &localAddress, quint16 port, QObject *parent = nullptr)
virtual ~QKnxNetIpServerDiscoveryAgent()
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
  • 34 public functions inherited from QObject

Public Slots

void start()
void start(int timeout)
void stop()
  • 1 public slot inherited from QObject

Signals

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

Additional Inherited Members

  • 1 property inherited from QObject
  • 1 public variable inherited from QObject
  • 10 static public members inherited from QObject
  • 9 protected functions inherited from QObject
  • 2 protected variables inherited from QObject

Detailed Description

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

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 QKnxNetIpServerDiscoveryAgent::Error

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

ConstantValueDescription
QKnxNetIpServerDiscoveryAgent::None0No errors occurred.
QKnxNetIpServerDiscoveryAgent::Network1A network error occurred.
QKnxNetIpServerDiscoveryAgent::NotIPv42The network protocol used is not IPv4.
QKnxNetIpServerDiscoveryAgent::Unknown0x80An unknown error occurred.

enum QKnxNetIpServerDiscoveryAgent::ResponseType

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

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

enum QKnxNetIpServerDiscoveryAgent::State

This enum value holds the state of the discovery agent.

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

Member Function Documentation

QKnxNetIpServerDiscoveryAgent::QKnxNetIpServerDiscoveryAgent(QObject *parent = nullptr)

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

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

[virtual] QKnxNetIpServerDiscoveryAgent::~QKnxNetIpServerDiscoveryAgent()

Deletes a KNXnet/IP server discovery agent.

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

This signal is emitted when the server server is discovered.

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.

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

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

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

[signal] void QKnxNetIpServerDiscoveryAgent::finished()

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

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.

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.

[slot] void QKnxNetIpServerDiscoveryAgent::start()

Starts a server discovery agent.

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

Starts a server discovery agent with the timeout timeout.

See also setTimeout() and timeout().

[signal] void QKnxNetIpServerDiscoveryAgent::started()

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

QKnxNetIpServerDiscoveryAgent::State QKnxNetIpServerDiscoveryAgent::state() const

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

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

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.

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