{"id":5105,"date":"2026-01-09T17:38:35","date_gmt":"2026-01-09T17:38:35","guid":{"rendered":"http:\/\/renaudguezennec.eu\/?p=5105"},"modified":"2026-01-11T01:05:54","modified_gmt":"2026-01-11T01:05:54","slug":"qtnat-open-you-port-with-qt","status":"publish","type":"post","link":"http:\/\/renaudguezennec.eu\/index.php\/2026\/01\/09\/qtnat-open-you-port-with-qt\/","title":{"rendered":"QtNat – Open your port with Qt"},"content":{"rendered":"\n

QtNat is a lightweight C++ library built with Qt 6 that simplifies NAT port mapping using UPnP (Universal Plug and Play). It is designed to help developers easily expose local services to external networks without requiring manual router configuration for users.<\/p>\n\n\n\n

By leveraging UPnP, QtNat automatically communicates with compatible routers to create port forwarding rules at runtime. This makes it particularly useful for peer-to-peer applications, multiplayer games, remote access tools, and any software that needs reliable inbound connectivity behind a NAT.<\/p>\n\n\n\n

QtNat provides a simplified API to do all steps automatically: discovery and mapping. This has been tested on my local device. Feel free to test it and improve it.<\/p>\n\n\n\n

<\/p>\n\n\n\n

Use it<\/h2>\n\n\n
\n    UpnpNat nat;\n\n    QObject::connect(&nat, &UpnpNat::statusChanged, [&nat, &app]() {\n        switch(nat.status())\n        {\n        case UpnpNat::NAT_STAT::NAT_IDLE:\n        case UpnpNat::NAT_STAT::NAT_DISCOVERY:\n        case UpnpNat::NAT_STAT::NAT_GETDESCRIPTION:\n        case UpnpNat::NAT_STAT::NAT_DESCRIPTION_FOUND:\n            break;\n        case UpnpNat::NAT_STAT::NAT_FOUND:\n            nat.requestDescription();\n            break;\n        case UpnpNat::NAT_STAT::NAT_READY:\n            nat.addPortMapping("UpnpTest", nat.localIp(), 6664, 6664, "TCP");\n            break;\n        case UpnpNat::NAT_STAT::NAT_ADD:\n            qDebug() << "It worked!";\n            app.quit();\n            break;\n        case UpnpNat::NAT_STAT::NAT_ERROR:\n            qDebug() <<"Error:" <<nat.error();\n            app.exit(1);\n            break;\n        }\n    });\n\n    nat.discovery();\n\n<\/pre><\/div>\n\n\n
    \n
  1. We create the object (l:0)<\/li>\n\n\n\n
  2. We connect to statusChanged signal to get notified (l:2)<\/li>\n\n\n\n
  3. When status is NAT_FOUND<\/strong>, we request the description (l:11)<\/li>\n\n\n\n
  4. When status is NAT_READY<\/strong>, we request the port mapping (l:14)<\/li>\n\n\n\n
  5. When status is NAT_ADD<\/strong>, It means the port mapping request has been added, It worked! The application quits.(l:17)<\/li>\n\n\n\n
  6. When status is NAT_ERROR<\/strong>, Error occured and display the error text. The application exits on error. (l:21)<\/li>\n\n\n\n
  7. We connect to error changed in order to detect errors. (l:14)<\/li>\n\n\n\n
  8. We start the discovery. (l:28)<\/li>\n<\/ol>\n\n\n\n
    Technical explainations<\/h2>\n\n\n\n
    The discovery<\/h3>\n\n\n\n
    Basically, we need to know if there is a upnp server around. \nTo do so, we send an M-SEARCH<\/strong> request on the multicast address.<\/p>\n\n\n\n
    Here is the code: <\/p>\n\n\n
    \n#define HTTPMU_HOST_ADDRESS "239.255.255.250"\n#define HTTPMU_HOST_PORT 1900\n#define SEARCH_REQUEST_STRING "M-SEARCH * HTTP\/1.1\\n"            \\\n                              "ST:UPnP:rootdevice\\n"             \\\n                              "MX: 3\\n"                          \\\n                              "Man:\\"ssdp:discover\\"\\n"          \\\n                              "HOST: 239.255.255.250:1900\\n"     \\\n                                                            "\\n"\nvoid UpnpNat::discovery()\n{\n    setStatus(NAT_STAT::NAT_DISCOVERY);\n    m_udpSocketV4.reset(new QUdpSocket(this));\n\n    QHostAddress broadcastIpV4(HTTPMU_HOST_ADDRESS);\n\n    m_udpSocketV4->bind(QHostAddress(QHostAddress::AnyIPv4), 0);\n    QByteArray datagram(SEARCH_REQUEST_STRING);\n\n    connect(m_udpSocketV4.get(), &QTcpSocket::readyRead, this, [this]() {\n        QByteArray datagram;\n        while(m_udpSocketV4->hasPendingDatagrams())\n        {\n            datagram.resize(int(m_udpSocketV4->pendingDatagramSize()));\n            m_udpSocketV4->readDatagram(datagram.data(), datagram.size());\n        }\n\n        QString result(datagram);\n        auto start= result.indexOf("http:\/\/");\n\n        if(start < 0)\n        {\n            setError(tr("Unable to read the beginning of server answer"));\n            setStatus(NAT_STAT::NAT_ERROR);\n            return;\n        }\n\n        auto end= result.indexOf("\\r", start);\n        if(end < 0)\n        {\n            setError(tr("Unable to read the end of server answer"));\n            setStatus(NAT_STAT::NAT_ERROR);\n            return;\n        }\n\n        m_describeUrl= result.sliced(start, end - start);\n\n        setStatus(NAT_STAT::NAT_FOUND);\n        m_udpSocketV4->close();\n    });\n\n    connect(m_udpSocketV4.get(), &QUdpSocket::errorOccurred, this, [this](QAbstractSocket::SocketError) {\n        setError(m_udpSocketV4->errorString());\n        setStatus(NAT_STAT::NAT_ERROR);\n    });\n\n    m_udpSocketV4->writeDatagram(datagram, broadcastIpV4, HTTPMU_HOST_PORT);\n}\n\n<\/pre><\/div>\n\n\n
    The whole goal of the discovery is to get the description<\/strong> file from the server with all available devices and services.\nThe result is stored in m_describeUrl<\/code>.<\/p>\n\n\n\n
    Request Description file<\/h3>\n\n\n\n
    Simple request using QNetworkAccessManager<\/a>.<\/p>\n\n\n
    \nvoid UpnpNat::requestDescription()\n{\n    setStatus(NAT_STAT::NAT_GETDESCRIPTION);\n    QNetworkRequest request;\n    request.setUrl(QUrl(m_describeUrl));\n    m_manager.get(request);\n}\n\n<\/pre><\/div>\n\n\n
    Parsing Description file<\/h3>\n\n\n\n
    Your physical network device may act as several Upnp devices.\nYou are looking for one of these device type:<\/p>\n\n\n\n