Doc: Add info to KNXnet/IP connection classes overview

- Move some information around
- Describe proxy and builder patterns for KNXnet/IP classes
- Replace the class diagram with one that only shows the classes
  that are typically used
- Describe proxy and builder patterns for data structs
- Add info about QKnxNetIpStruct and QKnxNetIpStructHeader

Change-Id: Ic3377823e13ec95dc8c74944861377af469453d4
Reviewed-by: Karsten Heimrich <karsten.heimrich@qt.io>

3 files changed, 121 insertions, 64 deletions

diff --git a/src/knx/doc/images/qtknx-netip-connection-classes.png b/src/knx/doc/images/qtknx-netip-connection-classes.png
new file mode 100644
index 0000000..2ad5aee
--- /dev/null
+++ b/src/knx/doc/images/qtknx-netip-connection-classes.png
diff --git a/src/knx/doc/images/qtknx-netip-frame-proxy-classes.png b/src/knx/doc/images/qtknx-netip-frame-proxy-classes.png
deleted file mode 100644
index 9e22a59..0000000
--- a/src/knx/doc/images/qtknx-netip-frame-proxy-classes.png
+++ /dev/null
diff --git a/src/knx/doc/src/netip-connections.qdoc b/src/knx/doc/src/netip-connections.qdoc
index b459344..270c4fd 100644
--- a/src/knx/doc/src/netip-connections.qdoc
+++ b/src/knx/doc/src/netip-connections.qdoc
@@ -42,116 +42,181 @@
     \l QKnxNetIpServerInfo classes can be used to obtain additional
     information about a particular server.
 
+    \image qtknx-netip-connection-classes.png
+
     Once the KNXnet/IP server is discovered, the KNXnet/IP client uses the
     server endpoints to establish a communication channel to the server for
-    transferring KNXnet/IP frames.
+    transferring KNXnet/IP frames. Usually, the \l QKnxNetIpTunnel or
+    \l QKnxNetIpDeviceManagement class is used to establish a functional
+    connection to a KNXnet/IP server.
+
+    \section1 KNXnet/IP Frames
+
+    The body of every KNXnet/IP frame (\l QKnxNetIpFrame) sent over an
+    established communication channel starts with a data field that contains
+    additional general information about the data connection
+    (\l QKnxNetIpConnectionHeader). The amount of this data and what
+    type of information is included there in particular is determined by
+    several options during the connection phase of a communication channel.
 
-    The Qt KNX module contains a set of proxy classes that provide the
+    To deal with the high number of specializations needed for the KNXnet/IP
+    frame, the \e {proxy pattern} was introduced. The proxy classes provide the
     means to read a request, response, or acknowledgment from the generic
     \l QKnxNetIpFrame class and to create a KNXnet/IP frame based on the
     information.
 
-    \image qtknx-netip-frame-proxy-classes.png
+    For example, the following code sample illustrates how to use the
+    \l QKnxNetIpSearchRequestProxy class to read the search request information
+    sent by a KNXnet/IP client:
+
+    \code
+        auto netIpFrame = QKnxNetIpFrame::fromBytes(...);
+
+        QKnxNetIpSearchRequestProxy searchRequest(netIpFrame);
+        if (!searchRequest.isValid())
+            return;
+
+        QKnxNetIpHpai hpai = searchRequest.discoveryEndpoint();
+        // ...
+    \endcode
+
+    Because the frame is a structure that has many fields, having to know the
+    exact order of parameters that can be passed to the constructor makes it
+    difficult to use correctly. To make this easier, the \e {builder pattern}
+    was introduced. The builder classes enable the encapsulation of the
+    construction, and thus provide a more flexible solution.
 
