QNetworkInformation Class

Q네트워크정보는 네이티브 백엔드를 통해 다양한 네트워크 정보를 노출합니다. 더 보기...

Header: #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 }

속성

공공 기능

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::도달 가능성 도달 가능성) { switch (도달 가능성) { case QNetworkInformation::도달 가능성::알 수 없음:        qDebug() << "Network reachability is unknown.";
       break; case QNetworkInformation::도달 가능성::연결이 끊어졌습니다:        qDebug() << "Network is disconnected.";
       break; case QNetworkInformation::도달 가능성::로컬:        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.";
       반환 1; } QNetworkInformation* netInfo = QNetworkInformation::instance(); // 도달가능성 변경 신호에 연결   QObject::connect(netInfo, &.QNetworkInformation::reachabilityChanged, &onReachabilityChanged); // 초기 상태 출력onReachabilityChanged(netInfo->reachability()); return a.exec(); }

고급 사용 사례의 경우 개발자는 특정 기능이나 기본 설정에 따라 백엔드를 로드하는 것을 선호할 수 있습니다. loadBackendByFeatures()를 사용하면 전송 매체 또는 신호 강도 보고와 같은 특정 기능 집합을 지원하는 백엔드를 선택할 수 있습니다. 또는 loadBackendByName()를 사용하면 플랫폼별 또는 사용자 정의 백엔드 구현을 포함할 수 있는 플러그인을 이름으로 로드할 수 있습니다.

QNetworkInformation은 싱글톤이며 첫 번째 로드 성공부터 QCoreApplication 객체가 파괴될 때까지 살아 있습니다. QCoreApplication 객체를 파괴하고 다시 생성하는 경우 다시 로드하여 플러그인을 다시 초기화해야 합니다.

참고: 이 클래스는 싱글톤인 동시에 QCoreApplication 에 의존하기 때문에 항상 QCoreApplication 객체와 동일한 스레드에서 QNetworkInformation 을 먼저 로드해야 합니다. 이 스레드에서 객체도 소멸되고 다양한 백엔드 관련 구성 요소가 생성될 때 동일한 스레드에서 소멸되는 것에 의존할 수 있기 때문입니다.

QNetworkInformation의 한 가지 가능한 사용 사례는 네트워크 연결 상태를 모니터링하는 것입니다. reachability()는 기본 운영 체제 또는 플러그인에서 보고한 정보를 기반으로 시스템이 온라인 상태로 간주되는지 여부를 표시합니다. 그러나 이 정보가 항상 정확하지는 않을 수 있습니다. 예를 들어, Windows의 경우 온라인 상태 확인은 Microsoft 소유 서버에 대한 연결에 의존할 수 있으며, 방화벽 규칙 등으로 인해 해당 서버에 연결할 수 없는 경우 시스템이 오프라인 상태라고 잘못 보고할 수 있습니다. 따라서 reachability()는 네트워크 연결을 시도하기 전에 최종적인 사전 검사로 사용해서는 안 되며, 연결 상태에 대한 일반적인 신호로만 사용해야 합니다.

reachability()를 효과적으로 사용하려면 애플리케이션이 도달하려는 대상의 종류도 이해해야 합니다. 예를 들어, 대상이 로컬 IP 주소인 경우 Reachability::Local 또는 Reachability::Site 으로 충분할 수 있습니다. 대상이 공용 인터넷에 있는 경우 Reachability::Online 이 필요합니다. 이러한 맥락이 없으면 보고된 도달 가능성을 해석할 때 실제 네트워크 액세스에 대해 잘못된 가정을 하게 될 수 있습니다.

경고: Linux와 Windows에서만 더 세분화된 Reachability::SiteReachability::Local 옵션을 지원합니다. Android 및 Apple 플랫폼에서 reachability()는 온라인, 오프라인 또는 알 수 없음만 보고하도록 제한됩니다. 따라서 로컬 또는 사이트 수준 연결을 감지하는 데 의존하는 모든 로직에는 적절한 플랫폼 검사 또는 폴백이 포함되어야 합니다.

// 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;
       반환 1; } // 타겟에 필요한 도달 가능성 수준을 결정합니다.   QNetworkInformation::도달 가능성 requiredReachability =isLocalAddress(targetIp) ? QNetworkInformation::도달 가능성::로컬 : QNetworkInformation::도달가능성::온라인; // 현재 시스템에서 보고된 도달가능성을 가져옵니다.    QNetworkInformation::도달 가능성 currentReachability =  networkInfo->reachability();
    qDebug() << "Target IP:" << targetIp.toString();
    qDebug() << "Target is considered"
            << (isLocalAddress(targetIp) ? "local/site.": "외부/온라인.");    qDebug() << "Required reachability level:" << requiredReachability;
    qDebug() << "Current reachability:" << currentReachability;

   if (currentReachability < requiredReachability) {        qWarning() << "Current network state may not allow reaching the target address.";
    } else {        qDebug() << "Target may be reachable based on current network state.";
    } ...

