QLowEnergyService Class

    //PreCondition: service details already discovered
    QLowEnergyCharacteristic batteryLevel = service->characteristic(
                QBluetoothUuid::CharacteristicType::BatteryLevel);
    if (!batteryLevel.isValid())
        return;

    QLowEnergyDescriptor notification = batteryLevel.descriptor(
                QBluetoothUuid::DescriptorType::ClientCharacteristicConfiguration);
    if (!notification.isValid())
        return;

    // establish hook into notifications
    connect(service, SIGNAL(characteristicChanged(QLowEnergyCharacteristic,QByteArray)),
            this, SLOT(characteristicChanged(QLowEnergyCharacteristic,QByteArray)));

    // enable notification
    service->writeDescriptor(notification, QByteArray::fromHex("0100"));

    // disable notification
    //service->writeDescriptor(notification, QByteArray::fromHex("0000"));

    // wait until descriptorWritten() signal is emitted
    // to confirm successful write

    QLowEnergyService *first, *second;
    QLowEnergyController control(remoteDevice);
    control.connectToDevice();

    // waiting for connection

    first = control.createServiceObject(QBluetoothUuid::ServiceClassUuid::BatteryService);
    second = control.createServiceObject(QBluetoothUuid::ServiceClassUuid::BatteryService);
    Q_ASSERT(first->state() == QLowEnergyService::RemoteService);
    Q_ASSERT(first->state() == second->state());

    first->discoverDetails();

    Q_ASSERT(first->state() == QLowEnergyService::RemoteServiceDiscovering);
    Q_ASSERT(first->state() == second->state());

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

[virtual noexcept] QLowEnergyService::~QLowEnergyService()

QLowEnergyService インスタンスを破棄する。

QLowEnergyCharacteristic QLowEnergyService::characteristic(const QBluetoothUuid &uuid) const

uuid にマッチする特性を返す。そうでない場合は無効な特性。

返される特性は、このサービスインスタンスのdiscoverDetails() がまだ呼び出されていないか、またはuuid に一致する特性がない場合は無効である。

characteristics()も参照 。

[signal] void QLowEnergyService::characteristicChanged(const QLowEnergyCharacteristic &characteristic, const QByteArray &newValue)

関連するコントローラオブジェクトがcentral の役割にある場合、このシグナルは、characteristic の値がペリフェラル/デバイス側のイベントによって変更されたときに発行される。その場合、このシグナルの発信は、ペリフェラル上の変更イベントの前に、特性のClientCharacteristicConfiguration 記述子を介して変更通知が有効化されていなければならないことを意味する。この方法の詳細については、above を参照されたい。

コントローラがperipheral の役割にある場合、つまり、サービスオブジェ クトがQLowEnergyController::addService を介して作成された場合、GATTクライアントが書 き込みリクエストまたはコマンドを使用して特性値を書き込んだときに、シグナ ルが発信される。

newValue パラメータには、characteristic の更新値が含まれる。

[signal] void QLowEnergyService::characteristicRead(const QLowEnergyCharacteristic &characteristic, const QByteArray &value)

このシグナルは、characteristic に対する読み取り要求が成功裏にvalue を返したときに発せられる。このシグナルは、 characteristicRead()を呼び出すことでトリガされる。読み取り操作が成功しなかった場合、CharacteristicReadError フラグを使用してerrorOccurred() シグナルが発せられる。

readCharacteristic()も参照 。

[signal] void QLowEnergyService::characteristicWritten(const QLowEnergyCharacteristic &characteristic, const QByteArray &newValue)

このシグナルは、characteristic の値がnewValue に正常に変更されたときに発行される。この変更は、writeCharacteristic()を呼び出すことによってトリガされなければならない。書き込み操作が成功しなかった場合、CharacteristicWriteError フラグを使用してerrorOccurred() シグナルが発行される。

書き込まれた信号の受信は、ターゲット・デバイスが書き込むべき値を受信し、書き込 み要求のステータスを報告したことを示すものとみなすことができる。

writeCharacteristic()も参照 。

QList<QLowEnergyCharacteristic> QLowEnergyService::characteristics() const

このQLowEnergyService インスタンスに関連付けられたすべての特性を返す。

このサービスインスタンスのdiscoverDetails() がまだ呼び出されていないか、既知の特性がない場合、返されるリストは空である。

characteristic()、state()、およびdiscoverDetails()も参照 。

bool QLowEnergyService::contains(const QLowEnergyCharacteristic &characteristic) const

characteristic がこのサービスに属している場合はtrue を返し、そうでない場合はfalse を返す。

characteristics() にcharacteristic が含まれている場合、特性はサービスに属する。

bool QLowEnergyService::contains(const QLowEnergyDescriptor &descriptor) const

descriptor がこのサービスに属している場合はtrue を返し、そうでない場合はfalse を返す。

[signal] void QLowEnergyService::descriptorRead(const QLowEnergyDescriptor &descriptor, const QByteArray &value)