-    \note In most programs, these classes will not be used directly.
-    Instead, the \l QKnxNetIpTunnel or \l QKnxNetIpDeviceManagement
-    class is used to establish a functional connection to a KNXnet/IP server.
+    The following code sample illustrates how to create a search request using
+    the \l QKnxNetIpSearchRequestProxy::Builder class:
+
+    \code
+        auto hpai = QKnxNetIpHpaiProxy::builder().create();
+
+        auto netIpFrame = QKnxNetIpSearchRequestProxy::builder()
+            .setDiscoveryEndpoint(hpai)
+            .create();
+    \endcode
 
     The following sections describe the process of establishing a communication
     channel between a KNXnet/IP client and a KNXnet/IP server using the proxy
-    classes.
+    or builder classes.
+
+    Similar proxy and builder patterns are available for constructing KNXnet/IP
+    device information block (DIB), connection request information (CRI), and
+    connection response data (CRD) structures from generic classes that are
+    based on the \l QKnxNetIpStruct class. These data structures can be
+    encapsulated in a KNXnet/IP frame. The \l QKnxNetIpStructHeader class
+    specifies the type of the data structure.
 
     \section1 Discovering KNXnet/IP Servers
 
     To discover KNXnet/IP servers, a KNXnet/IP client sends a search request
-    frame (\l QKnxNetIpSearchRequestProxy) via multicast using its
+    frame (\l QKnxNetIpSearchRequestProxy or
+    \l QKnxNetIpSearchRequestProxy::Builder) via multicast using its
     \e {discovery endpoint}. All servers that receive the request immediately
-    send a search response (\l QKnxNetIpSearchResponseProxy) using the host
+    send a search response (\l QKnxNetIpSearchResponseProxy or
+    \l QKnxNetIpSearchResponseProxy::Builder) using the host
     address protocol information (HPAI) of the client's discovery endpoint.
     The search response frame contains the HPAI of the server's control endpoint
-    (\l QKnxNetIpHpai) for all further communication.
+    for all further communication.
 
     Before communicating with a KNXnet/IP server, the KNXnet/IP client sends a
-    description request (\l QKnxNetIpDescriptionRequestProxy) through a unicast
+    description request (\l QKnxNetIpDescriptionRequestProxy or
+    \l QKnxNetIpDescriptionRequestProxy::Builder) through a unicast
     or point-to-point connection to all \e {control endpoints} of the server to
     check that the server supports the requested connection type and options.
     The server replies by sending a description response frame
-    (\l QKnxNetIpDescriptionResponseProxy) that contains the requested
+    (\l QKnxNetIpDescriptionResponseProxy or
+    \l QKnxNetIpDescriptionResponseProxy::Builder) that contains the requested
     information.
 
     Search and description response frames contain information about the
-    KNXnet/IP server as a KNXnet/IP device information block (DIB) structure.
-    A DIB structure is constructed by using the QKnxNetIpDeviceDibProxy class
-    to read the device information from the generic \l QKnxNetIpDib class.
-    The following proxy classes can be used to read other types of device
-    information from the class:
+    KNXnet/IP server as a KNXnet/IP DIB structure. A DIB structure is
+    constructed by using the \l QKnxNetIpDeviceDibProxy or
+    \l QKnxNetIpDeviceDibProxy::Builder class to read the device information
+    from the generic \l QKnxNetIpDib class. The following proxy and builder
+    classes can be used to read other types of device information from the
+    class:
 
     \list
-        \li \l QKnxNetIpConfigDibProxy for reading the IP configuration of a
-            KNXnet/IP device
-        \li \l QKnxNetIpCurrentConfigDibProxy for reading the current IP
-            configuration of a KNXnet/IP device
-        \li \l QKnxNetIpKnxAddressesDibProxy for reading all assigned individual
-            addresses of a KNXnet/IP device
-        \li \l QKnxNetIpManufacturerDibProxy for reading manufacturer specific
-            device information
-        \li \l QKnxNetIpServiceFamiliesDibProxy for reading the service families
-            and versions supported by a KNXnet/IP device
+        \li \l QKnxNetIpConfigDibProxy or \l QKnxNetIpConfigDibProxy::Builder
+            for reading the IP configuration of a KNXnet/IP device
+        \li \l QKnxNetIpCurrentConfigDibProxy or
+            \l QKnxNetIpCurrentConfigDibProxy::Builder for reading the current
+            IP configuration of a KNXnet/IP device
+        \li \l QKnxNetIpKnxAddressesDibProxy or
+            \l QKnxNetIpKnxAddressesDibProxy::Builder for reading all assigned
+            individual addresses of a KNXnet/IP device
+        \li \l QKnxNetIpManufacturerDibProxy or
+            \l QKnxNetIpManufacturerDibProxy::Builder for reading manufacturer
+            specific device information
+        \li \l QKnxNetIpServiceFamiliesDibProxy or
+            \l QKnxNetIpServiceFamiliesDibProxy::Builder for reading the service
+            families and versions supported by a KNXnet/IP device
     \endlist
 
     \section1 Creating and Maintaining Communication Channels
 
     To establish a communication channel to a KNXnet/IP server, a KNXnet/IP