QNetworkInformation::Feature도 참조하세요 .

멤버 유형 문서

열거형 클래스 Q네트워크정보::기능
플래그 Q네트워크정보::기능

플러그인이 현재 지원할 수 있는 모든 기능을 나열합니다. QNetworkInformation::loadBackendByFeatures ()에서 사용할 수 있습니다.

상수설명
QNetworkInformation::Feature::Reachability0x1플러그인이 이 기능을 지원하는 경우 reachability 속성이 유용한 결과를 제공합니다. 그렇지 않으면 항상 Reachability::Unknown 을 반환합니다. QNetworkInformation::Reachability 를 참조하세요.
QNetworkInformation::Feature::CaptivePortal0x2플러그인이 이 기능을 지원하는 경우 isBehindCaptivePortal 속성이 유용한 결과를 제공합니다. 그렇지 않으면 항상 false 을 반환합니다.
QNetworkInformation::Feature::TransportMedium0x4플러그인에서 이 기능을 지원하는 경우 transportMedium 속성이 유용한 결과를 제공합니다. 그렇지 않으면 항상 TransportMedium::Unknown 을 반환합니다. QNetworkInformation::TransportMedium 를 참조하세요.
QNetworkInformation::Feature::Metered0x8플러그인이 이 기능을 지원하는 경우 isMetered 속성이 유용한 결과를 제공합니다. 그렇지 않으면 항상 false 을 반환합니다.

Features 유형은 QFlags<Feature>에 대한 typedef입니다. Feature 값의 OR 조합을 저장합니다.

enum class QNetworkInformation::Reachability

상수설명
QNetworkInformation::Reachability::Unknown0이 값이 반환되면 연결되었지만 OS에서 아직 완전한 연결을 확인하지 못했거나 이 기능이 지원되지 않는 것입니다.
QNetworkInformation::Reachability::Disconnected1시스템이 전혀 연결되지 않았을 수 있음을 나타냅니다.
QNetworkInformation::Reachability::Local2시스템이 네트워크에 연결되어 있지만 로컬 네트워크에 있는 디바이스에만 액세스할 수 있음을 나타냅니다.
QNetworkInformation::Reachability::Site3시스템이 네트워크에 연결되어 있지만 로컬 서브넷 또는 인트라넷에 있는 장치에만 액세스할 수 있음을 나타냅니다.
QNetworkInformation::Reachability::Online4시스템이 네트워크에 연결되어 있고 인터넷에 액세스할 수 있음을 나타냅니다.

QNetworkInformation::reachability도 참조하세요 .

[since 6.3] enum class QNetworkInformation::TransportMedium

현재 인터넷에 연결할 수 있는 인식된 미디어를 나열합니다.

