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
- void deny()
- void grant()
- void isTransient(WebEnginePermission.Feature feature)
- 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::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 |
The feature type associated with this permission.
Constant | Description |
---|---|
WebEnginePermission.MediaAudioCapture | Access to a microphone, or another audio source. This feature is transient. |
WebEnginePermission.MediaVideoCapture | Access to a webcam, or another video source. This feature is transient. |
WebEnginePermission.MediaAudioVideoCapture | Combination of MediaAudioCapture and MediaVideoCapture. This feature is transient. |
WebEnginePermission.DesktopVideoCapture | Access to the contents of the user's screen. This feature is transient. |
WebEnginePermission.DesktopAudioVideoCapture | Access to the contents of the user's screen, and application audio. This feature is transient. |
WebEnginePermission.MouseLock | Locks the pointer inside an element on the web page. This feature is transient. |
WebEnginePermission.Notifications | Allows the website to send notifications to the user. |
WebEnginePermission.Geolocation | Access to the user's physical location. |
WebEnginePermission.ClipboardReadWrite | Access to the user's clipboard. |
WebEnginePermission.LocalFontsAccess | Access to the fonts installed on the user's machine. Only available on desktops. |
WebEnginePermission.Unsupported | 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.
isValid : bool |
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 |
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 |
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 feature() is transient. |
WebEnginePermission.Granted | Permission has already been granted. |
WebEnginePermission.Denied | Permission 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() |
void grant() |
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.