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

Properties

Methods

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::listPermissions() to get a list of existing permissions associated with a profile, or WebEngineProfile::getPermission() 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 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/.

The usability lifetime of a webEnginePermission is tied either to its associated WebEngineView (for transient feature types), or WebEngineProfile (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 WebEngineProfile::persistentPermissionsPolicy. 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, and their state() will always be WebEnginePermission.Invalid.

The feature types Qt WebEngine supports are described in feature.

See also WebEngineView::permissionRequested, WebEngineProfile::getPermission(), and WebEngineProfile::listPermissions().

Property Documentation

feature : enumeration [read-only]

The feature type associated with this permission.

ConstantDescription
WebEnginePermission.MediaAudioCaptureAccess to a microphone, or another audio source. This feature is transient.
WebEnginePermission.MediaVideoCaptureAccess to a webcam, or another video source. This feature is transient.
WebEnginePermission.MediaAudioVideoCaptureCombination of MediaAudioCapture and MediaVideoCapture. This feature is transient.
WebEnginePermission.DesktopVideoCaptureAccess to the contents of the user's screen. This feature is transient.
WebEnginePermission.DesktopAudioVideoCaptureAccess to the contents of the user's screen, and application audio. This feature is transient.
WebEnginePermission.MouseLockLocks the pointer inside an element on the web page. This feature is transient.
WebEnginePermission.NotificationsAllows the website to send notifications to the user.
WebEnginePermission.GeolocationAccess to the user's physical location.
WebEnginePermission.ClipboardReadWriteAccess to the user's clipboard.
WebEnginePermission.LocalFontsAccessAccess to the fonts installed on the user's machine. Only available on desktops.
WebEnginePermission.UnsupportedAn 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.


isValid : bool [read-only]

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

An invalid webEnginePermission 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.

See also isTransient.


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


state : enumeration [read-only]

The current state of the permission.

ConstantDescription
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 feature() is transient.
WebEnginePermission.GrantedPermission has already been granted.
WebEnginePermission.DeniedPermission has already been denied.

If a permission for the specified feature 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 feature is transient, the return value is WebEnginePermission.Ask. If the object is in an invalid state, the returned value is WebEnginePermission.Invalid.

See also isValid and isTransient.


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 feature. Does nothing when isValid evaluates to false.

See also deny, reset, and isValid.


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


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.