- Qt 6.9
- Qt WebEngine
- C++ Classes
- QtWebEngineCore
- QWebEnginePermission
- Qt 6.9.2 Reference Documentation

# 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

- List of all members, including inherited members

## Public Types

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

## Properties

- isValid : const bool
- origin : const QUrl
- permissionType : const PermissionType
- state : const State

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

Constant | Value | Description
--- | --- | ---
`QWebEnginePermission::PermissionType::MediaAudioCapture` | `1` | Access to a microphone, or another audio source. This permission is not persistent.
`QWebEnginePermission::PermissionType::MediaVideoCapture` | `2` | Access to a webcam, or another video source. This permission is not persistent.
`QWebEnginePermission::PermissionType::MediaAudioVideoCapture` | `3` | Combination of MediaAudioCapture and MediaVideoCapture. This permission is not persistent.
`QWebEnginePermission::PermissionType::DesktopVideoCapture` | `4` | Access to the contents of the user's screen. This permission is not persistent.
`QWebEnginePermission::PermissionType::DesktopAudioVideoCapture` | `5` | Access to the contents of the user's screen, and application audio. This permission is not persistent.
`QWebEnginePermission::PermissionType::MouseLock` | `6` | Locks the pointer inside an element on the web page. This permission is not persistent.
`QWebEnginePermission::PermissionType::Notifications` | `7` | Allows the website to send notifications to the user. This permission is persistent.
`QWebEnginePermission::PermissionType::Geolocation` | `8` | Access to the user's physical location. This permission is persistent.
`QWebEnginePermission::PermissionType::ClipboardReadWrite` | `9` | Access to the user's clipboard. This permission is persistent.
`QWebEnginePermission::PermissionType::LocalFontsAccess` | `10` | Access to the fonts installed on the user's machine. Only available on desktops. This permission is persistent.
`QWebEnginePermission::PermissionType::Unsupported` | `0` | An 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:

Constant | Value | Description
--- | --- | ---
`QWebEnginePermission::State::Invalid` | `0` | Object is in an invalid state, and any attempts to modify the described permission will fail.
`QWebEnginePermission::State::Ask` | `1` | Either the permission has not been requested before, or the permissionType() is not persistent.
`QWebEnginePermission::State::Granted` | `2` | Permission has already been granted.
`QWebEnginePermission::State::Denied` | `3` | Permission 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().