QWebEnginePermission Class

A QWebEnginePermission is an object used to access and modify the state of a single permission that's been granted or denied to a specific origin URL. More...

Header: #include <QWebEnginePermission>
CMake: find_package(Qt6 REQUIRED COMPONENTS WebEngineCore)
target_link_libraries(mytarget PRIVATE Qt6::WebEngineCore)
qmake: QT += webenginecore
Since: Qt 6.8
In QML: webEnginePermission

Public Types

enum class PermissionType { MediaAudioCapture, MediaVideoCapture, MediaAudioVideoCapture, DesktopVideoCapture, DesktopAudioVideoCapture, …, Unsupported }
enum class State { Invalid, Ask, Granted, Denied }

Properties

Public Functions

void deny() const
void grant() const
bool isValid() const
QUrl origin() const
QWebEnginePermission::PermissionType permissionType() const
void reset() const
QWebEnginePermission::State state() const

Static Public Members

bool isPersistent(QWebEnginePermission::PermissionType permissionType)

Detailed Description

The typical usage pattern is as follows:

  1. A website requests a specific permission, triggering the QWebEnginePage::permissionRequested() signal;
  2. The signal handler triggers a prompt asking the user whether they want to grant the permission;
  3. When the user has made their decision, the application calls grant() or deny();

Alternatively, an application interested in modifying already granted permissions may use QWebEngineProfile::listAllPermissions() to get a list of existing permissions associated with a profile, or QWebEngineProfile::queryPermission() to get a QWebEnginePermission object for a specific permission.

The origin() property can be used to query which origin the QWebEnginePermission is associated with, while the permissionType() property describes the type of the requested permission. A website origin is the combination of its scheme, hostname, and port. Permissions are granted on a per-origin basis; thus, if the web page https://www.example.com:12345/some/page.html requests a permission, it will be granted to the origin https://www.example.com:12345/.

QWebEnginePermission::PermissionType describes all the permission types Qt WebEngine supports. Only some permission types are remembered between browsing sessions; they are persistent. Non-persistent permissions query the user every time a website requests them. You can check whether a permission type is persistent at runtime using the static method QWebEnginePermission::isPersistent().

Persistent permissions are stored inside the active QWebEngineProfile, and their lifetime depends on the value of QWebEngineProfile::persistentPermissionsPolicy(). By default, named profiles store their permissions on disk, whereas off-the-record ones store them in memory (and destroy them when the profile is destroyed). A stored permission will not query the user the next time a website requests it; instead it will be automatically granted or denied, depending on the resolution the user picked initially. To erase a stored permission, call reset() on it.

A non-persistent permission, on the other hand, is only usable until the related QWebEnginePage performs a navigation to a different URL, or is destroyed.

You can check whether a QWebEnginePermission is in a valid state using its isValid() property. For invalid objects, calls to grant(), deny(), or reset() will do nothing, while calls to state() will always return QWebEnginePermission::Invalid.

See also QWebEnginePage::permissionRequested(), QWebEngineProfile::queryPermission(), and QWebEngineProfile::listAllPermissions().

Member Type Documentation

enum class QWebEnginePermission::PermissionType

This enum type holds the type of the requested permission type:

ConstantValueDescription
QWebEnginePermission::PermissionType::MediaAudioCapture1Access to a microphone, or another audio source. This permission is not persistent.
QWebEnginePermission::PermissionType::MediaVideoCapture2Access to a webcam, or another video source. This permission is not persistent.
QWebEnginePermission::PermissionType::MediaAudioVideoCapture3Combination of MediaAudioCapture and MediaVideoCapture. This permission is not persistent.
QWebEnginePermission::PermissionType::DesktopVideoCapture4Access to the contents of the user's screen. This permission is not persistent.
QWebEnginePermission::PermissionType::DesktopAudioVideoCapture5Access to the contents of the user's screen, and application audio. This permission is not persistent.
QWebEnginePermission::PermissionType::MouseLock6Locks the pointer inside an element on the web page. This permission is not persistent.
QWebEnginePermission::PermissionType::Notifications7Allows the website to send notifications to the user. This permission is persistent.
QWebEnginePermission::PermissionType::Geolocation8Access to the user's physical location. This permission is persistent.
QWebEnginePermission::PermissionType::ClipboardReadWrite9Access to the user's clipboard. This permission is persistent.
QWebEnginePermission::PermissionType::LocalFontsAccess10Access to the fonts installed on the user's machine. Only available on desktops. This permission is persistent.
QWebEnginePermission::PermissionType::Unsupported0An unsupported permission type.

Note: Non-persistent permission types are ones that will never be remembered by the underlying storage, and will trigger a permission request every time a website tries to use them.

enum class QWebEnginePermission::State

This enum type holds the current state of the requested permission:

ConstantValueDescription
QWebEnginePermission::State::Invalid0Object is in an invalid state, and any attempts to modify the described permission will fail.
QWebEnginePermission::State::Ask1Either the permission has not been requested before, or the permissionType() is not persistent.
QWebEnginePermission::State::Granted2Permission has already been granted.
QWebEnginePermission::State::Denied3Permission has already been denied.

Property Documentation

[read-only] isValid : const bool

Indicates whether attempts to change the permission's state will be successful.

An invalid QWebEnginePermission is either:

  • One whose permissionType() is unsupported;
  • One whose origin() is invalid;
  • One whose associated profile has been destroyed

Access functions:

bool isValid() const

See also isPersistent().

[read-only] origin : const QUrl

This property holds the URL of the permission's associated origin.

A website origin is the combination of its scheme, hostname, and port. Permissions are granted on a per-origin basis; thus, if the web page https://www.example.com:12345/some/page.html requests a permission, it will be granted to the origin https://www.example.com:12345/.

Access functions:

QUrl origin() const

[read-only] permissionType : const PermissionType

This property holds the permission type associated with this permission.

Access functions:

QWebEnginePermission::PermissionType permissionType() const

[read-only] state : const State

This property holds the current state of the permission.

If a permission for the specified permissionType() and origin() has already been granted or denied, the return value is QWebEnginePermission::Granted, or QWebEnginePermission::Denied, respectively. When this is the first time the permission is requested, the return value is QWebEnginePermission::Ask. If the object is in an invalid state, the returned value is QWebEnginePermission::Invalid.

Access functions:

QWebEnginePermission::State state() const

See also isValid() and isPersistent().

Member Function Documentation

[invokable] void QWebEnginePermission::deny() const

Stops the associated origin from accessing the requested permissionType. Does nothing when isValid() evaluates to false.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also grant(), reset(), and isValid().

[invokable] void QWebEnginePermission::grant() const

Allows the associated origin to access the requested permissionType. Does nothing when isValid() evaluates to false.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also deny(), reset(), and isValid().

[static invokable] bool QWebEnginePermission::isPersistent(QWebEnginePermission::PermissionType permissionType)

Returns whether a permissionType is persistent, meaning that a permission's state will be remembered and the user will not be queried the next time the website requests the same permission.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

[invokable] void QWebEnginePermission::reset() const

Removes the permission from the profile's underlying storage. By default, permissions are stored on disk (except for off-the-record profiles, where permissions are stored in memory and are destroyed with the profile). This means that an already granted/denied permission will not be requested twice, but will get automatically granted/denied every subsequent time a website requests it. Calling reset() allows the query to be displayed again the next time the website requests it.

Does nothing when isValid() evaluates to false.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also grant(), deny(), isValid(), and QWebEngineProfile::persistentPermissionsPolicy().

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.