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>
voidonReachabilityChanged(QNetworkInformation::Reachability reachability) {
switch(reachability) {
caseQNetworkInformation::Reachability::Unknown:
qDebug() << "Network reachability is unknown.";
break;
caseQNetworkInformation::到達可能性::接続切れ:
qDebug() << "Network is disconnected.";
break;
caseQNetworkInformation::到達可能性::ローカル:
qDebug() << "Network is locally reachable.";
break;
caseQNetworkInformation::到達可能性::サイト:
qDebug() << "Network can reach the site.";
break;
caseQNetworkInformation::Reachability::Online:
qDebug() << "Network is online.";
break;
}
}
intmain(intargc, 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());
returna.exec();
}より高度なユースケースでは、開発者は特定の機能や設定に基づいてバックエンドを読み込むことを好む場合があります。loadBackendByFeatures() を使用すると、伝送媒体や信号強度の報告など、特定の機能セットをサポートするバックエンドを選択できます。あるいは、loadBackendByName() を使用すると、名前でプラグインを読み込むことができ、これにはプラットフォーム固有の、あるいはカスタムなバックエンドの実装を含めることができます。
QNetworkInformation はシングルトンであり、最初の読み込みが成功してからQCoreApplication オブジェクトが破棄されるまで存続します。QCoreApplication オブジェクトを破棄して再作成する場合は、プラグインを再初期化するために再度読み込む必要があります。
注: このクラスはシングルトンであると同時に `QCoreApplication` に依存しているため 、`QNetworkInformation` は常に `QCoreApplication ` オブジェクトと同じスレッドで最初に読み込む必要があります。これは、オブジェクトがこのスレッドで破棄されること、また、バックエンド固有のさまざまなコンポーネントが、作成されたのと同じスレッドで破棄されることを前提としている場合があるためです。
QNetworkInformation の利用例の一つとして、ネットワーク接続状態の監視が挙げられます。reachability() は、基盤となるオペレーティングシステムやプラグインから報告される情報に基づき、システムがオンラインとみなされるかどうかを示します。ただし、この情報は必ずしも正確であるとは限りません。 たとえば、Windows では、オンラインチェックが Microsoft が所有するサーバーへの接続状況に依存している場合があります。そのサーバーに到達できない場合(ファイアウォールのルールなどが原因)、システムは誤ってオフラインであると報告してしまう可能性があります。 したがって、reachability() は、ネットワーク接続を試みる前の決定的な事前チェックとして使用するのではなく、接続状態の一般的な指標として扱うべきです。
reachability() を効果的に使用するには、アプリケーションが接続先の種類を正しく把握している必要があります。例えば、接続先がローカル IP アドレスである場合は、Reachability::Local またはReachability::Site で十分かもしれません。接続先がパブリックインターネット上にある場合は、Reachability::Online が必要です。この文脈が欠けていると、報告された到達可能性を解釈する際に、実際のネットワークアクセスについて誤った仮定を招く恐れがあります。
警告: より詳細なReachability::Site およびReachability::Local オプションをサポートしているのは、LinuxとWindowsのみです 。AndroidおよびAppleプラットフォームでは、reachability()は「オンライン」、「オフライン」、または「不明」のみを報告することに制限されています。したがって、ローカルまたはサイトレベルの接続性を検出することに依存するロジックには、適切なプラットフォームチェックまたはフォールバックを含める必要があります。
// IPアドレスが「ローカル」であるかどうかを判定する簡単なヘルパー関数
boolisLocalAddress(constQHostAddress&address)
{
returnaddress.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();
}
intmain(intargc, 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(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も参照してください 。
メンバ型のドキュメント
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 が Bluetooth パーソナルエリアネットワークに接続されている場合にも返されることがあります。 |
QNetworkInformation::TransportMedium::Cellular | 2 | 現在アクティブな接続が携帯電話ネットワークを使用していることを示します。 |
QNetworkInformation::TransportMedium::WiFi | 3 | 現在アクティブな接続が Wi-Fi を使用していることを示します。 |
QNetworkInformation::TransportMedium::Bluetooth | 4 | 現在アクティブな接続が Bluetooth を使用して接続されていることを示します。 |
この列挙型は 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` の場合は、ログや診断情報のアップロードを控えるのが望ましいでしょう。
voiduploadLogFile()
{
...
}
intmain(intargc, 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()
platform-default バックエンドの読み込みを試みます。
注:バージョン 6.7以降では、 プラットフォームのデフォルトのバックエンドが利用できない場合や読み込みに失敗した場合、Reachability をサポートする任意のバックエンドを読み込もうとします。これにも失敗した場合は、すべてのプロパティに対してデフォルト値のみを返すバックエンドにフォールバックします。
このプラットフォームとプラグインの対応関係は以下の通りです:
| プラットフォーム | プラグイン名 |
|---|---|
| Windows | networklistmanager |
| Apple (macOS/iOS) | Appleネットワーク情報 |
| Android | Android |
| Linux | networkmanager |
この関数は、前述のロジックで十分である場合に便宜上提供されています。特定のプラグインが必要な場合は、代わりに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.