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 Feature { MediaAudioCapture, MediaVideoCapture, MediaAudioVideoCapture, DesktopVideoCapture, DesktopAudioVideoCapture, …, Unsupported }
enum State { Invalid, Ask, Granted, Denied }

Properties

Public Functions

void deny() const
QWebEnginePermission::Feature feature() const
void grant() const
bool isValid() const
const QUrl origin() const
void reset() const
QWebEnginePermission::State state() const

Static Public Members

bool isTransient(QWebEnginePermission::Feature feature)

Detailed Description

The typical usage pattern is as follows:

  1. A website requests a specific feature, 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::listPermissions() to get a list of existing permissions associated with a profile, or QWebEngineProfile::getPermission() 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 feature() property describes the associated feature. 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::Feature describes all the feature types Qt WebEngine supports. Some Features are transient; in practice, this means that they are never remembered, and a website that uses them will trigger a permission prompt every time the Feature is needed. Transient Features cannot be granted in advance.

The usability lifetime of a QWebEnginePermission is tied either to its associated QWebEnginePage (for transient feature types), or QWebEngineProfile (for permanent feature types). A transient permission is one which needs to be explicitly granted or denied every time it's needed (e.g. webcam/screen sharing permission), whereas a permanent one might be stored inside the current profile, depending on the value of QWebEngineProfile::persistentPermissionsPolicy(). 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::getPermission(), and QWebEngineProfile::listPermissions().

Member Type Documentation

enum QWebEnginePermission::Feature

This enum type holds the type of the requested feature:

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

Note: Transient feature 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. Transient Features can only be denied/granted as they're needed; any attempts to pre-grant a transient Feature will fail.

enum QWebEnginePermission::State

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

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

Property Documentation

[read-only] feature : const Feature

This property holds the feature type associated with this permission.

Access functions:

QWebEnginePermission::Feature feature() const

[read-only] isValid : const bool

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

An invalid QWebEnginePermission is either:

  • One whose feature() is unsupported;
  • One whose feature() is transient, and the associated page/view has been destroyed;
  • One whose feature() is permanent, but the associated profile has been destroyed;
  • One whose origin() is invalid.

Access functions:

bool isValid() const

See also isTransient().

[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:

const QUrl origin() const

[read-only] state : const State

This property holds the current state of the permission.

If a permission for the specified feature() 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, or if the feature() is transient, 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 isTransient().

Member Function Documentation

[invokable] void QWebEnginePermission::deny() const

Stops the associated origin from accessing the requested feature. 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 feature. 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::isTransient(QWebEnginePermission::Feature feature)

Returns whether feature is transient, meaning that a permission will be requested every time the associated functionality is used by a web page.

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 asked 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().