QLowEnergyController Class

メンバ関数のドキュメント

[virtual noexcept] QLowEnergyController::~QLowEnergyController()

QLowEnergyController のインスタンスを破棄します。

QLowEnergyService *QLowEnergyController::addService(const QLowEnergyServiceData &service, QObject *parent = nullptr)

service から取得したparent を使用して、QLowEnergyService オブジェクトを構築し、返します。コントローラーは、PeripheralRole およびUnconnectedState に存在している必要があります。また、service オブジェクトは有効である必要があります。

stopAdvertising()、disconnectFromDevice()、およびQLowEnergyServiceData::addIncludedServiceも参照してください 。

void QLowEnergyController::connectToDevice()

リモートのBluetooth Low Energyデバイスに接続します。

コントローラのstate()がUnconnectedState と等しくない場合、この関数は何も実行しません。接続が正常に確立されると、connected()シグナルが発信されます。

Linux/BlueZシステムでは、このクラスの2つのインスタンスを使用して同じリモートデバイスに接続することはできません。この関数を2回目に呼び出すと、エラーが発生して失敗する可能性があります。この制限は、将来のリリースで解除される可能性があります。

disconnectFromDevice()も参照してください 。

[signal] void QLowEnergyController::connected()

このシグナルは、コントローラーがリモートのLow Energyデバイスへの接続に成功した場合（コントローラーがCentralRole 状態にある場合）、またはコントローラーに接続されたリモートのLow Energyデバイスが存在する場合（コントローラーがPeripheralRole 状態にある場合）に送信されます。 iOS、macOS、およびAndroidでは、コントローラーがPeripheralRole 状態にある場合、このシグナルは信頼性が低くなります。iOSおよびmacOSでは、コントローラーは、あるセントラルが特性や記述子の読み書きを試みた瞬間に、そのセントラルが当社の周辺機器に接続されていると推測するだけです。 Androidでは、コントローラーは接続されているすべてのGATTデバイスを監視します。LinuxのBlueZ DBus周辺機器バックエンドでは、リモコンが初めて特性または記述子の読み取り／書き込みを行った時点で、接続済みとみなされます。

[signal] void QLowEnergyController::connectionUpdated(const QLowEnergyConnectionParameters &newParameters)

このシグナルは、接続パラメータが変更されたときに発火します。これは、requestConnectionUpdate() の呼び出しの結果として発生する場合もあれば、接続の相手側が新しいパラメータを要求したなどの他の理由による場合もあります。新しい値は、newParameters から取得できます。

requestConnectionUpdate()も参照してください 。

[static] QLowEnergyController *QLowEnergyController::createCentral(const QBluetoothDeviceInfo &remoteDevice, QObject *parent = nullptr)

CentralRole に属し、親オブジェクトとしてparent を持つ、このクラスの新しいオブジェクトを返します。remoteDevice は、後で接続が確立されるデバイスを指します。

コントローラは、接続管理にローカルのデフォルト Bluetooth アダプタを使用します。

「QLowEnergyController::CentralRole」も参照してください 。

[static] QLowEnergyController *QLowEnergyController::createCentral(const QBluetoothDeviceInfo &remoteDevice, const QBluetoothAddress &localDevice, QObject *parent = nullptr)

parent を設定した、このクラスの新しいインスタンスを返します。

remoteDevice には、このオブジェクトが後で接続を試みるリモートBluetooth Low Energyデバイスのアドレスが含まれている必要があります。

接続は、localDevice を通じて確立されます。localDevice が無効な場合、ローカルのデフォルトデバイスが自動的に選択されます。localDevice で、ローカルの Bluetooth アダプタではないローカルデバイスが指定されている場合、connectToDevice() が呼び出されると、error() はInvalidBluetoothAdapterError に設定されます。

なお、接続に使用するローカルデバイスの指定は、BlueZ を使用する場合にのみ可能です。その他のプラットフォームでは、この機能はサポートされていません。

[static] QLowEnergyController *QLowEnergyController::createPeripheral(QObject *parent = nullptr)

PeripheralRole 内にあり、親オブジェクトがparent である、このクラスの新しいオブジェクトを返します。通常、次の手順として、いくつかのサービスを追加し、最後に返されたオブジェクトに対してstartAdvertising() を呼び出します。

コントローラは、接続管理にローカルのデフォルト Bluetooth アダプタを使用します。