このシグナルは、descriptor に対する読み取り要求がそのvalue を正常に返したときに発せられる。このシグナルは、descriptorRead()を呼び出すことでトリガされる。読み取り操作が成功しなかった場合、DescriptorReadError フラグを使用してerrorOccurred() シグナルが発行される。

readDescriptor()も参照 。

[signal] void QLowEnergyService::descriptorWritten(const QLowEnergyDescriptor &descriptor, const QByteArray &newValue)

このシグナルは、descriptor の値がnewValue に正常に変更されたときに発行される。 関連するコントローラオブジェクトがcentral ロールに属している場合、この変更は、writeDescriptor() を呼び出すことで発生する。そうでない場合、このシグナルは、GATTクライアントから各ディスクリプタへの書 き込み要求またはコマンドの結果である。

writeDescriptor()も参照のこと 。

void QLowEnergyService::discoverDetails(QLowEnergyService::DiscoveryMode mode = FullDiscovery)

サービスの含まれるサービス、特性、およびそれらに関連する記述子の発見を開始する。

発見プロセスはstateChanged() シグナルによって示される。生成後、サービスはDiscoveryRequired 状態となる。discoverDetails()を呼び出すと、DiscoveringService に遷移する。詳細の発見が完了すると、ServiceDiscovered 状態に遷移する。遷移のたびに、stateChanged （）シグナルが発せられる。引数mode に応じて、FullDiscovery またはSkipValueDiscovery が実行される。いずれにせよ、すべてのサービスと特性が発見される。FullDiscovery は進行し、すべての特性値と記述子を読み込む。SkipValueDiscovery は、特性値と記述子を読み込まない。SkipValueDiscovery には2つの利点がある。第一に、より高速である。第2に、一部のデバイスで、特性値や記述子を読み取り可能であると誤って宣伝するバグを回避できるが、それにもかかわらず読み取りを許可しない。これは予測不可能な動作を引き起こす可能性がある。SkipValueDiscovery の後、特性または記述子の値にアクセスする前に、readCharacteristic() /readDescriptor() を呼び出し、それらが正常に終了するのを待つ必要がある。

引数mode は Qt 6.2 で導入されました。

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

QLowEnergyService::ServiceError QLowEnergyService::error() const

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

[signal, since 6.2] void QLowEnergyService::errorOccurred(QLowEnergyService::ServiceError newError)

このシグナルは、エラーが発生したときに発せられます。newError パラメータには、発生したエラーが記述されます。

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

QList<QBluetoothUuid> QLowEnergyService::includedServices() const

現在のサービスに含まれるすべてのサービスのUUIDを返します。

このサービスインスタンスのdiscoverDetails （）がまだ呼び出されていないか、既知の特徴がない場合、返されるリストは空になります。

インクルードされたサービスに、さらに別のサービスが含まれている可能性がある。そのような第2レベルのインクルードは、関連する第1レベルQLowEnergyService インスタンス経由で取得されなければならない。技術的には、これは循環依存を作成する可能性があります。

QLowEnergyController::createServiceObject()は、各UUIDのサービスインスタンスを取得するために使用されるべきである。

createServiceObject()も参照のこと 。

void QLowEnergyService::readCharacteristic(const QLowEnergyCharacteristic &characteristic)

characteristic の値を読み込む。操作が成功すると、characteristicRead() シグナルが発せられ、そうでない場合はCharacteristicReadError が設定される。一般に、QLowEnergyCharacteristic::Read プロパティが設定されていれば、characteristic は読み取り可能である。

同じリモートデバイスに対するすべての記述子および特性要求は、直列化される。複数の要求を同時に発行する場合、キューが使用される。キューは、同じ特性に対する重複した読み取り要求を排除しない。

特性は、サービスがServiceDiscovered 状態にあり、サービスに属している場合にのみ読み出すことができる。これらの条件のいずれかが真でない場合、QLowEnergyService::OperationError が設定される。

characteristicRead() およびwriteCharacteristic()も参照 。

void QLowEnergyService::readDescriptor(const QLowEnergyDescriptor &descriptor)

descriptor の値を読み取る。操作が成功した場合、descriptorRead() シグナルが発せられ、そうでない場合、DescriptorReadError が設定される。

同じリモート・デバイスに対するすべての記述子および特性要求は直列化される。複数の要求を同時に発行する場合、キューが使用される。キューは、同じ記述子に対する重複読み出し要求を排除しない。

サービスがServiceDiscovered 状態であり、記述子がサービスに属している場合にのみ、記述子を読み出すことができる。これらの条件のいずれかが真でない場合、QLowEnergyService::OperationError が設定される。

descriptorRead() およびwriteDescriptor()も参照のこと 。

QString QLowEnergyService::serviceName() const

サービス名を返す。そうでない場合は空文字列。

返される名前は、serviceUuid() がよく知られた UUID である場合にのみ取得できる。

QBluetoothUuid QLowEnergyService::serviceUuid() const

