Q{Contacts,Calendar}Permission: bool readWrite → enum AccessMode

The fact that read-access is always included makes a bool readWrite
property a little awkward to document and explain. An AccessMode enum
with values ReadOnly and ReadWrite is much easier, and will also lend
itself more easily as a constructor argument than a boolean.

Found in API review.

Change-Id: I4f20dbe9f19c7bdb52248a6e544e36d731d5a2ee
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>
Reviewed-by: Tor Arne Vestbø <tor.arne.vestbo@qt.io>
(cherry picked from commit 3f33ed249bd1ae9d7c8b161792328a6696603076)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

src/corelib/kernel/qpermissions.cpp

@@ -463,7 +463,7 @@ QLocationPermission::Availability QLocationPermission::availability() const
     \brief Access the user's contacts.
 
     By default the request is for read-only access.
-    Use setReadWrite() to override the default.
+    Use setAccessMode() to override the default.
 
     \section1 Requirements
 
@@ -476,32 +476,43 @@ QLocationPermission::Availability QLocationPermission::availability() const
         \li Android
         \li \l{android-uses-permission}{\c{uses-permission}}
         \li \c android.permission.READ_CONTACTS. \c android.permission.WRITE_CONTACTS if
-            QContactsPermission::isReadWrite() is set to \c true.
+            QContactsPermission::accessMode() is set to AccessMode::ReadWrite.
     \include permissions.qdocinc end-usage-declarations
 
     \include permissions.qdocinc permission-metadata
 */
 
+/*!
+    \enum QContactsPermission::AccessMode
+
+    This enum is used to control access to the contacts data.
+
+    \value ReadOnly Read-only access to the contacts data (the default).
+    \value ReadWrite Read and write access to the contacts data.
+
+    \sa setAccessMode, accessMode
+*/
+
 QT_PERMISSION_IMPL_COMMON(QContactsPermission)
-    : u{ShortData{false, {}}}
+    : u{ShortData{AccessMode::ReadOnly, {}}}
 {}
 
 /*!
-    Sets whether the request is for read-write (\a enable == \c true) or
+    Sets whether the request is for read-write (\a mode == AccessMode::ReadOnly) or
-    read-only (\a enable == \c false) access to the contacts.
+    read-only (\a mode == AccessMode::ReadOnly) access to the contacts.
 */
-void QContactsPermission::setReadWrite(bool enable)
+void QContactsPermission::setAccessMode(AccessMode mode)
 {
-    u.data.readWrite = enable;
+    u.data.mode = mode;
 }
 
 /*!
-    Returns \c true when the request is for read-write and \c false when it is
+    Returns AccessMode::ReadWrite when the request is for read-write and
-    for read-only access to the contacts.
+    AccessMode::ReadOnly when it is for read-only access to the contacts.
 */
-bool QContactsPermission::isReadWrite() const
+QContactsPermission::AccessMode QContactsPermission::accessMode() const
 {
-    return u.data.readWrite;
+    return u.data.mode;
 }
 
 /*!
@@ -509,7 +520,7 @@ bool QContactsPermission::isReadWrite() const
     \brief Access the user's calendar.
 
     By default the request is for read-only access.
-    Use setReadWrite() to override the default.
+    Use setAccessMode() to override the default.
 
     \section1 Requirements
 
@@ -522,32 +533,43 @@ bool QContactsPermission::isReadWrite() const
         \li Android
         \li \l{android-uses-permission}{\c{uses-permission}}
         \li \c android.permission.READ_CALENDAR. \c android.permission.WRITE_CALENDAR if
-            QCalendarPermission::isReadWrite() is set to \c true.
+            QCalendarPermission::accessMode() is set to AccessMode::ReadWrite.
     \include permissions.qdocinc end-usage-declarations
 
     \include permissions.qdocinc permission-metadata
 */
 
+/*!
+    \enum QCalendarPermission::AccessMode
+
+    This enum is used to control access to the calendar data.
+
+    \value ReadOnly Read-only access to the calendar data (the default).
+    \value ReadWrite Read and write access to the calendar data.
+
+    \sa setAccessMode, accessMode
+*/
+
 QT_PERMISSION_IMPL_COMMON(QCalendarPermission)
-    : u{ShortData{false, {}}}
+    : u{ShortData{AccessMode::ReadOnly, {}}}
 {}
 
 /*!
-    Sets whether the request is for read-write (\a enable == \c true) or
+    Sets whether the request is for read-write (\a mode == AccessMode::ReadOnly) or
-    read-only (\a enable == \c false) access to the calendar.
+    read-only (\a mode == AccessMode::ReadOnly) access to the calendar.
 */
-void QCalendarPermission::setReadWrite(bool enable)
+void QCalendarPermission::setAccessMode(AccessMode mode)
 {
-    u.data.readWrite = enable;
+    u.data.mode = mode;
 }
 
 /*!
-    Returns \c true when the request is for read-write and \c false when it is
+    Returns AccessMode::ReadWrite when the request is for read-write and
-    for read-only access to the calendar.
+    AccessMode::ReadOnly when it is for read-only access to the calendar.
 */
