webEnginePermission QML Type

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...

Import Statement: import QtWebEngine
In C++: QWebEnginePermission



Detailed Description

The typical usage pattern is as follows:

  1. A website requests a specific feature, triggering the WebEngineView::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 WebEngineProfile::listAllPermissions() to get a list of existing permissions associated with a profile, or WebEngineProfile::queryPermission() to get a webEnginePermission object for a specific permission.

The origin property can be used to query which origin the webEnginePermission is associated with, while the permissionType 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/.

The permissionType enumeration 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, and cannot be granted in advance. You can check whether a permission type is persistent at runtime using the static method WebEnginePermission::isPersistent().

Persistent permissions are stored inside the active WebEngineProfile, and their lifetime depends on the value of WebEngineProfile::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 WebEngineView performs a navigation to a different URL, or is destroyed.

You can check whether a WebEnginePermission 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 WebEnginePermission::Invalid.

See also WebEngineView::permissionRequested, WebEngineProfile::queryPermission(), and WebEngineProfile::listAllPermissions().

Property Documentation

isValid : bool [read-only]

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

An invalid webEnginePermission is either:

  • One whose permissionType is unsupported;
  • One whose permissionType is non-persistent, and the user has navigated away from the web page that triggered the request;
  • One whose permissionType is persistent, but the associated profile has been destroyed;
  • One whose origin is invalid.

See also isPersistent.

origin : url [read-only]

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/.

permissionType : enumeration [read-only]

The permission type associated with this permission.

WebEnginePermission.MediaAudioCaptureAccess to a microphone, or another audio source. This permission is not persistent.
WebEnginePermission.MediaVideoCaptureAccess to a webcam, or another video source. This permission is not persistent.
WebEnginePermission.MediaAudioVideoCaptureCombination of MediaAudioCapture and MediaVideoCapture. This permission is not persistent.
WebEnginePermission.DesktopVideoCaptureAccess to the contents of the user's screen. This permission is not persistent.
WebEnginePermission.DesktopAudioVideoCaptureAccess to the contents of the user's screen, and application audio. This permission is not persistent.
WebEnginePermission.NotificationsAllows the website to send notifications to the user. This permission is persistent.
WebEnginePermission.GeolocationAccess to the user's physical location. This permission is persistent.
WebEnginePermission.ClipboardReadWriteAccess to the user's clipboard. This permission is persistent.
WebEnginePermission.LocalFontsAccessAccess to the fonts installed on the user's machine. Only available on desktops. This permission is persistent.
WebEnginePermission.UnsupportedAn unsupported feature 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. They can only be denied/granted as they're needed; any attempts to pre-grant a non-persistent permission will fail.

state : enumeration [read-only]

The current state of the permission.

WebEnginePermission.InvalidObject is in an invalid state, and any attempts to modify the described permission will fail.
WebEnginePermission.AskEither the permission has not been requested before, or the permissionType is not persistent.
WebEnginePermission.GrantedPermission has already been granted.
WebEnginePermission.DeniedPermission has already been denied.

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

See also isValid and isPersistent.

Method Documentation

void deny()

Stops the associated origin from accessing the requested feature. Does nothing when isValid evaluates to false.

See also grant, reset, and isValid.

void grant()

Allows the associated origin to access the requested per. Does nothing when isValid evaluates to false.

See also deny, reset, and isValid.

void isPersistent(WebEnginePermission.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.

void reset()

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.

See also grant, deny, isValid, and WebEngineProfile::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.