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:
- A website requests a specific feature, 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::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:
Constant | Value | Description |
---|---|---|
QWebEnginePermission::MediaAudioCapture | 1 | Access to a microphone, or another audio source. This feature is transient. |
QWebEnginePermission::MediaVideoCapture | 2 | Access to a webcam, or another video source. This feature is transient. |
QWebEnginePermission::MediaAudioVideoCapture | 3 | Combination of MediaAudioCapture and MediaVideoCapture. This feature is transient. |
QWebEnginePermission::DesktopVideoCapture | 4 | Access to the contents of the user's screen. This feature is transient. |
QWebEnginePermission::DesktopAudioVideoCapture | 5 | Access to the contents of the user's screen, and application audio. This feature is transient. |
QWebEnginePermission::MouseLock | 6 | Locks the pointer inside an element on the web page. This feature is transient. |
QWebEnginePermission::Notifications | 7 | Allows the website to send notifications to the user. |
QWebEnginePermission::Geolocation | 8 | Access to the user's physical location. |
QWebEnginePermission::ClipboardReadWrite | 9 | Access to the user's clipboard. |
QWebEnginePermission::LocalFontsAccess | 10 | Access to the fonts installed on the user's machine. Only available on desktops. |
QWebEnginePermission::Unsupported | 0 | An 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:
Constant | Value | Description |
---|---|---|
QWebEnginePermission::Invalid | 0 | Object is in an invalid state, and any attempts to modify the described permission will fail. |
QWebEnginePermission::Ask | 1 | Either the permission has not been requested before, or the feature() is transient. |
QWebEnginePermission::Granted | 2 | Permission has already been granted. |
QWebEnginePermission::Denied | 3 | Permission 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().