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 インスタンスは内部データを共有する。したがって、インスタンスの1つがサービス詳細の発見を開始すると、他のインスタンスも自動的に発見状態に遷移する。

services()も参照のこと 。

void QLowEnergyController::disconnectFromDevice()

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

現在の接続から生じたQLowEnergyService 、QLowEnergyCharacteristic またはQLowEnergyDescriptor インスタンスは、自動的に無効になる。これらのオブジェクトが無効になると、このコントローラオブジェクトが再接続しても、無効のままになります。

コントローラがUnconnectedState の場合、この関数は何もしない。

コントローラがペリフェラルロールの場合、広告を停止し、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バイトである。3 バイトが ATT プロトコルヘッダに必要である。

接続セットアップと 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 のコントローラの場合、この値は、現在接続されているクライアント デバイスのアドレスの1つです。コントローラが現在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 パラメータは新しい値を表します。

この関数は 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 と は、31バイトのユーザーデータに制限される。たとえば、 に128ビットのuidがいくつか追加された場合、アドバタイズされるパケッ トはすべてのuidを含まないかもしれない。既存の制限によって、uuidsが切り捨てられた可能性がある。このような場合、 が追加情報として使用される。scanResponseData advertisingData 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()も参照 。