From d25075f3ae6f2900d853d8e7e2ac683479946c47 Mon Sep 17 00:00:00 2001 From: Volker Hilsheimer Date: Mon, 10 Oct 2022 13:19:55 +0200 Subject: Doc: we don't guarantee compatibility for backend classes Similar to QPA, we want to continue to develop the backend APIs between minor releases. Loading a plugin that uses a different Qt version than the application is anyway a bad idea (if supported at all), and for Qt Location specifically we don't want to support this. Change-Id: Ib8b159e1df391bc5a474ddccb6933ab80529264f Reviewed-by: Ivan Solovev (cherry picked from commit 2aea02b53c90a72988edcbb3d7572d2f8fd29ac9) Reviewed-by: Volker Hilsheimer --- src/location/doc/src/qt6-changes.qdoc | 7 +++++-- src/location/maps/qgeocodingmanagerengine.cpp | 11 ++++++++--- src/location/maps/qgeomappingmanagerengine.cpp | 5 +++++ src/location/maps/qgeoroutingmanagerengine.cpp | 5 +++++ src/location/maps/qgeoserviceproviderfactory.cpp | 5 +++++ src/location/places/qplacemanagerengine.cpp | 5 +++++ 6 files changed, 33 insertions(+), 5 deletions(-) diff --git a/src/location/doc/src/qt6-changes.qdoc b/src/location/doc/src/qt6-changes.qdoc index 815edd9d..f5a01d56 100644 --- a/src/location/doc/src/qt6-changes.qdoc +++ b/src/location/doc/src/qt6-changes.qdoc @@ -82,9 +82,12 @@ Functionality that had "labs" status has been removed. This includes the experimental framework for turn-by-turn navigation, MapObjects - \section2 Maps + \section2 Backend Provider API - \section2 Places + The backend provider API is no longer subject to binary and source + compatibility guarantees. + + \section1 Other API changes This section contains API improvements that do not break source compatibility. However they might have an impact on the application logic, diff --git a/src/location/maps/qgeocodingmanagerengine.cpp b/src/location/maps/qgeocodingmanagerengine.cpp index 9d51c31e..6ab62e39 100644 --- a/src/location/maps/qgeocodingmanagerengine.cpp +++ b/src/location/maps/qgeocodingmanagerengine.cpp @@ -57,9 +57,14 @@ QT_BEGIN_NAMESPACE convenience methods to implementers of QGeoServiceProvider plugins who want to provide support for geocoding operations. - In the default implementation, supportsGeocoding() and supportsReverseGeocoding() returns false while - geocode() and reverseGeocode() - cause QGeoCodeReply::UnsupportedOptionError to occur. + \note There are no source or binary compatibility guarantees for the + backend classes. The API is only guaranteed to work with the Qt version it + was developed against. API changes will however only be made in minor + releases. (6.6, 6.7, and so on.) + + In the default implementation, supportsGeocoding() and + supportsReverseGeocoding() returns false while geocode() and + reverseGeocode() cause QGeoCodeReply::UnsupportedOptionError to occur. If the service provider supports geocoding the subclass should provide an implementation of geocode() and call setSupportsGeocoding(true) at diff --git a/src/location/maps/qgeomappingmanagerengine.cpp b/src/location/maps/qgeomappingmanagerengine.cpp index 5d9f41d1..bb2f9114 100644 --- a/src/location/maps/qgeomappingmanagerengine.cpp +++ b/src/location/maps/qgeomappingmanagerengine.cpp @@ -55,6 +55,11 @@ QT_BEGIN_NAMESPACE \brief Provides support functionality for map display with QGeoServiceProvider. + \note There are no source or binary compatibility guarantees for the + backend classes. The API is only guaranteed to work with the Qt version it + was developed against. API changes will however only be made in minor + releases. (6.6, 6.7, and so on.) + The QGeoMappingManagerEngine class provides an interface and convenience methods to implementors of QGeoServiceProvider plugins who want to provide support for displaying and interacting with maps. diff --git a/src/location/maps/qgeoroutingmanagerengine.cpp b/src/location/maps/qgeoroutingmanagerengine.cpp index fe7ad322..7226dad1 100644 --- a/src/location/maps/qgeoroutingmanagerengine.cpp +++ b/src/location/maps/qgeoroutingmanagerengine.cpp @@ -52,6 +52,11 @@ QT_BEGIN_NAMESPACE convenience methods to implementers of QGeoServiceProvider plugins who want to provide access to geographic routing information. + \note There are no source or binary compatibility guarantees for the + backend classes. The API is only guaranteed to work with the Qt version it + was developed against. API changes will however only be made in minor + releases. (6.6, 6.7, and so on.) + Subclasses of QGeoRoutingManagerEngine need to provide an implementation of calculateRoute(). diff --git a/src/location/maps/qgeoserviceproviderfactory.cpp b/src/location/maps/qgeoserviceproviderfactory.cpp index 62007bf1..d58773bd 100644 --- a/src/location/maps/qgeoserviceproviderfactory.cpp +++ b/src/location/maps/qgeoserviceproviderfactory.cpp @@ -51,6 +51,11 @@ QT_BEGIN_NAMESPACE \brief The QGeoServiceProviderFactory class is a factory class used as the plugin interface for services related to geographical information. + \note There are no source or binary compatibility guarantees for the + backend classes. The API is only guaranteed to work with the Qt version it + was developed against. API changes will however only be made in minor + releases. (6.6, 6.7, and so on.) + Implementers must provide a unique combination of providerName() and providerVersion() per plugin. diff --git a/src/location/places/qplacemanagerengine.cpp b/src/location/places/qplacemanagerengine.cpp index cab5603d..971f4621 100644 --- a/src/location/places/qplacemanagerengine.cpp +++ b/src/location/places/qplacemanagerengine.cpp @@ -65,6 +65,11 @@ QT_BEGIN_NAMESPACE implementers of QGeoServiceProvider plugins who want to provide access to place functionality. + \note There are no source or binary compatibility guarantees for the + backend classes. The API is only guaranteed to work with the Qt version it + was developed against. API changes will however only be made in minor + releases. (6.6, 6.7, and so on.) + Application developers need not concern themselves with the QPlaceManagerEngine. Backend implementers however will need to derive from QPlaceManagerEngine and provide implementations for the abstract virtual functions. -- cgit v1.2.3