QLowEnergyController::PeripheralRoleも参照してください 。

[static, since 6.2] QLowEnergyController *QLowEnergyController::createPeripheral(const QBluetoothAddress &localDevice, QObject *parent = nullptr)

PeripheralRole に属し、親オブジェクトがparent で、localDevice を使用している、このクラスの新しいオブジェクトを返します。通常、次の手順として、いくつかのサービスを追加し、最後に返されたオブジェクトに対してstartAdvertising() を呼び出します。

周辺機器はlocalDevice に基づいて作成されます。localDevice が無効な場合、ローカルのデフォルトデバイスが自動的に選択されます。localDevice で、ローカルの Bluetooth アダプタではないローカルデバイスが指定されている場合、error() はInvalidBluetoothAdapterError に設定されます。

localDevice の指定は、Linuxでのみサポートされています。その他のプラットフォームでは、このパラメータは無視されます。

この関数は Qt 6.2 で導入されました。

「QLowEnergyController::PeripheralRole」も参照してください 。

QLowEnergyService *QLowEnergyController::createServiceObject(const QBluetoothUuid &serviceUuid, QObject *parent = nullptr)

serviceUuid で表されるサービスのインスタンスを作成します。serviceUuid パラメータは、services() を通じて取得されている必要があります。

呼び出し元は、返されたポインタの所有権を取得し、parent パラメータをデフォルトの所有者として渡すことができます。

リモートデバイス上でserviceUuid を持つサービスが見つからない場合、またはコントローラが切断されている場合、この関数は null ポインタを返します。

この関数は、セカンダリ・サービスのインスタンスも返すことができます。サービス間の包含関係は、QLowEnergyService::includedServices() によって表現できます。

同じサービス UUID を使用してこの関数が複数回呼び出された場合、返されるQLowEnergyService インスタンスは内部データを共有します。したがって、いずれかのインスタンスがサービスの詳細の検出を開始すると、他のインスタンスも自動的に検出状態に移行します。

services()も参照してください 。

void QLowEnergyController::disconnectFromDevice()

リモートデバイスとの接続を切断します。

現在の接続によって生成されたQLowEnergyService 、QLowEnergyCharacteristic 、またはQLowEnergyDescriptor のインスタンスは、すべて自動的に無効化されます。これらのオブジェクトのいずれかが一度無効化されると、このコントローラオブジェクトが再接続したとしても、その状態は維持されます。

コントローラがUnconnectedState の状態にある場合、この関数は何も実行しません。

コントローラが周辺機器（peripheral）の役割にある場合、この関数はアドバタイジングを停止し、以前にaddService() を通じて追加されたすべてのサービスを削除します。QLowEnergyController インスタンスを再利用するには、アプリケーションがサービスを再度追加し、startAdvertising() を呼び出してアドバタイジングモードを再開する必要があります。

connectToDevice()も参照してください 。

[signal] void QLowEnergyController::disconnected()

このシグナルは、コントローラーがリモートLow Energyデバイスから切断されたとき、またはその逆の場合に発行されます。iOSおよびmacOSでは、コントローラーがPeripheralRole 状態にある場合、このシグナルは信頼性がありません。Androidでは、最後に接続されていたデバイスが切断されたときにこのシグナルが発行されます。BlueZ DBusバックエンドでは、属性にアクセスした最後のクライアントが切断された時点で、コントローラーは切断されたものとみなされます。

void QLowEnergyController::discoverServices()

サービスディスカバリプロセスを開始します。

ディスカバリの進行状況は、serviceDiscovered() シグナルによって示されます。プロセスが完了すると、discoveryFinished() シグナルが発信されます。

コントローラインスタンスが接続されていない場合、またはコントローラーがすでにサービス検出を実行済みの場合、この関数は何も行いません。

[signal] void QLowEnergyController::discoveryFinished()

このシグナルは、実行中のサービスディスカバリが終了したときに発行されます。ディスカバリ処理がエラーで終了した場合は、このシグナルは発行されません。

このシグナルは、コントローラーがCentralRole 状態にある場合にのみ発行されます。

discoverServices() およびerror()も参照してください 。

QLowEnergyController::Error QLowEnergyController::error() const

最後に発生したエラー、またはNoError を返します。

[signal, since 6.2] void QLowEnergyController::errorOccurred(QLowEnergyController::Error newError)

このシグナルは、エラーが発生した際に発火します。newError パラメータは、発生したエラーの詳細を記述します。

