webEnginePermission QML Value 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 |
| Since: | Qt 6.8 |
| In C++: | QWebEnginePermission |
Properties
- isValid : bool
- origin : url
- permissionType : enumeration
- state : enumeration
Methods
- void deny()
- void grant()
- void isPersistent(WebEnginePermission.PermissionType permissionType)
- void reset()
Detailed Description
The typical usage pattern is as follows:
- A website requests a specific feature, triggering the WebEngineView::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 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. 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 |
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 |
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 |
The permission type associated with this permission.
| Constant | Description |
|---|---|
WebEnginePermission.MediaAudioCapture | Access to a microphone, or another audio source. This permission is not persistent. |
WebEnginePermission.MediaVideoCapture | Access to a webcam, or another video source. This permission is not persistent. |
WebEnginePermission.MediaAudioVideoCapture | Combination of MediaAudioCapture and MediaVideoCapture. This permission is not persistent. |
WebEnginePermission.DesktopVideoCapture | Access to the contents of the user's screen. This permission is not persistent. |
WebEnginePermission.DesktopAudioVideoCapture | Access to the contents of the user's screen, and application audio. This permission is not persistent. |
WebEnginePermission.Notifications | Allows the website to send notifications to the user. This permission is persistent. |
WebEnginePermission.Geolocation | Access to the user's physical location. This permission is persistent. |
WebEnginePermission.ClipboardReadWrite | Access to the user's clipboard. This permission is persistent. |
WebEnginePermission.LocalFontsAccess | Access to the fonts installed on the user's machine. Only available on desktops. This permission is persistent. |
WebEnginePermission.Unsupported | An 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.
state : enumeration |
The current state of the permission.
| Constant | Description |
|---|---|
WebEnginePermission.Invalid | Object is in an invalid state, and any attempts to modify the described permission will fail. |
WebEnginePermission.Ask | Either the permission has not been requested before, or the permissionType is not persistent. |
WebEnginePermission.Granted | Permission has already been granted. |
WebEnginePermission.Denied | Permission 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, 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() |
void grant() |
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 displayed again the next time the website requests it.
Does nothing when isValid evaluates to false.
See also grant, deny, isValid, and WebEngineProfile::persistentPermissionsPolicy.