/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \example knxeditor
    \title KNX Editor Example
    \ingroup qtknx-examples

    \brief A KNX client for handling KNX local device management and
    tunneling.

    \image editor-main.png "KNX editor"

    The KNX Editor user interface contains a \uicontrol Communication group,
    tabs for different KNX functionalities, and an \uicontrol Output panel.

    To get started, users select one of the network interfaces on their
    machine in the \uicontrol {Local IP Address} field, and then select
    \uicontrol Scan to find any neighbouring KNX routers.

    Once the client discovers KNX routers, information about them is displayed
    in the \uicontrol Output panel. Users must select a router to enable the
    tab views.

    In the \uicontrol {Local Device Management} tab, users can customize
    the KNX frame and some parameters. They can choose the local management
    service type request to send and attach data values to it. The request
    is sent after the users select \uicontrol Connect. The received response
    is displayed in the tab. The following image shows an M_PropRead.req
    request that was sent and the response that was received.

    \image editor-devman.jpg "local device management tab"

    The \uicontrol Tunneling tab allows establishing a KNXnet/IP tunnel
    connection to a KNX router. The tunnel is established by selecting
    \uicontrol Connect. It is then possible to send data link layer service
    requests and customize the parameters contained in the requests. The
    following image shows an example of sending an L_Data.req request.

    \image tunnel-tab.jpg

    The \uicontrol {Tunneling Features} tab requires a KNX router that supports
    tunneling version 2. It allows accessing information such as the device
    descriptor of the host device and other properties. It is an extension
    that enables users to access the required management information over their
    authorized tunneling connection only.

    The \uicontrol Output panel shows the traffic moving over the connection
    between the client and the server.

    The application consists of four classes:

    \list
        \li \c MainWindow is a \l QMainWindow that renders the general layout of
            the application.
        \li \c LocalDeviceManagement is a \l QWidget connected to the
            \uicontrol {Local Device Management} tab.
        \li \c Tunneling is a \l QWidget asociated with the
            \uicontrol Tunneling tab.
        \li \c TunnelingFeatures is a \l QWidget linked to the
            \uicontrol {Tunneling Features} tab.
    \endlist

    Each of the above classes stores a reference to the class definition
    generated by \c qmake for every designer UI file. Through that reference,
    the above classes can interact with the graphical components of the
    application.

    \section1 Main Window Class Definition and Implementation

    \quotefromfile knxeditor/mainwindow.h
    \skipto class MainWindow :
    \printuntil /^\}/

    The \c MainWindow class uses a \l QKnxNetIpServerDiscoveryAgent instance
    that allows discovering KNXnet/IP servers by sending a search request
    in the network that the client is connected to. It also saves an
    instance of QKnxNetIpServerInfo for storing information about the
    current KNXnet/IP server (router) selected by the user.

    The \c QKnxNetIpServerDiscoveryAgent is initiated when the \uicontrol Scan
    button is clicked. Here is the code snippet doing it:

    \quotefromfile knxeditor/mainwindow.cpp
    \skipto MainWindow::MainWindow
    \printuntil {
    \dots
    \skipto QPushButton::clicked
    \printuntil );
    \dots

    There are signal handlers installed for every signal emitted by the
    discovery agent. Here is an example of one of the setups capturing the
    \l QKnxNetIpServerDiscoveryAgent::deviceDiscovered signal emitted when
    a server is found:

    \quotefromfile knxeditor/mainwindow.cpp
    \skipto MainWindow::MainWindow
    \printuntil {
    \dots
    \skipto QKnxNetIpServerDiscoveryAgent::deviceDiscovered
    \printuntil );
    \dots

    In this last example, when \l
    QKnxNetIpServerDiscoveryAgent::deviceDiscovered is triggered, the
    function \c MainWindow::showServerAndServices() is called. It displays
    information about the routers in the \uicontrol Output panel.

    At this point, users can select one of the available routers to establish
    a connection, and send the different types of frames using the different
    features available in the tabs:

    \quotefromfile knxeditor/mainwindow.cpp
    \skipto MainWindow::MainWindow
    \printuntil {
    \dots
    \skipto QKnxNetIpServerDiscoveryAgent::finished
    \printuntil });
    \dots
    \skipto /^\}/
    \printuntil /^\}/
    \skipto void MainWindow::newServerSelected
    \printuntil auto info
    \dots
    \skipto info.endpoint
    \printuntil /^\}/

    The \c MainWindow::newServerSelected method saves the selected server in
    the \c MainWindow instance.

    \section1 Local Device Management Class Definition and Implementation

    \quotefromfile knxeditor/localdevicemanagement.h
    \skipto class LocalDeviceManagement :
    \printuntil /^\}/

    Local device management uses an instance of \l QKnxNetIpDeviceManagement
    for the opening and handling of a device management connection to a
    KNXnet/IP router. The tunnel is created when the \uicontrol Connect button
    is clicked.

    \quotefromfile knxeditor/localdevicemanagement.cpp
    \skipto LocalDeviceManagement::LocalDeviceManagement
    \printuntil {
    \dots
    \skipto QPushButton::clicked
    \printuntil });
    \dots
    \skipto /^\}/
    \printuntil /^\}/

    The \l QKnxNetIpDeviceManagement instance is instructed to connect
    to the server host that was previously selected.

    Once the \l QKnxNetIpDeviceManagement::connected signal is triggered, the
    \uicontrol {Send Request} button gets enabled and the client can begin
    sending customized device management service requests. The code snippet
    below shows the handler set up for the \c clicked signal of the
    \uicontrol {Send Request} button (\c deviceManagementSendRequest):

    \quotefromfile knxeditor/localdevicemanagement.cpp
    \skipto LocalDeviceManagement::LocalDeviceManagement
    \printuntil {
    \dots
    \skipto QKnxNetIpDeviceManagement::connected
    \printuntil     });
    \dots
    \skipto deviceManagementSendRequest, &QPushButton::clicked
    \printuntil     });
    \dots
    \skipto /^\}/
    \printuntil /^\}/


    \section1 Tunneling Class Definition and Implementation

    \quotefromfile knxeditor/tunneling.h
    \skipto class Tunneling :
    \printuntil /^\}/

    The \c Tunneling class holds a \l QKnxNetIpTunnel that enables the opening
    and handling of a KNXnet/IP client connection to a KNXnet/IP server. Once
    the class is instantiated, the client establishes the connection when the
    \uicontrol Connect button is clicked:

    \quotefromfile knxeditor/tunneling.cpp
    \skipto Tunneling::Tunneling
    \printuntil {
    \dots
    \skipto QPushButton::clicked
    \printuntil     });
    \dots
    \skipto /^\}/
    \printuntil /^\}/

    The received KNX frames are decoded and handled here:

    \quotefromfile knxeditor/tunneling.cpp
    \skipto Tunneling::Tunneling
    \printuntil {
    \dots
    \skipto QKnxNetIpTunnel::frameReceived
    \printuntil     });
    \dots
    \skipto /^\}/
    \printuntil /^\}/

    \section1 TunnelingFeatures Class Definition and Implementation

    \quotefromfile knxeditor/tunnelingfeatures.h
    \skipto class TunnelingFeatures :
    \printuntil /^\}/

    Similarly to the \c Tunneling class, the \c TunnelingFeatures class uses a
    \l QKnxNetIpTunnel for opening and handling a KNXnet/IP client connection.
    However, it makes use of some  additional methods for sending the tunneling
    feature version 2 frames: \l QKnxNetIpTunnel::sendTunnelingFeatureGet and
    \l QKnxNetIpTunnel::sendTunnelingFeatureSet. Here is the handler for
    the \c clicked singal of the \uicontrol {Send Message} button
    (\c tunnelingSend):

    \quotefromfile knxeditor/tunnelingfeatures.cpp
    \skipto tunnelingSend, &QPushButton::clicked
    \printuntil     });

    \section1 The Main Function

    The KNX editor \c main() function does not have any special handling. It
    looks like the main function for any Qt app:

    \quotefromfile knxeditor/main.cpp
    \skipto #include
    \printuntil /^\}/
*/
