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
- 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:
- A website requests a specific permission, triggering the QWebEnginePage::permissionRequested() signal;
- The signal handler triggers a prompt asking the user whether they want to grant the permission;
- 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().
© 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.