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つの利点があります。第一に、処理が高速です。 第二に、特性や記述子を誤って「読み取り可能」と広告しているにもかかわらず、実際には読み取りを許可していない一部のデバイスにおけるバグを回避できます。これは予期しない動作を引き起こす可能性があります。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に対応するサービスインスタンスを取得するには、`xml-ph-0000@deepl.internal()` を使用する必要があります。

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

void QLowEnergyService::readCharacteristic(const QLowEnergyCharacteristic &characteristic)

characteristic の値を読み取ります。操作が成功した場合は、characteristicRead()シグナルが出力され、失敗した場合はCharacteristicReadError が設定されます。一般的に、characteristic は、そのQLowEnergyCharacteristic::Read プロパティが設定されている場合に読み取り可能です。

同じリモートデバイスに対するすべてのデскриプタおよび特性のリクエストはシリアライズされる。複数のリクエストを同時に発行する際にはキューが使用される。このキューは、同じ特性に対する重複した読み取りリクエストを排除するものではない。

特性は、サービスが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 を書き込みます。具体的な動作は、関連付けられたコントローラーオブジェクトがどのロールにあるかによって異なります。

中央ロール

この呼び出しにより、リモート周辺機器への書き込み要求またはコマンドが発行されます。操作が成功した場合は、characteristicWritten() シグナルが発信されます。失敗した場合は、CharacteristicWriteError が設定されます。この関数を呼び出しても、現在の書き込み要求後に周辺機器自体が値を再度変更しない限り、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()も参照してください 。