상수설명
QNetworkInformation::TransportMedium::Unknown0OS에서 활성 미디어가 없다고 보고하거나, 활성 미디어가 Qt에서 인식되지 않거나, TransportMedium 기능이 지원되지 않는 경우 반환됩니다.
QNetworkInformation::TransportMedium::Ethernet1현재 활성 연결이 이더넷을 사용하고 있음을 나타냅니다. 참고: 이 값은 Windows가 Bluetooth 개인 영역 네트워크에 연결된 경우에도 반환될 수 있습니다.
QNetworkInformation::TransportMedium::Cellular2현재 활성 연결이 셀룰러 네트워크를 사용하고 있음을 나타냅니다.
QNetworkInformation::TransportMedium::WiFi3현재 활성 연결이 Wi-Fi를 사용하고 있음을 나타냅니다.
QNetworkInformation::TransportMedium::Bluetooth4현재 활성 연결이 블루투스를 사용하여 연결되었음을 나타냅니다.

이 열거형은 Qt 6.3에 도입되었습니다.

QNetworkInformation::transportMedium참조하십시오 .

속성 문서

[read-only, since 6.2] isBehindCaptivePortal : const bool

사용자 디바이스가 캡티브 포털 뒤에 있는지 여부를 알려줍니다.

이 속성은 사용자의 디바이스가 현재 캡티브 포털 뒤에 있는 것으로 알려져 있는지 여부를 나타냅니다. 이 기능은 운영 체제의 캡티브 포털 감지에 의존하며 이를 보고하지 않는 시스템에서는 지원되지 않습니다. 이 기능이 지원되지 않는 시스템에서는 항상 false 을 반환합니다.

이 속성은 Qt 6.2에 도입되었습니다.

액세스 함수:

bool isBehindCaptivePortal() const

알림 신호:

void isBehindCaptivePortalChanged(bool state)

[read-only, since 6.3] isMetered : const 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

알림 신호:

void isMeteredChanged(bool isMetered)

[read-only] reachability : const Reachability

이 속성에는 시스템의 현재 네트워크 연결 상태가 저장됩니다.

예상되는 연결 수준을 나타냅니다. 이는 플러그인/운영 체제에서 보고하는 것을 기반으로 한다는 점에 유의하세요. 특정 시나리오에서는 잘못된 것으로 알려져 있습니다. 예를 들어 Windows에서 '온라인' 확인은 기본적으로 Windows가 Microsoft 소유의 서버에 연결하여 수행됩니다. 이 서버가 어떤 이유로든 차단된 경우 온라인에 연결할 수 없는 것으로 간주합니다. 따라서 연결을 시도하기 전에 이 검사를 사전 검사로 사용해서는 안 됩니다.

액세스 기능:

QNetworkInformation::Reachability reachability() const

알림 신호:

void reachabilityChanged(QNetworkInformation::Reachability newReachability)

[read-only, since 6.3] transportMedium : const TransportMedium

이 속성은 애플리케이션의 현재 활성 전송 매체를 보유합니다.

이 속성은 해당 정보를 사용할 수 있는 운영 체제에서 애플리케이션의 현재 활성 전송 매체를 반환합니다.

예를 들어 사용자가 WiFi 네트워크 범위를 벗어나거나 이더넷 케이블을 분리하거나 비행기 모드를 활성화할 때 현재 전송 매체가 변경되면 신호가 방출됩니다.

이 속성은 Qt 6.3에 도입되었습니다.

액세스 기능:

QNetworkInformation::TransportMedium transportMedium() const

알림 신호:

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 을 지원하는 모든 백엔드를 로드하려고 시도합니다. 이 경우에도 실패하면 모든 속성에 대한 기본값만 반환하는 백엔드로 되돌아갑니다.

이 플랫폼과 플러그인 간 매핑은 다음과 같습니다:

플랫폼플러그인 이름
Windowsnetworklistmanager
Apple(macOS/iOS)어플네트워크정보
안드로이드android
Linuxnetworkmanager

이 함수는 앞의 로직으로 충분한 경우 편의를 위해 제공됩니다. 특정 플러그인이 필요한 경우 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 을 반환합니다.

© 2025 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.