diff options
author | Andreas Buhr <andreas.buhr@qt.io> | 2021-07-14 20:34:55 +0200 |
---|---|---|
committer | Alex Blasche <alexander.blasche@qt.io> | 2021-07-22 11:58:14 +0000 |
commit | 2e8e58b0eca8b060e02e6b65b57bf14a6a6313ed (patch) | |
tree | e18f554d851fa31a0b0d4016747fec423733e645 /src | |
parent | 380a7752a62a312a601273b0a87828f4eeaacd73 (diff) | |
download | qtconnectivity-2e8e58b0eca8b060e02e6b65b57bf14a6a6313ed.tar.gz |
Create Qt5.15 to 6.2 migration documentation for QtBluetooth
Task-number: QTBUG-90920
Pick-to: 6.2
Change-Id: I1d99a7f6c6cd0f5f890c65c052ea8ceb87760275
Reviewed-by: Alex Blasche <alexander.blasche@qt.io>
Diffstat (limited to 'src')
-rw-r--r-- | src/bluetooth/ApiChangesQt6.txt | 119 | ||||
-rw-r--r-- | src/bluetooth/doc/qt6-changes.qdoc | 149 | ||||
-rw-r--r-- | src/bluetooth/doc/src/bluetooth-index.qdoc | 5 |
3 files changed, 154 insertions, 119 deletions
diff --git a/src/bluetooth/ApiChangesQt6.txt b/src/bluetooth/ApiChangesQt6.txt deleted file mode 100644 index 079d1c94..00000000 --- a/src/bluetooth/ApiChangesQt6.txt +++ /dev/null @@ -1,119 +0,0 @@ -This document lists the API changes done between Qt Bluetooth 5.15 and the first -QtBluetooth release in the Qt 6 series. This file is temporary in nature to keep track of API -changes for further documentation later on. - -General -------- - - - qbluetoothglobal.h was removed. qtbluetoothglobal. is the official header with the same purpose. - - - Every usage of QVector has been replaced by QList. - - - Win32 backend has been removed. There will not be a working Bluetooth backend when Qt is built with mingw. - - - Since there is now only one Windows backend, the logging category qt.bluetooth.winrt was removed. - The corresponding log messages are now in qt.bluetooth.windows. - -QBluetooth namespace --------------------- - - - The enums QBluetooth::Security and QBluetooth::AttAccessConstraint have been changed - to a scoped enums for improved type safety. - -QBluetoothDeviceDiscoveryAgent ------------------------------- - - - QBluetoothDeviceDiscoveryAgent::inquiryType property and related setter/getter & enum were removed. - The API element was never implemented and/or supported. - -QBluetoothDeviceInfo --------------------- - -- manufacturerData() returns a QMultiHash rather than QHash. Since Qt 6 - QMultiHash no longer derives from QHash. - -- DataCompleteness was removed without replacement. - -- setServiceUuids(const QList<QBluetoothUuid>, DataCompleteness) was replaced by - setServiceUuids(const QList<QBluetoothUuid> &uuids) - -- DataCompleteness serviceUuidsCompleteness() const was removed without replacement. - -- QList<QBluetoothUuid> serviceUuids(DataCompleteness *completeness = nullptr) const was replaced by - QList<QBluetoothUuid> serviceUuids() const. - -QBluetoothLocalDevice ---------------------- - -- Pairing agent related API was removed without replacement. This includes pairingConfirmation(bool), - pairingDisplayPinCode(..) & pairingDisplayConfirmation(..). Except for Android and BlueZ 4 there was - never an implementation for it. Bluez 4 support was removed in Qt 6 and Android's implementation - required unobtainable BLUETOOTH_PRIVILEGED for at least parts of the code. - -QLowEnergyService ------------------ - - - Renamed ServiceState enum values: - - "DiscoveryRequired" becomes "RemoteService" - - "DiscoveringServices" becomes "RemoteServiceDiscovering" - - "ServiceDiscovered" becomes "RemoteServiceDiscovered" - This change happens in anticipation that service discovery might become an optional - step in the future. - -QBluetoothUuid --------------- - - - enums ProtocolUuid, ServiceClassUuid, CharacteristicType, and DescriptorType are now scoped enums. - Usage of enum items has to be adapted in user code. - -QLowEnergyController --------------------- - - - Existing ctors and create*() functions with remote QBluetoothAddress parameters have been removed. QBluetoothAddress - is not sufficient to indicate remote devices on Apple systems. It requires UUIDs to "name" devices. This can only - be satisfied by QBluetoothDeviceInfo. - - - Remaining QLowEnergyController ctors have been made private. The createPeripheral() and createCentral() functions - should be used to obtain QLowEnergyController instances. - -QLowEnergyCharacteristic ------------------------- - - - New method clientCharacteristicConfiguration() have been introduced to conveniently obtain the - Client Characteristic Configuration Descriptor. - - Constants CCCDDisable, CCCDEnableNotification, and CCCDEnableIndication have been introduced - which hold the possible values for the Client Characteristic Configuration Descriptor. - - The handle() method is no longer part of the public interface. - -QLowEnergyDescriptor --------------------- - - - The handle() method is no longer part of the public interface. - -QBluetoothTransferManager -------------------------- - - - QBluetoothTransferManager, QBluetoothTransferRequest, and QBluetoothTransferReply have been removed - without replacement. - -QBluetoothSocket -------------------------- - - - QBluetoothSocket::SocketState and QBluetoothSocket::SocketError are now scoped enums. Usage of enum - items has to be adapted in user code. - -QML Interface -------------- - - - The QML interface has been removed because socket programming via QML is not advisable. - QDeclarativeBluetoothService, QDeclarativeBluetoothSocket, and QDeclarativeBluetoothDiscoveryModel - (in QML: BluetoothService, BluetoothSocket, and BluetoothDiscoveryModel) - have been removed without replacement. - -"error" signals ---------------- - - - The "error" signals in QBluetoothDeviceDiscoveryAgent, QBluetoothLocalDevice, QBluetoothServer, - QBluetoothServiceDiscoveryAgent, QBluetoothSocket, QLowEnergyController, and QLowEnergyService - have been renamed to "errorOccurred" to remove ambiguities between the "error" signal and the - "error" getter. diff --git a/src/bluetooth/doc/qt6-changes.qdoc b/src/bluetooth/doc/qt6-changes.qdoc new file mode 100644 index 00000000..468263c5 --- /dev/null +++ b/src/bluetooth/doc/qt6-changes.qdoc @@ -0,0 +1,149 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qtbluetooth-changes-qt6.html + \title Changes to Qt Bluetooth + \ingroup changes-qt-5-to-6 + \brief Migrate QtBluetooth to Qt 6. + + Qt 6 is a result of the conscious effort to make the framework more + efficient and easy to use. + + We try to maintain binary and source compatibility for all the public + APIs in each release. But some changes were inevitable in an effort to + make Qt a better framework. + + In this topic we summarize those changes in QtBluetooth, and provide guidance + to handle them. + + \section1 General + + - qbluetoothglobal.h was removed. qtbluetoothglobal.h is the official header with the same purpose. + + - Every usage of QVector has been replaced by QList. + + - Win32 backend has been removed. There will not be a working Bluetooth backend when Qt is built with mingw. + + - Since there is now only one Windows backend, the logging category qt.bluetooth.winrt was removed. + The corresponding log messages are now in qt.bluetooth.windows. + + \section1 QBluetooth namespace + + - The enums QBluetooth::Security and QBluetooth::AttAccessConstraint have been changed + to a scoped enums for improved type safety. + + \section1 QBluetoothDeviceDiscoveryAgent + + - QBluetoothDeviceDiscoveryAgent::inquiryType property and related setter/getter & enum were removed. + The API element was never implemented and/or supported. + + \section1 QBluetoothDeviceInfo + + - manufacturerData() returns a QMultiHash rather than QHash. Since Qt 6 + QMultiHash is no longer derived from QHash. + + - DataCompleteness was removed without replacement as the related API elements + no longer served a purpose + + - setServiceUuids(const QList<QBluetoothUuid>, DataCompleteness) was replaced by + setServiceUuids(const QList<QBluetoothUuid> &uuids) + + - DataCompleteness serviceUuidsCompleteness() const was removed without replacement. + + - QList<QBluetoothUuid> serviceUuids(DataCompleteness *completeness = nullptr) const was replaced by + QList<QBluetoothUuid> serviceUuids() const. + + \section1 QBluetoothLocalDevice + + - The pairing agent related API was removed without replacement. This includes pairingConfirmation(bool), + pairingDisplayPinCode(..) & pairingDisplayConfirmation(..). Except for Android and BlueZ 4 there was + never an implementation for it. Bluez 4 support was removed in Qt 6 and Android's implementation + required unobtainable BLUETOOTH_PRIVILEGED for at least parts of the code. + + \section1 QLowEnergyService + + - Renamed ServiceState enum values: + - "DiscoveryRequired" becomes "RemoteService" + - "DiscoveringServices" becomes "RemoteServiceDiscovering" + - "ServiceDiscovered" becomes "RemoteServiceDiscovered" + This change happens in anticipation that service discovery might become an optional + step in the future. + + \section1 QBluetoothUuid + + - enums ProtocolUuid, ServiceClassUuid, CharacteristicType, and DescriptorType are now scoped enums. + The usage of enum items has to be adapted in user code. + + \section1 QLowEnergyController + + - Existing ctors and create*() functions with remote QBluetoothAddress parameters have been removed. QBluetoothAddress + is not sufficient to indicate remote devices on Apple systems. It requires UUIDs to "name" devices. This can only + be satisfied by QBluetoothDeviceInfo. + + - Remaining QLowEnergyController ctors have been made private. The createPeripheral() and createCentral() functions + should be used to obtain QLowEnergyController instances. + + \section1 QLowEnergyCharacteristic + + - The new method clientCharacteristicConfiguration() has been introduced to conveniently obtain the + Client Characteristic Configuration Descriptor. + - The constants CCCDDisable, CCCDEnableNotification, and CCCDEnableIndication have been introduced + which hold the possible values for the Client Characteristic Configuration Descriptor. + - The handle() method is no longer part of the public Bluetooth LE interfaces. It's purpose as identifier + for characteristics was replaced. The QLowEnergyCharacteristic instances itself serve as identifier. + + \section1 QLowEnergyDescriptor + + - The handle() method is no longer part of the public Bluetooth LE interfaces. It's purpose as identifier + for descriptors was replaced. The QLowEnergyDescriptor instances itself serve as identifier. + + \section1 QBluetoothTransferManager + + - QBluetoothTransferManager, QBluetoothTransferRequest, and QBluetoothTransferReply have been removed + without replacement. + + \section1 QBluetoothSocket + + - QBluetoothSocket::SocketState and QBluetoothSocket::SocketError are now scoped enums. The usage of enum + items has to be adapted in user code. + + \section1 QML Interface + + - The QML interface has been removed because socket programming via QML is not advisable. + QDeclarativeBluetoothService, QDeclarativeBluetoothSocket, and QDeclarativeBluetoothDiscoveryModel + (in QML: BluetoothService, BluetoothSocket, and BluetoothDiscoveryModel) + have been removed without replacement. + + \section1 "error" signals + + - The "error" signals in QBluetoothDeviceDiscoveryAgent, QBluetoothLocalDevice, QBluetoothServer, + QBluetoothServiceDiscoveryAgent, QBluetoothSocket, QLowEnergyController, and QLowEnergyService + have been renamed to "errorOccurred" to remove ambiguities between the "error" signal and the + "error" getter. + +*/ diff --git a/src/bluetooth/doc/src/bluetooth-index.qdoc b/src/bluetooth/doc/src/bluetooth-index.qdoc index 4de94895..f71f015e 100644 --- a/src/bluetooth/doc/src/bluetooth-index.qdoc +++ b/src/bluetooth/doc/src/bluetooth-index.qdoc @@ -190,6 +190,11 @@ A quick way to enable all QtBluetooth logging is to add the following line to th \endlist \endlist +\section1 Module Evolution + +\l{Changes to Qt Bluetooth} lists important changes in the module +API and functionality that were done for the Qt 6 series of Qt. + \section1 Licenses and Attributions Qt Bluetooth is available under commercial licenses from \l{The Qt Company}. |