-    client sends a connection request (\l QKnxNetIpConnectRequestProxy). The
-    connection request provides information needed for different types of
-    communication channels to fulfill a connection request as a KNXnet/IP
-    connection request information (CRI) structure. A CRI structure is
-    constructed from the generic \l QKnxNetIpCri class by using the
-    \l QKnxNetIpCriProxy class.
+    client sends a connection request (\l QKnxNetIpConnectRequestProxy or
+    \l QKnxNetIpConnectRequestProxy::Builder). The connection request provides
+    information needed for different types of communication channels to fulfill
+    a connection request as a KNXnet/IP CRI structure. A CRI structure is
+    constructed from the generic  \l QKnxNetIpCri class by using the
+    \l QKnxNetIpCriProxy or \l QKnxNetIpCriProxy::Builder class.
 
     In response, the KNXnet/IP server sends a connection response frame
-    (\l QKnxNetIpConnectResponseProxy) that returns the group address or
+    (\l QKnxNetIpConnectResponseProxy or
+    \l QKnxNetIpConnectResponseProxy::Builder) that returns the group address or
     individual address (\l QKnxAddress) that is assigned to the connection
     by the server.
 
-    The address is returned in a connection response data (CRD) structure with
-    the connect response \l QKnxNetIpFrame. The CRD structure is constructed
-    from the generic \l QKnxNetIpCrd class by using the \l QKnxNetIpCrdProxy
-    class.
+    The address is returned in a CRD structure with the connect response
+    \l QKnxNetIpFrame. The CRD structure is constructed from the generic
+    \l QKnxNetIpCrd class by using the \l QKnxNetIpCrdProxy or
+    \l QKnxNetIpCrdProxy::Builder class.
 
     If the server accepted the request, the frame also contains the identifier
     and HPAI of the \e {data endpoint} that the server prepared for the
     communication channel.
 
     A KNXnet/IP client reqularly sends a connection state request frame
-    (\l QKnxNetIpConnectionStateRequestProxy) to the KNXnet/IP server's control
-    endpoint to check the state of a connection established to the server.
-    The server responds immediately with a connection state response frame
-    (\l QKnxNetIpConnectionStateResponseProxy).
+    (\l QKnxNetIpConnectionStateRequestProxy or
+    \l QKnxNetIpConnectionStateRequestProxy::Builder) to the KNXnet/IP server's
+     control endpoint to check the state of a connection established to the
+    server. The server responds immediately with a connection state response
+    frame (\l QKnxNetIpConnectionStateResponseProxy or
+    \l QKnxNetIpConnectionStateResponseProxy::Builder).
 
     \section1 Sending Service Requests
 
     Once the communication channel is established, the KNXnet/IP client can
-    send tunneling requests (\l QKnxNetIpTunnelingRequestProxy) and device
-    configuration requests (\l QKnxNetIpDeviceConfigurationRequestProxy) to
+    send tunneling requests (\l QKnxNetIpTunnelingRequestProxy or
+    \l QKnxNetIpTunnelingRequestProxy::Builder) and device
+    configuration requests (\l QKnxNetIpDeviceConfigurationRequestProxy or
+    \l QKnxNetIpDeviceConfigurationRequestProxy::Builder) to
     the KNXnet/IP server. The server responds with a tunneling acknowledgment
