QNetworkInformation Class
QNetworkInformation은 네이티브 백엔드를 통해 다양한 네트워크 정보를 제공합니다. 더 보기...
| 헤더: | #include <QNetworkInformation> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Network) target_link_libraries(mytarget PRIVATE Qt6::Network) |
| qmake: | QT += network |
| 다음부터: | Qt 6.1 |
| 상속: | QObject |
공개 유형
| enum class | Feature { Reachability, CaptivePortal, TransportMedium, Metered } |
| flags | Features |
| enum class | Reachability { Unknown, Disconnected, Local, Site, Online } |
(since 6.3) enum class | TransportMedium { Unknown, Ethernet, Cellular, WiFi, Bluetooth } |
속성
(since 6.2)isBehindCaptivePortal : bool(since 6.3)isMetered : bool- reachability : Reachability
(since 6.3)transportMedium : TransportMedium
공개 함수
| QString | backendName() const |
| bool | isBehindCaptivePortal() const |
| bool | isMetered() const |
| QNetworkInformation::Reachability | reachability() const |
(since 6.3) QNetworkInformation::Features | supportedFeatures() const |
| bool | supports(QNetworkInformation::Features features) const |
| QNetworkInformation::TransportMedium | transportMedium() const |
신호
| void | isBehindCaptivePortalChanged(bool state) |
| void | isMeteredChanged(bool isMetered) |
| void | reachabilityChanged(QNetworkInformation::Reachability newReachability) |
| void | transportMediumChanged(QNetworkInformation::TransportMedium current) |
정적 공용 멤버
| QStringList | availableBackends() |
| QNetworkInformation * | instance() |
(since 6.4) bool | loadBackendByFeatures(QNetworkInformation::Features features) |
(since 6.4) bool | loadBackendByName(QStringView backend) |
(since 6.3) bool | loadDefaultBackend() |
상세한 설명
QNetworkInformation은 플러그인을 통해 네트워크 관련 정보에 대한 크로스 플랫폼 인터페이스를 제공합니다.
각기 다른 플러그인은 다양한 기능을 지원할 수 있으므로, 필요한 기능에 따라 플러그인을 불러올 수 있습니다.
대부분의 경우, loadDefaultBackend()를 호출하여 플랫폼별 백엔드를 로드하는 것이 권장되는 방법입니다. 이렇게 하면 현재 플랫폼에서 사용 가능한 가장 적합한 백엔드가 자동으로 선택되며, 대부분의 애플리케이션에 적합합니다.
#include <QCoreApplication>
#include <QNetworkInformation>
#include <QDebug>
void onReachabilityChanged(QNetworkInformation::Reachability reachability) {
switch (reachability) {
case QNetworkInformation::Reachability::Unknown:
qDebug() << "Network reachability is unknown.";
break;
case QNetworkInformation::접근성::연결끊김:
qDebug() << "Network is disconnected.";
break;
case QNetworkInformation::Reachability::Local:
qDebug() << "Network is locally reachable.";
break;
case QNetworkInformation::접근성::사이트:
qDebug() << "Network can reach the site.";
break;
case QNetworkInformation::접근성::온라인:
qDebug() << "Network is online.";
break;
}
}
int main(int argc, char *argv[]) {
QCoreApplication a(argc, argv);
// QNetworkInformation 지원 여부 확인
if (!QNetworkInformation::loadDefaultBackend()) {
qWarning() << "QNetworkInformation is not supported on this platform or backend.";
return 1;
}
QNetworkInformation* netInfo = QNetworkInformation::instance();
// reachabilityChanged 시그널에 연결
QObject::connect(netInfo, &QNetworkInformation::reachabilityChanged,
&onReachabilityChanged);
// 초기 상태 출력
onReachabilityChanged(netInfo->reachability());
return a.exec();
}보다 고급 사용 사례의 경우, 개발자는 특정 기능이나 선호도에 따라 백엔드를 로드하는 것을 선호할 수 있습니다. ` loadBackendByFeatures()`를 사용하면 전송 매체나 신호 강도 보고와 같은 특정 기능 세트를 지원하는 백엔드를 선택할 수 있습니다. 또는 ` loadBackendByName()`를 사용하면 이름으로 플러그인을 로드할 수 있으며, 여기에는 플랫폼별 또는 사용자 정의 백엔드 구현이 포함될 수 있습니다.
QNetworkInformation은 싱글톤이며, 첫 번째 로드 성공 시점부터 QCoreApplication 객체가 소멸될 때까지 유지됩니다. QCoreApplication 객체를 소멸시킨 후 다시 생성하는 경우, 플러그인을 재초기화하려면 이를 다시 로드해야 합니다.
참고: 이 클래스는 싱글톤이면서 동시에 QCoreApplication 에 의존하기때문에 , QNetworkInformation은 항상 QCoreApplication 객체와 동일한 스레드에서 먼저 로드되어야 합니다. 이는 객체가 이 스레드에서 소멸될 것이며, 다양한 백엔드별 구성 요소들이 생성된 스레드와 동일한 스레드에서 소멸되어야 할 수 있기 때문입니다.
QNetworkInformation의 가능한 사용 사례 중 하나는 네트워크 연결 상태를 모니터링하는 것입니다. reachability()은 기본 운영 체제나 플러그인이 보고한 정보를 바탕으로 시스템이 온라인 상태로 간주되는지 여부를 나타냅니다. 그러나 이 정보가 항상 정확한 것은 아닙니다. 예를 들어, Windows에서는 온라인 확인이 Microsoft 소유 서버와의 연결 상태에 의존할 수 있습니다. 해당 서버에 접속할 수 없는 경우(예: 방화벽 규칙으로 인해), 시스템이 잘못된 오프라인 상태라고 보고할 수 있습니다. 따라서 reachability()은 네트워크 연결을 시도하기 전의 결정적인 사전 확인 수단으로 사용되어서는 안 되며, 대신 연결 상태에 대한 일반적인 지표로만 활용해야 합니다.
reachability()를 효과적으로 사용하려면, 애플리케이션이 접속하려는 대상이 어떤 유형인지 파악해야 합니다. 예를 들어, 대상이 로컬 IP 주소인 경우 Reachability::Local 또는 Reachability::Site 로 충분할 수 있습니다. 대상이 공용 인터넷에 있는 경우 Reachability::Online 가 필요합니다. 이러한 맥락을 고려하지 않고 보고된 접속 가능성을 해석하면, 실제 네트워크 접속에 대해 잘못된 가정을 하게 될 수 있습니다.
경고: Linux와 Windows에서만 더 세분화된 Reachability::Site 및 Reachability::Local 옵션을 지원합니다. Android 및 Apple 플랫폼에서는 reachability()가 ‘온라인(Online)’, ‘오프라인(Offline)’ 또는 ‘알 수 없음(Unknown)’ 상태만 보고하도록 제한되어 있습니다. 따라서 로컬 또는 사이트 수준의 연결성을 감지하는 데 의존하는 모든 로직은 적절한 플랫폼 확인 또는 대체 처리를 포함해야 합니다.
// IP 주소가 "로컬"인지 판단하는 간단한 헬퍼 함수
bool isLocalAddress(const QHostAddress&address)
{
return address.isInSubnet(QHostAddress("192.168.0.0"), 16)||
address.isInSubnet(QHostAddress("10.0.0.0"), 8) ||
address.isInSubnet(QHostAddress("172.16.0.0"), 12) ||
address.isLoopback();
}
int main(int argc, char *argv[])
{
...
// 대상 IP 주소 (기본값: Google DNS)
QString targetIpStr = argc > 1 ? argv[1]: "8.8.8.8";
QHostAddress targetIp(targetIpStr);
if (targetIp.isNull()) {
qWarning() << "Invalid IP address:" << targetIpStr;
return 1;
}
// 대상에 대해 필요한 접근성 수준을 결정
QNetworkInformation::Reachability requiredReachability =
isLocalAddress(targetIp)
? QNetworkInformation::Reachability::Local
: QNetworkInformation::Reachability::Online;
// 시스템에서 보고한 현재 접근 가능성 값을 가져옵니다
QNetworkInformation::Reachability currentReachability = networkInfo->reachability();
qDebug() << "Target IP:" << targetIp.toString();
qDebug() << "Target is considered"
<< (isLocalAddress(targetIp) ? "local/site.": "external/online.");
qDebug() << "Required reachability level:" << requiredReachability;
qDebug() << "Current reachability:" << currentReachability;
if (현재 도달 가능성 < 요구되는 도달 가능성) {
qWarning() << "Current network state may not allow reaching the target address.";
} else {
qDebug() << "Target may be reachable based on current network state.";
}
...QNetworkInformation::Feature도 참조하십시오 .
멤버 유형 설명서
enum class QNetworkInformation::Feature
flags QNetworkInformation::Features
플러그인이 현재 지원할 수 있는 모든 기능을 나열합니다. 이 기능은 ` QNetworkInformation::loadBackendByFeatures()`에서 사용할 수 있습니다.
| 상수 | 값 | 설명 |
|---|---|---|
QNetworkInformation::Feature::Reachability | 0x1 | 플러그인이 이 기능을 지원하는 경우, reachability 속성은 유용한 결과를 제공합니다. 그렇지 않은 경우 항상 Reachability::Unknown 를 반환합니다. QNetworkInformation::Reachability 도 참조하십시오. |
QNetworkInformation::Feature::CaptivePortal | 0x2 | 플러그인이 이 기능을 지원하는 경우, isBehindCaptivePortal 속성은 유용한 결과를 제공합니다. 그렇지 않은 경우 항상 false 를 반환합니다. |
QNetworkInformation::Feature::TransportMedium | 0x4 | 플러그인이 이 기능을 지원하는 경우, transportMedium 속성은 유용한 결과를 제공합니다. 그렇지 않은 경우 항상 TransportMedium::Unknown 를 반환합니다. QNetworkInformation::TransportMedium 도 참조하십시오. |
QNetworkInformation::Feature::Metered | 0x8 | 플러그인이 이 기능을 지원하는 경우, isMetered 속성은 유용한 결과를 제공합니다. 그렇지 않은 경우 항상 false 를 반환합니다. |
Features 유형은 QFlags<Feature>에 대한 typedef입니다. 이 유형은 Feature 값들의 OR 조합을 저장합니다.
enum class QNetworkInformation::Reachability
| 상수 | 값 | 설명 |
|---|---|---|
QNetworkInformation::Reachability::Unknown | 0 | 이 값이 반환되면 시스템은 연결된 상태일 수 있으나, OS가 아직 완전한 연결을 확인하지 못했거나 이 기능이 지원되지 않을 수 있습니다. |
QNetworkInformation::Reachability::Disconnected | 1 | 시스템이 전혀 연결되어 있지 않을 수 있음을 나타냅니다. |
QNetworkInformation::Reachability::Local | 2 | 시스템이 네트워크에 연결되어 있지만, 로컬 네트워크에 있는 장치에만 액세스할 수 있을 수 있음을 나타냅니다. |
QNetworkInformation::Reachability::Site | 3 | 시스템이 네트워크에 연결되어 있지만, 로컬 서브넷 또는 인트라넷에 있는 장치에만 액세스할 수 있을 수 있음을 나타냅니다. |
QNetworkInformation::Reachability::Online | 4 | 시스템이 네트워크에 연결되어 있으며 인터넷에 액세스할 수 있음을 나타냅니다. |
QNetworkInformation::reachability도 참조하십시오 .
[since 6.3] enum class QNetworkInformation::TransportMedium
현재 인터넷에 연결할 수 있는 것으로 인식된 미디어를 나열합니다.
| 상수 | 값 | 설명 |
|---|---|---|
QNetworkInformation::TransportMedium::Unknown | 0 | OS에서 활성 매체가 없다고 보고하거나, 활성 매체가 Qt에서 인식되지 않거나, TransportMedium 기능이 지원되지 않는 경우 반환됩니다. |
QNetworkInformation::TransportMedium::Ethernet | 1 | 현재 활성화된 연결이 이더넷을 사용하고 있음을 나타냅니다. 참고: 이 값은 Windows가 블루투스 개인 영역 네트워크에 연결되어 있을 때도 반환될 수 있습니다. |
QNetworkInformation::TransportMedium::Cellular | 2 | 현재 활성화된 연결이 셀룰러 네트워크를 사용하고 있음을 나타냅니다. |
QNetworkInformation::TransportMedium::WiFi | 3 | 현재 활성화된 연결이 Wi-Fi를 사용하고 있음을 나타냅니다. |
QNetworkInformation::TransportMedium::Bluetooth | 4 | 현재 활성화된 연결이 블루투스를 통해 연결되어 있음을 나타냅니다. |
이 열거형은 Qt 6.3에서 도입되었습니다.
QNetworkInformation::transportMedium도 참조하십시오 .
속성 문서
[read-only, since 6.2] isBehindCaptivePortal : bool
사용자의 기기가 캡티브 포털 뒤에 있는지 여부를 알려줍니다.
이 속성은 사용자의 기기가 현재 캡티브 포털 뒤에 있는 것으로 확인되었는지 여부를 나타냅니다. 이 기능은 운영 체제의 캡티브 포털 감지 기능에 의존하며, 이를 보고하지 않는 시스템에서는 지원되지 않습니다. 이 기능이 지원되지 않는 시스템에서는 항상 ` false`를 반환합니다.
이 열거형은 Qt 6.2에서 도입되었습니다.
액세스 함수:
| bool | isBehindCaptivePortal() const |
Notifier 신호:
| void | isBehindCaptivePortalChanged(bool state) |
[read-only, since 6.3] isMetered : bool
현재 연결이 데이터 사용량 제한이 적용되는지 확인하세요
이 속성은 현재 연결이 (알려진 바에 따르면) 데이터 사용량 제한이 적용되는지 여부를 반환합니다. 이 정보를 바탕으로 애플리케이션에서 특정 네트워크 요청이나 업로드를 수행할지 여부를 결정하는 데 참고할 수 있습니다. 예를 들어, 이 속성이 ` true`인 경우 로그나 진단 정보를 업로드하지 않는 것이 좋습니다.
void uploadLogFile()
{
...
}
int main(int argc, char *argv[])
{
QCoreApplication app(argc, argv);
...
if (netInfo->isMetered()) {
qWarning() << "Log upload skipped: Current network is metered.";
app.quit();
} else {
uploadLogFile();
}
...
}이 열거형은 Qt 6.3에서 도입되었습니다.
액세스 함수:
| bool | isMetered() const |
Notifier 시그널:
| void | isMeteredChanged(bool isMetered) |
[read-only] reachability : Reachability
이 속성은 시스템의 네트워크 연결 상태를 나타냅니다.
예상 가능한 연결 수준을 나타냅니다. 이 정보는 플러그인/운영 체제가 보고하는 내용만을 기반으로 한다는 점에 유의하십시오. 특정 상황에서는 이 정보가 부정확할 수 있습니다. 예를 들어, Windows에서 '온라인' 확인은 기본적으로 Windows가 Microsoft 소유의 서버에 연결하여 수행됩니다. 어떤 이유로든 이 서버에 접속이 차단되면, 시스템은 온라인 연결이 불가능한 것으로 간주합니다. 따라서 연결을 시도하기 전 사전 확인 용도로 이 정보를 사용해서는 안 됩니다.
액세스 기능:
| QNetworkInformation::Reachability | reachability() const |
알림 신호:
| void | reachabilityChanged(QNetworkInformation::Reachability newReachability) |
[read-only, since 6.3] transportMedium : TransportMedium
이 속성은 애플리케이션에 대해 현재 활성화된 전송 매체를 저장합니다.
이 속성은 해당 정보가 제공되는 운영 체제에서 애플리케이션의 현재 활성화된 전송 매체를 반환합니다.
현재 전송 매체가 변경되면 신호가 발생하며, 이는 예를 들어 사용자가 WiFi 네트워크의 범위를 벗어나거나, 이더넷 케이블을 뽑거나, 비행기 모드를 켤 때 발생할 수 있습니다.
이 열거형은 Qt 6.3에서 도입되었습니다.
액세스 함수:
| QNetworkInformation::TransportMedium | transportMedium() const |
Notifier 신호:
| void | transportMediumChanged(QNetworkInformation::TransportMedium current) |
멤버 함수 문서
[static] QStringList QNetworkInformation::availableBackends()
현재 사용 가능한 모든 백엔드의 이름을 담은 목록을 반환합니다.
QString QNetworkInformation::backendName() const
현재 로드된 백엔드의 이름을 반환합니다.
[static] QNetworkInformation *QNetworkInformation::instance()
QNetworkInformation 의 인스턴스가 있는 경우, 해당 인스턴스에 대한 포인터를 반환합니다. 백엔드가 로드되기 전에 이 메서드가 호출되면 null 포인터를 반환합니다.
loadBackendByName(), loadDefaultBackend(), loadBackendByFeatures()도 참조하십시오 .
[static, since 6.4] bool QNetworkInformation::loadBackendByFeatures(QNetworkInformation::Features features)
features 를 지원하는 백엔드를 불러옵니다.
요청된 백엔드를 성공적으로 로드했거나 이미 로드되어 있는 경우 ` true `을 반환합니다. 그렇지 않은 경우 ` false `을 반환합니다.
이 함수는 Qt 6.4에서 도입되었습니다.
instance도 참조하십시오 .
[static, since 6.4] bool QNetworkInformation::loadBackendByName(QStringView backend)
backend 와 이름이 일치하는(대소문자 구분 없이) 백엔드를 불러오려고 시도합니다.
요청된 백엔드를 성공적으로 로드했거나 이미 로드된 상태인 경우 true 을 반환합니다. 그렇지 않은 경우 false 을 반환합니다.
이 함수는 Qt 6.4에서 도입되었습니다.
instance도 참조하십시오 .
[static, since 6.3] bool QNetworkInformation::loadDefaultBackend()
플랫폼 기본 백엔드를 불러오려고 시도합니다.
참고: 6.7버전부터는 플랫폼 기본 백엔드를 사용할 수 없거나 로드에 실패할 경우, ` Reachability `를 지원하는 백엔드를 로드하려고 시도합니다. 이 시도도 실패하면 모든 속성에 대해 기본값만 반환하는 백엔드로 대체됩니다.
플랫폼과 플러그인 간의 매핑은 다음과 같습니다:
| 플랫폼 | 플러그인 이름 |
|---|---|
| Windows | networklistmanager |
| Apple (macOS/iOS) | applenetworkinformation |
| Android | 안드로이드 |
| Linux | 네트워크 매니저 |
이 함수는 앞서 설명한 로직만으로도 충분한 경우에 편의상 제공됩니다. 특정 플러그인이 필요한 경우에는 대신 loadBackendByName() 또는 loadBackendByFeatures()를 직접 호출해야 합니다.
로드할 적절한 백엔드를 결정하며, 해당 백엔드가 이미 로드되어 있거나 로드에 성공한 경우 true 를 반환합니다. 다른 백엔드가 이미 로드되어 있거나 선택한 백엔드의 로드에 실패한 경우 false 를 반환합니다.
이 함수는 Qt 6.3에서 도입되었습니다.
instance(), loadBackendByName(), loadBackendByFeatures()도 참조하십시오 .
[since 6.3] QNetworkInformation::Features QNetworkInformation::supportedFeatures() const
현재 백엔드에서 지원하는 모든 기능을 반환합니다.
이 함수는 Qt 6.3에서 도입되었습니다.
bool QNetworkInformation::supports(QNetworkInformation::Features features) const
현재 로드된 백엔드가 ` features`을 지원하는 경우 ` true `을 반환합니다.
© 2026 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.