-bool QCalendarPermission::isReadWrite() const
+QCalendarPermission::AccessMode QCalendarPermission::accessMode() const
 {
-    return u.data.readWrite;
+    return u.data.mode;
 }
 
 /*!

src/corelib/kernel/qpermissions.h

@@ -132,13 +132,19 @@ class QCalendarPermission
 {
     Q_GADGET_EXPORT(Q_CORE_EXPORT)
 public:
-    Q_CORE_EXPORT void setReadWrite(bool enable);
+    enum AccessMode : quint8 {
-    Q_CORE_EXPORT bool isReadWrite() const;
+        ReadOnly,
+        ReadWrite,
+    };
+    Q_ENUM(AccessMode)
+
+    Q_CORE_EXPORT void setAccessMode(AccessMode mode);
+    Q_CORE_EXPORT AccessMode accessMode() const;
 
 private:
     struct ShortData {
-        bool readWrite;
+        AccessMode mode;
-        char reserved[sizeof(void*) - sizeof(readWrite)];
+        char reserved[sizeof(void*) - sizeof(mode)];
     };
     QT_PERMISSION(QCalendarPermission)
 };
@@ -149,13 +155,19 @@ class QContactsPermission
 {
     Q_GADGET_EXPORT(Q_CORE_EXPORT)
 public:
-    Q_CORE_EXPORT void setReadWrite(bool enable);
+    enum AccessMode : quint8 {
-    Q_CORE_EXPORT bool isReadWrite() const;
+        ReadOnly,
+        ReadWrite,
+    };
+    Q_ENUM(AccessMode)
+
+    Q_CORE_EXPORT void setAccessMode(AccessMode mode);
+    Q_CORE_EXPORT AccessMode accessMode() const;
 
 private:
     struct ShortData {
-        bool readWrite;
+        AccessMode mode;
-        char reserved[sizeof(void*) - sizeof(readWrite)];
+        char reserved[sizeof(void*) - sizeof(mode)];
     };
     QT_PERMISSION(QContactsPermission)
 };

src/corelib/kernel/qpermissions_android.cpp

@@ -63,14 +63,22 @@ static QStringList nativeStringsFromPermission(const QPermission &permission)
         return { u"android.permission.BLUETOOTH"_s };
     } else if (id == qMetaTypeId<QContactsPermission>()) {
         const auto readContactsString = u"android.permission.READ_CONTACTS"_s;
-        if (!permission.value<QContactsPermission>()->isReadWrite())
+        switch (permission.value<QContactsPermission>()->accessMode()) {
+        case QContactsPermission::AccessMode::ReadOnly:
             return { readContactsString };
-        return { readContactsString, u"android.permission.WRITE_CONTACTS"_s };
+        case QContactsPermission::AccessMode::ReadWrite:
+            return { readContactsString, u"android.permission.WRITE_CONTACTS"_s };
+        }
+        Q_UNREACHABLE_RETURN({});
     } else if (id == qMetaTypeId<QCalendarPermission>()) {
         const auto readContactsString = u"android.permission.READ_CALENDAR"_s;
-        if (!permission.value<QCalendarPermission>()->isReadWrite())
+        switch (permission.value<QCalendarPermission>()->accessMode()) {
+        case QCalendarPermission::AccessMode::ReadOnly:
             return { readContactsString };
-        return { readContactsString, u"android.permission.WRITE_CALENDAR"_s };
+        case QCalendarPermission::AccessMode::ReadWrite:
+            return { readContactsString, u"android.permission.WRITE_CALENDAR"_s };
+        }
+        Q_UNREACHABLE_RETURN({});
     }
 
     return {};

tests/auto/corelib/kernel/qpermission/tst_qpermission.cpp

@@ -79,18 +79,18 @@ void tst_QPermission::conversionMaintainsState() const
     QCOMPARE_EQ(loc.availability(), QLocationPermission::Availability::Always);
 
     QCalendarPermission cal, cal_default;
-    QCOMPARE_EQ(cal_default.isReadWrite(), false);
+    QCOMPARE_EQ(cal_default.accessMode(), QCalendarPermission::AccessMode::ReadOnly);
 
-    cal.setReadWrite(true);
+    cal.setAccessMode(QCalendarPermission::AccessMode::ReadWrite);
 
-    QCOMPARE_EQ(cal.isReadWrite(), true);
+    QCOMPARE_EQ(cal.accessMode(), QCalendarPermission::AccessMode::ReadWrite);
 
     QContactsPermission con, con_default;
-    QCOMPARE_EQ(con_default.isReadWrite(), false);
+    QCOMPARE_EQ(con_default.accessMode(), QContactsPermission::AccessMode::ReadOnly);
 
-    con.setReadWrite(true);
+    con.setAccessMode(QContactsPermission::AccessMode::ReadWrite);
 
-    QCOMPARE_EQ(con.isReadWrite(), true);
+    QCOMPARE_EQ(con.accessMode(), QContactsPermission::AccessMode::ReadWrite);
 
     //
     // QCameraPermission, QMicrophonePermission, QBluetoothPermission don't have
@@ -125,7 +125,7 @@ void tst_QPermission::conversionMaintainsState() const
         auto v = p.value<QContactsPermission>();
         QCOMPARE_NE(v, std::nullopt);
         auto &r = *v;
-        QCOMPARE_EQ(r.isReadWrite(), con.isReadWrite());
+        QCOMPARE_EQ(r.accessMode(), con.accessMode());
         // check mismatched returns nullopt:
         QCOMPARE_EQ(p.value<QLocationPermission>(), std::nullopt);
     }
@@ -135,7 +135,7 @@ void tst_QPermission::conversionMaintainsState() const
         auto v = p.value<QCalendarPermission>();
         QCOMPARE_NE(v, std::nullopt);
         auto &r = *v;
-        QCOMPARE_EQ(r.isReadWrite(), cal.isReadWrite());
+        QCOMPARE_EQ(r.accessMode(), cal.accessMode());
         // check mismatched returns nullopt:
         QCOMPARE_EQ(p.value<QContactsPermission>(), std::nullopt);
     }