-    (\l QKnxNetIpTunnelingAcknowledgeProxy) or a device configuration
-    acknowledgment (\l QKnxNetIpDeviceConfigurationRequestProxy), respectively.
+    (\l QKnxNetIpTunnelingAcknowledgeProxy or
+    \l QKnxNetIpTunnelingAcknowledgeProxy::Builder) or a device configuration
+    acknowledgment (\l QKnxNetIpDeviceConfigurationRequestProxy or
+    \l QKnxNetIpDeviceConfigurationRequestProxy::Builder), respectively.
 
     If the KNXnet/IP client does not receive an acknowledgment within a
     specified timeout, or the status of a received acknowledgment frame
     indicates that errors occurred, the client repeats the request frame
     the specified number of times and then terminates the connection by
-    sending a disconnection request (\l QKnxNetIpDisconnectRequestProxy)
-    to the server's control endpoint.
+    sending a disconnection request (\l QKnxNetIpDisconnectRequestProxy or
+    \l QKnxNetIpDisconnectRequestProxy::Builder) to the server's control
+    endpoint.
 
     For more information about device management and tunneling, see
     \l {Qt KNX Device Management Classes} and \l {Qt KNX Tunneling Classes}.
 
     \section1 KNXnet/IP Endpoints
 
-    The HPAI structure (created by using the \l QKnxNetIpHpaiProxy) contains
-    the IP address and port number needed to send a KNXnet/IP frame to another
+    The HPAI structure (read from the generic \l QKnxNetIpHpai class by using
+    \l QKnxNetIpHpaiProxy or \l QKnxNetIpHpaiProxy::Builder) contains the IP
+    address and port number needed to send a KNXnet/IP frame to another
     device. Different types of \e endpoints provide logical views of a HPAI to
     access devices for a particular purpose.
 
@@ -163,22 +228,13 @@
     The control endpoint uniquely identifies a KNXnet/IP server that provides
     at least one type of KNXnet/IP service.
 
-    \section1 KNXnet/IP Frames
-
-    The body of every KNXnet/IP frame (\l QKnxNetIpFrame) sent over an
-    established communication channel starts with a data field that contains
-    additional general information about the data connection
-    (\l QKnxNetIpConnectionHeader). The amount of this data and what
-    type of information is included there in particular is determined by
-    several options during the connection phase of a communication channel.
-
     \section1 Routing
 
     A routing indication is sent by a KNXnet/IP router or device to transmit KNX
     link layer frames over IP networks. The \l QKnxNetIpRoutingIndicationProxy
-    class provides the means to read a routing indication from the generic
-    \l QKnxNetIpFrame class and to create a KNXnet/IP frame based on the
-    information.
+    and \l QKnxNetIpRoutingIndicationProxy::Builder class provides the means to
+    read a routing indication from the generic \l QKnxNetIpFrame class and to
+    create a KNXnet/IP frame based on the information.
 
     Depending on the configuration, a KNXnet/IP router or device can receive
     more datagrams than it can forward to the KNX subnetwork. This can lead
@@ -189,13 +245,14 @@
     Flow control is implemented by means of sending router busy messages
     to avoid the loss of datagrams due to overflowing queues in routers and
     devices. Router busy messages are created by using the
-    \l QKnxNetIpRoutingBusyProxy class.
+    \l QKnxNetIpRoutingBusyProxy or \l QKnxNetIpRoutingBusyProxy::Builder class.
 
     A routing-lost message is multicast by a KNXnet/IP router to notify that
     KNXnet/IP routing indication frames were lost. The message contains the
     state of the router or device (\l QKnx::NetIp::DeviceState) and the number
     of lost frames. The messages are created by using the
-    \l QKnxNetIpRoutingLostMessageProxy class.
+    \l QKnxNetIpRoutingLostMessageProxy or
+    \l QKnxNetIpRoutingLostMessageProxy::Builder class.
 
     \section1 List of KNXnet/IP Classes