この関数はQt 6.2で導入されました。

error() およびerrorString()も参照してください 。

QString QLowEnergyController::errorString() const

最後に発生したエラーを文字列として返します。この文字列は翻訳されています。

QBluetoothAddress QLowEnergyController::localAddress() const

通信に使用されているローカルBluetoothアダプタのアドレスを返します。

このクラスインスタンスに対してデフォルトのアダプタの使用が要求されたものの、インスタンス作成時にデフォルトのアダプタが存在しなかった場合、返されるQBluetoothAddress はnullになります。

QBluetoothAddress::isNull()も参照してください 。

[since 6.2] int QLowEnergyController::mtu() const

MTUサイズを返します。

接続の確立時に、ATTのMTUサイズがネゴシエーションされます。このメソッドは、そのネゴシエーションの結果を返します。状況によっては、パケットサイズの最適化に利用できます。1つのパケットで転送できるデータの最大量は、mtu-3バイトです。ATTプロトコルのヘッダーには3バイトが必要です。

接続の確立およびMTUネゴシエーションが行われる前は、デフォルト値である23 が返されます。

すべてのプラットフォームが MTU 値を公開しているわけではありません。そのようなプラットフォーム（例：Linux）では、この関数は常に `-1` を返します。

コントローラがPeripheralRole 状態にある場合、そのコントローラには複数の中央デバイスが接続されている可能性があります。そのような場合、この関数は最後にネゴシエーションされた接続のMTUを返します。

この関数は Qt 6.2 で導入されました。

[signal] void QLowEnergyController::mtuChanged(int mtu)

この信号は、MTUの変更が正常に完了した際に送信されます。mtu は新しい値を表します。

mtu()も参照してください 。

[since 6.5] void QLowEnergyController::readRssi()

readRssi() は、接続されたリモートデバイスの RSSI（受信信号強度インジケータ）を読み取ります。読み取りに成功した場合、RSSI 値はrssiRead() シグナルによって通知されます。

この関数は Qt 6.5 で導入されました。

関連項目： rssiRead()、connectToDevice()、state()、createCentral()、およびerrorOccurred()を参照してください 。

QBluetoothAddress QLowEnergyController::remoteAddress() const

リモート側のBluetooth Low Energyデバイスのアドレスを返します。

CentralRole 内のコントローラの場合、この値は常にコントローラオブジェクトの作成時に渡された値となります。PeripheralRole 内のコントローラの場合、この値は現在接続されているクライアントデバイスのアドレスのいずれかになります。コントローラが現在ConnectedState にない場合、このアドレスは無効となります。

QLowEnergyController::RemoteAddressType QLowEnergyController::remoteAddressType() const

remoteAddress() の型を返します。デフォルトでは、この値はPublicAddress に初期化されます。

setRemoteAddressType()も参照してください 。

QBluetoothUuid QLowEnergyController::remoteDeviceUuid() const

リモート側のBluetooth Low Energyデバイスの一意の識別子を返します。

macOS/iOS/tvOS では、CoreBluetooth は LE デバイスのハードウェアアドレスを公開・受け付けません。その代わりに、開発者は CoreBluetooth によって生成される一意の 128 ビット UUID を使用する必要があります。これらの UUID は、同じセントラル <-> ペリフェラルペア間では不変であり、リモートデバイスへの接続時に使用されます。CentralRole 内のコントローラの場合、この値は常にコントローラオブジェクトの作成時に渡された値となります。PeripheralRole 内のコントローラの場合、この値は無効となります。

QString QLowEnergyController::remoteName() const

コントローラがCentralRole にある場合、リモートのBluetooth Low Energyデバイスの名前を返します。それ以外の場合は、結果は未定義です。

void QLowEnergyController::requestConnectionUpdate(const QLowEnergyConnectionParameters &parameters)

コントローラに対し、parameters に従って接続を更新するよう要求します。要求が成功した場合、connectionUpdated()シグナルが、実際の新しいパラメータとともに発行されます。接続パラメータの詳細については、QLowEnergyConnectionParameters クラスを参照してください。

