Some fixes in QKnxNetIpRouter interface and documentation

1. Improve consistency of the class interface
2. Improve documentation example of signal routingIndicationReceived
3. Remove routing mode assignment in setFilterTable. Let the user
handle the mode by calling setRoutingMode
4. Fixed qdoc issue: qknxnetiprouter.cpp:118: (qdoc) warning: Cannot
find 'QKnxNetIpRouter::FilterTable' specified with '\typedef' in any
header file

Change-Id: Ife5fd6c1c6446b547bacca90c128504223bba631
Reviewed-by: Karsten Heimrich <karsten.heimrich@qt.io>
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>

4 files changed, 52 insertions, 35 deletions

diff --git a/examples/knx/router/main.cpp b/examples/knx/router/main.cpp
index 8c921bb..f9ccc9a 100644
--- a/examples/knx/router/main.cpp
+++ b/examples/knx/router/main.cpp
@@ -126,7 +126,10 @@ void setupRouterCLI(QKnxNetIpRouter &router,
                 .setData(tmp.isEmpty() ? bytes : QKnxByteArray::fromHex(tmp))
                 .setMedium(QKnx::MediumType::NetIP)
                 .createFrame();
-            router.sendRoutingIndication(frame);
+            auto indication = QKnxNetIpRoutingIndicationProxy::builder()
+                              .setCemi(frame)
+                              .create();
+            router.sendRoutingIndication(indication);
         } else if (cliParser.isSet("busy")) {
             auto routingBusyFrame = QKnxNetIpRoutingBusyProxy::builder()
                 .setDeviceState(QKnxNetIp::DeviceState::IpFault)
diff --git a/src/knx/netip/qknxnetiprouter.cpp b/src/knx/netip/qknxnetiprouter.cpp
index 5feb5c4..c27e08c 100644
--- a/src/knx/netip/qknxnetiprouter.cpp
+++ b/src/knx/netip/qknxnetiprouter.cpp
@@ -61,10 +61,11 @@ QT_BEGIN_NAMESPACE
     QKnxNetIpRouter to send and receive KNXnet/IP frames:
 
     \code
-        QKnxNetIpRouter router;
-        router.setInterfaceAffinity(QNetworkInterface::interfaceFromName("eth0"));
-        router.setMulticastAddress(QHostAddress("224.0.23.32"));
-        router.start();
+        QKnxNetIpRouter router1;
+        QKnxNetIpRouter router2;
+        router1.setInterfaceAffinity(QNetworkInterface::interfaceFromName("eth0"));
+        router1.setMulticastAddress(QHostAddress("224.0.23.32"));
+        router1.start();
 
         auto busyWaitTime = ...
         auto busyControlField = ...
@@ -75,15 +76,38 @@ QT_BEGIN_NAMESPACE
             .setRoutingBusyWaitTime(busyWaitTime)
             .setRoutingBusyControl(busyControlField)
             .create();
-        router.sendRoutingBusy(routingBusyFrame);
+        router1.sendRoutingBusy(routingBusyFrame);
 
         // Processing routing indications received
-        QObject::connect(&router,
+        QObject::connect(&router1,
                          &QKnxNetIpRouter::routingIndicationReceived,
-                     [](QKnxNetIpFrame frame) {
+                     [](QKnxNetIpFrame frame,
+                        QKnxNetIpRouter::FilterAction routingAction) {
                 QKnxNetIpRoutingIndicationProxy indication(frame);
                 qInfo().noquote() << "Received routing indication:"
                                   << indication.isValid();
+
+                switch (routingAction) {
+                case QKnxNetIpRouter::FilterAction::RouteDecremented:
+                    auto cemi = indication.cemi();
+                    auto extCtrl = cemi.extendedControlField();
+                    count = extCtrl.hopCount();
+                    // decrement and send to other subnet
+                    extCtrl.setHopCount(--count);
+                    auto newIndication =  QKnxNetIpRoutingIndicationProxy::builder()
+                                            .setCemi(cemi)
+                                            .create();
+                    router2.sendRoutingIndication(newIndication)
+                    // ....
+                case QKnxNetIpRouter::FilterAction::RouteLast:
+                case QKnxNetIpRouter::FilterAction::ForwardLocally:
+                case QKnxNetIpRouter::FilterAction::IgnoreTotally:
+                case QKnxNetIpRouter::FilterAction::IgnoreAcked:
+                //....
+                default:
+                    break;
+                }
+                //....
         });
 
     \endcode
@@ -92,7 +116,7 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
-    \typedef QKnxNetIpRouter::FilterTable
+    \typedef QKnxNetIpRouter::KnxAddressWhitelist
 
     A synonym for QKnxNetIpRouter::QSet<QKnxAddress>, which is the type used
     to store the filter table of the router. The filter table is interpreted
@@ -285,7 +309,6 @@ void QKnxNetIpRouter::setFilterTable(const QKnxNetIpRouter::KnxAddressWhitelist
 {
     Q_D(QKnxNetIpRouter);
     d->m_filterTable = table;
-    d->m_routingMode = RoutingMode::Filter;
 }
 
 /*!
@@ -445,18 +468,6 @@ void QKnxNetIpRouter::sendRoutingIndication(const QKnxNetIpFrame &frame)
 }
 
 /*!
-    Multicasts the routing indication \a linkFrame through the network interface
-    associated with the QKnxNetIpRouter.
- */
-void QKnxNetIpRouter::sendRoutingIndication(const QKnxLinkLayerFrame &linkFrame)
-{
-    auto netIpFrame = QKnxNetIpRoutingIndicationProxy::builder()
-        .setCemi(linkFrame)
-        .create();
-    sendRoutingIndication(netIpFrame);
-}
-
-/*!
     Multicasts the routing busy message containing \a frame through the
     network interface associated with the QKnxNetIpRouter.
 */
@@ -503,29 +514,27 @@ void QKnxNetIpRouter::sendRoutingLostMessage(const QKnxNetIpFrame &frame)
 }
 
 /*!
-    Multicasts the routing system broadcast \a linkFrame through the network
+    Multicasts the routing system broadcast \a frame through the network
     interface associated with the QKnxNetIpRouter.
 */
-void QKnxNetIpRouter::sendRoutingSystemBroadcast(const QKnxLinkLayerFrame &linkFrame)
+void QKnxNetIpRouter::sendRoutingSystemBroadcast(const QKnxNetIpFrame &frame)
 {
     Q_D(QKnxNetIpRouter);
 
-    auto netipFrame = QKnxNetIpRoutingSystemBroadcastProxy::builder()
-        .setCemi(linkFrame)
-        .create();
+    if (d->m_state != QKnxNetIpRouter::State::Routing)
+        return;
 
-    QKnxNetIpRoutingSystemBroadcastProxy proxy(netipFrame);
+    QKnxNetIpRoutingSystemBroadcastProxy proxy(frame);
     if (!proxy.isValid())
         return;
 
-    if (!d->sendFrame(netipFrame)) {
+    if (!d->sendFrame(frame)) {
         d->errorOccurred(QKnxNetIpRouter::Error::KnxRouting, tr("Could not send routing "
             "system broadcast."));
     } else {
-        emit routingSystemBroadcastSent(netipFrame);
+        emit routingSystemBroadcastSent(frame);
     }
 }
-
 /*!
     Signals the QKnxNetIpRouter to start listening for messages
     received and accept sending messages.
diff --git a/src/knx/netip/qknxnetiprouter.h b/src/knx/netip/qknxnetiprouter.h
index 8ca5a6a..fb1232f 100644
--- a/src/knx/netip/qknxnetiprouter.h
+++ b/src/knx/netip/qknxnetiprouter.h
@@ -110,11 +110,10 @@ public:
     void setIndividualAddress(const QKnxAddress &address);
 
 public Q_SLOTS:
-    void sendRoutingIndication(const QKnxLinkLayerFrame &linkFrame);
     void sendRoutingIndication(const QKnxNetIpFrame &frame);
     void sendRoutingBusy(const QKnxNetIpFrame &frame);
     void sendRoutingLostMessage(const QKnxNetIpFrame &frame);
-    void sendRoutingSystemBroadcast(const QKnxLinkLayerFrame &linkFrame);
+    void sendRoutingSystemBroadcast(const QKnxNetIpFrame &frame);
 
     void start();
     void stop();
diff --git a/tests/auto/qknxnetiprouter/tst_qknxnetiprouter.cpp b/tests/auto/qknxnetiprouter/tst_qknxnetiprouter.cpp
index eb2d735..0f3b926 100644
--- a/tests/auto/qknxnetiprouter/tst_qknxnetiprouter.cpp
+++ b/tests/auto/qknxnetiprouter/tst_qknxnetiprouter.cpp
@@ -290,7 +290,10 @@ void tst_QKnxNetIpRouter::test_routing_sends_indications()
         QVERIFY(indicationSent.isValid());
         QCOMPARE(indicationSent.linkLayerFrame().bytes(), frameSent.bytes());
     });
-    m_router.sendRoutingIndication(frameSent);
+    auto indication = QKnxNetIpRoutingIndicationProxy::builder()
+                      .setCemi(frameSent)
+                      .create();
+    m_router.sendRoutingIndication(indication);
     QVERIFY(indicationSentEmitted);
 
     bool stateChangedEmitted = false;
@@ -441,7 +444,10 @@ void tst_QKnxNetIpRouter::test_routing_interface_sends_system_broadcast()
             QKnxNetIpRoutingSystemBroadcastProxy sbc(frame);
             QVERIFY(sbc.isValid());
     });
-    m_router.sendRoutingSystemBroadcast(generateDummySbcFrame());
+    auto routingBroadcast = QKnxNetIpRoutingSystemBroadcastProxy::builder()
+                            .setCemi(generateDummySbcFrame())
+                            .create();
+    m_router.sendRoutingSystemBroadcast(routingBroadcast);
     QVERIFY(sbcSent);
 }