サービスの UUID を返します。そうでない場合は null UUID を返します。

QLowEnergyService::ServiceState QLowEnergyService::state() const

サービスの現在の状態を返す。

デバイスのサービスが初めてインスタンス化された場合、オブジェクトの状態はDiscoveryRequired である。周辺デバイス上の同じサービスを指すすべてのサービスオブジェクトの状態は、常に等しくなります。これは、内部オブジェクトデータの共有性によるものです。したがって、最初のインスタンスの後に作成されたサービスオブジェクトのインスタンスは、既に存在するインスタンスと同じ状態を持つ。

QLowEnergyController がリモートデバイスから切断されると、サービスは無効になります。無効なサービスは、切断イベント発生時の内部状態を保持します。このことは、サービスの詳細が発見されると、無効なサービスからも取得できることを意味する。これは、デバイス接続が確立され、サービス詳細が取得され、次のデバイスが周辺デバイスに接続できるようにデバイスが即座に切断されるシナリオを許容する。

しかしながら、通常の状況では、サービスとその詳細の繰り返しの発見を避けるために、接続は維持されるべきである。発見にはしばらく時間がかかり、クライアントは継続的な変更通知を購読することができる。

stateChanged()も参照のこと 。

[signal] void QLowEnergyService::stateChanged(QLowEnergyService::ServiceState newState)

このシグナルは、サービスの状態が変化したときに発行される。newState はstate() からも取得できる。

state() も参照 。

QLowEnergyService::ServiceTypes QLowEnergyService::type() const

サービスのタイプを返します。

void QLowEnergyService::writeCharacteristic(const QLowEnergyCharacteristic &characteristic, const QByteArray &newValue, QLowEnergyService::WriteMode mode = WriteWithResponse)

characteristic の値としてnewValue を書き込む。 正確なセマンティクスは、関連するコントローラオブジェク トのロールによって異なる。

セントラルロール

コールの結果、リモートペリフェラルへのライト要求またはコマンドが発生する。CharacteristicWriteError 操作が成功すると、characteristicWritten() シグナルが発信される。この関数を呼び出しても、現在の書き込み要求の後に周辺機器自身が再び値を変更しない限り、characteristicChanged() シグナルはトリガされません。

mode パラメータは、リモートデバイスが書き込み確認を送るべきかどうかを決定します。書き込まれるcharacteristic は、関連する書き込みモードをサポートしなければなりません。特性がサポートする書き込みモードは、QLowEnergyCharacteristic::Write とQLowEnergyCharacteristic::WriteNoResponse プロパティで示される。

同じリモートデバイスに対するすべての記述子および特性の書き込み要求は、直列化される。複数の書き込み要求を同時に発行する場合、待ち行列が採用される。キューは、同じ特性に対する重複した書き込み要求を排除しない。例えば、同じ記述子が値Aに設定され、その直後に値Bに設定された場合、2つの書 き込み要求は、指定された順序で実行される。

特性は、このサービスがServiceDiscovered の状態にあり、サービスに属している場合にのみ書き込むことができます。これらの条件のいずれかが真でない場合、QLowEnergyService::OperationError が設定されます。

ペリフェラルの役割

呼び出しの結果、特性の値がローカルデータベースで更新される。

クライアントが現在接続されていて、特性に対する通知または指示を有効にしている場合、それぞれの情報が送信される。デバイスが特性に対する通知または指示を有効にしており、そのデバイスが現在接続されていないが、そのデバイスとローカルデバイスの間に結合が存在する場合、通知または指示は、次の再接続時に送信される。

特性値の長さに制約があり、newValue がその制約に従わない場合、動作は特定されない。

QLowEnergyService::characteristicWritten() およびQLowEnergyService::readCharacteristic()も参照のこと 。

void QLowEnergyService::writeDescriptor(const QLowEnergyDescriptor &descriptor, const QByteArray &newValue)

descriptor の値としてnewValue を書き込む。正確なセマンティクスは、関連するコントローラオブジェクトのロールに依存する。

セントラルロール

この関数を呼び出すと、リモートデバイスへの書き込み要求が発生する。操作が成功した場合、descriptorWritten()シグナルが発行される。そうでない場合、DescriptorWriteError が発行される。

同じリモート・デバイスに対するすべての記述子および特性要求は直列化される。複数の書き込み要求を同時に発行する場合、キューが使用される。キューは、同じ記述子に対する重複した書き込み要求を排除しない。例えば、同じ記述子に値Aが設定され、その直後に値Bが設定された場合、2つの書き込み要求は所定の順序で実行される。

記述子は、このサービスがServiceDiscovered 、サービスに属している場合にのみ書き込むことができる。これらの条件のいずれかが真でない場合、QLowEnergyService::OperationError が設定される。

ペリフェラルの役割

値はローカルサービスデータベースに書き込まれる。newValue の内容がdescriptor に対して有効でない場合、動作は指定されない。

descriptorWritten() およびreadDescriptor()も参照してください 。