Androidでは、このパラメータセットの調整は間接的にしか許可されていません。接続パラメータは3つのカテゴリ（高優先度、低優先度、バランス優先度）に分類されます。 各カテゴリには、QLowEnergyConnectionParameters::minimumInterval()、QLowEnergyConnectionParameters::maximumInterval()、およびQLowEnergyConnectionParameters::latency() に対する事前設定済みの値セットが割り当てられています。接続リクエストは非同期操作ですが、Android ではリクエストの結果を通知するコールバックが提供されていません。これは Android 側の既知のバグです。このバグのため、Android ではconnectionUpdated() シグナルが発行されません。

関連項目： connectionUpdated()。

QLowEnergyController::Role QLowEnergyController::role() const

このコントローラーオブジェクトが属するロールを返します。

ロールは、createCentral() またはcreatePeripheral() を使用してQLowEnergyController インスタンスを生成する際に決定されます。

[signal, since 6.5] void QLowEnergyController::rssiRead(qint16 rssi)

このシグナルは、接続されたリモートデバイスのRSSI（受信信号強度インジケータ）の読み取りに成功した後に発火します。rssi パラメータは、新しい値を表します。

この関数は Qt 6.5 で導入されました。

readRssi()も参照してください 。

[signal] void QLowEnergyController::serviceDiscovered(const QBluetoothUuid &newService)

このシグナルは、新しいサービスが検出されるたびに発信されます。newService パラメータには、検出されたサービスのUUIDが含まれます。

このシグナルは、コントローラがCentralRole の状態にある場合にのみ発信されます。

discoverServices() およびdiscoveryFinished()も参照してください 。

QList<QBluetoothUuid> QLowEnergyController::services() const

コントローラがCentralRole にある場合、リモートデバイスが提供するサービスのリストを返します。それ以外の場合は、結果は未定義です。

このリストには、すべてのプライマリおよびセカンダリサービスが含まれます。

createServiceObject()も参照してください 。

void QLowEnergyController::setRemoteAddressType(QLowEnergyController::RemoteAddressType type)

リモートアドレス「type 」を設定します。リモートのBluetooth Low Energyデバイスに接続するには、このタイプの指定が必要です。

この属性は、古い Linux カーネル（v3.3 以下）を搭載した Linux/BlueZ システム、または実行ファイルに対して CAP_NET_ADMIN が設定されていない場合にのみ設定する必要があります。この属性のデフォルト値はRandomAddress です。

remoteAddressType()も参照してください 。

void QLowEnergyController::startAdvertising(const QLowEnergyAdvertisingParameters &parameters, const QLowEnergyAdvertisingData &advertisingData, const QLowEnergyAdvertisingData &scanResponseData = QLowEnergyAdvertisingData())

parameters で設定されたパラメータを使用して、advertisingData およびscanResponseData に指定されたデータのアドバタイズを開始します。コントローラはPeripheralRole 内に配置する必要があります。parameters でアドバタイズが接続可能であるように指定されている場合、この関数は着信クライアント接続のリスニングも開始します。

scanResponseData の指定は必須ではありません。これは、parameters の特定の構成では適用されないためです。advertisingData およびscanResponseData のユーザーデータは31バイトに制限されています。例えば、advertisingData に複数の128ビットUUIDが追加された場合、アドバタイズされるパケットにはすべてのUUIDが含まれない可能性があります。 この既存の制限により、UUIDが切り捨てられた可能性があります。そのような場合は、追加情報としてscanResponseData を使用することができます。

BlueZのDBusバックエンドでは、スキャン応答でどのデータを使用するかをBlueZが決定します。そのため、すべてのアドバタイズメントデータは、メインのadvertisingData パラメータに設定することを推奨します。アドバタイズメントデータとスキャン応答データの両方が設定されている場合、スキャン応答データが優先されます。

このオブジェクトが現在UnconnectedState に含まれていない場合、何も起こりません。

stopAdvertising()も参照してください 。

QLowEnergyController::ControllerState QLowEnergyController::state() const

コントローラの現在の状態を返します。

stateChanged()も参照してください 。

[signal] void QLowEnergyController::stateChanged(QLowEnergyController::ControllerState state)

このシグナルは、コントローラの状態が変化したときに発せられます。新しいstate は、state() を通じて取得することもできます。

state()も参照してください 。

void QLowEnergyController::stopAdvertising()

このオブジェクトが現在アドバタイジング状態にある場合、アドバタイジングを停止します。

この関数が動作するには、コントローラーが `PeripheralRole ` 状態にある必要があります。また、この関数は、以前に `addService()` を通じて追加されたサービスを無効化しません。

startAdvertising()も参照してください 。