QWebEngineProfile Class

The QWebEngineProfile class provides a web engine profile shared by multiple pages. More...

Header: #include <QWebEngineProfile>
CMake: find_package(Qt6 REQUIRED COMPONENTS WebEngineCore)
target_link_libraries(mytarget PRIVATE Qt6::WebEngineCore)
qmake: QT += webenginecore
Inherits: QObject

Public Types

enum HttpCacheType { MemoryHttpCache, DiskHttpCache, NoCache }
enum PersistentCookiesPolicy { NoPersistentCookies, AllowPersistentCookies, ForcePersistentCookies }

Public Functions

QWebEngineProfile(QObject *parent = nullptr)
QWebEngineProfile(const QString &storageName, QObject *parent = nullptr)
QString cachePath() const
void clearAllVisitedLinks()
void clearHttpCache()
void clearVisitedLinks(const QList<QUrl> &urls)
QWebEngineClientCertificateStore *clientCertificateStore()
QWebEngineCookieStore *cookieStore()
QString downloadPath() const
QString httpAcceptLanguage() const
int httpCacheMaximumSize() const
QWebEngineProfile::HttpCacheType httpCacheType() const
QString httpUserAgent() const
void installUrlSchemeHandler(const QByteArray &scheme, QWebEngineUrlSchemeHandler *handler)
bool isOffTheRecord() const
bool isPushServiceEnabled() const
bool isSpellCheckEnabled() const
QWebEngineProfile::PersistentCookiesPolicy persistentCookiesPolicy() const
QString persistentStoragePath() const
void removeAllUrlSchemeHandlers()
void removeUrlScheme(const QByteArray &scheme)
void removeUrlSchemeHandler(QWebEngineUrlSchemeHandler *handler)
void requestIconForIconURL(const QUrl &url, int desiredSizeInPixel, std::function<void (const QIcon &, const QUrl &)> iconAvailableCallback) const
void requestIconForPageURL(const QUrl &url, int desiredSizeInPixel, std::function<void (const QIcon &, const QUrl &, const QUrl &)> iconAvailableCallback) const
QWebEngineScriptCollection *scripts() const
void setCachePath(const QString &path)
void setDownloadPath(const QString &path)
void setHttpAcceptLanguage(const QString &httpAcceptLanguage)
void setHttpCacheMaximumSize(int maxSize)
void setHttpCacheType(QWebEngineProfile::HttpCacheType httpCacheType)
void setHttpUserAgent(const QString &userAgent)
void setNotificationPresenter(std::function<void (std::unique_ptr<QWebEngineNotification>)> notificationPresenter)
void setPersistentCookiesPolicy(QWebEngineProfile::PersistentCookiesPolicy newPersistentCookiesPolicy)
void setPersistentStoragePath(const QString &path)
void setPushServiceEnabled(bool enable)
void setSpellCheckEnabled(bool enable)
void setSpellCheckLanguages(const QStringList &languages)
void setUrlRequestInterceptor(QWebEngineUrlRequestInterceptor *interceptor)
QWebEngineSettings *settings() const
QStringList spellCheckLanguages() const
QString storageName() const
const QWebEngineUrlSchemeHandler *urlSchemeHandler(const QByteArray &scheme) const
bool visitedLinksContainsUrl(const QUrl &url) const

Signals

void downloadRequested(QWebEngineDownloadRequest *download)

Static Public Members

QWebEngineProfile *defaultProfile()

Detailed Description

A web engine profile contains settings, scripts, persistent cookie policy, and the list of visited links shared by all web engine pages that belong to the profile.

All pages that belong to the profile share a common QWebEngineSettings instance, which can be accessed with the settings() method. Likewise, the scripts() method provides access to a common QWebEngineScriptCollection instance.

Information about visited links is stored together with persistent cookies and other persistent data in a storage returned by storageName(). Persistent data is stored in a subdirectory set by calling setPersistentStoragePath(), and the cache is located in a subdirectory set by calling setCachePath(). The cache type can be set to in-memory or on-disk by calling setHttpCacheType(). If only the storage name is set, the subdirectories are created and named automatically. If you set any of the values manually, you should do it before creating any pages that belong to the profile.

The cache can be cleared of links by calling clearVisitedLinks() or clearAllVisitedLinks(). PersistentCookiesPolicy describes whether session and persistent cookies are saved to and restored from memory or disk.

Profiles can be used to isolate pages from each other. A typical use case is a dedicated off-the-record profile for a private browsing mode. Using QWebEngineProfile() without defining a storage name constructs a new off-the-record profile that leaves no record on the local machine, and has no persistent data or cache. The isOffTheRecord() method can be used to check whether a profile is off-the-record.

The default profile can be accessed by defaultProfile(). It is a built-in profile that all web pages not specifically created with another profile belong to.

Implementing the QWebEngineUrlRequestInterceptor interface and registering the interceptor on a profile by setUrlRequestInterceptor() enables intercepting, blocking, and modifying URL requests (QWebEngineUrlRequestInfo) before they reach the networking stack of Chromium.

A QWebEngineUrlSchemeHandler can be registered for a profile by installUrlSchemeHandler() to add support for custom URL schemes. Requests for the scheme are then issued to QWebEngineUrlSchemeHandler::requestStarted() as QWebEngineUrlRequestJob objects.

Spellchecking HTML form fields can be enabled per profile by using the setSpellCheckEnabled() method and the current languages used for spellchecking can be set by using the setSpellCheckLanguages() method.

Member Type Documentation

enum QWebEngineProfile::HttpCacheType

This enum describes the HTTP cache type:

ConstantValueDescription
QWebEngineProfile::MemoryHttpCache0Use an in-memory cache. This is the default if off-the-record is set.
QWebEngineProfile::DiskHttpCache1Use a disk cache. This is the default if the profile is not off-the-record. If set on an off-the-record profile will instead set MemoryHttpCache.
QWebEngineProfile::NoCache2Disable both in-memory and disk caching. (Added in Qt 5.7)

enum QWebEngineProfile::PersistentCookiesPolicy

This enum describes policy for cookie persistency:

ConstantValueDescription
QWebEngineProfile::NoPersistentCookies0Both session and persistent cookies are stored in memory. This is the only setting possible if off-the-record is set or no persistent data path is available.
QWebEngineProfile::AllowPersistentCookies1Cookies marked persistent are saved to and restored from disk, whereas session cookies are only stored to disk for crash recovery. This is the default setting.
QWebEngineProfile::ForcePersistentCookies2Both session and persistent cookies are saved to and restored from disk.

Member Function Documentation

[explicit] QWebEngineProfile::QWebEngineProfile(QObject *parent = nullptr)

Constructs a new off-the-record profile with the parent parent.

An off-the-record profile leaves no record on the local machine, and has no persistent data or cache. Thus, the HTTP cache can only be in memory and the cookies can only be non-persistent. Trying to change these settings will have no effect.

See also isOffTheRecord().

[explicit] QWebEngineProfile::QWebEngineProfile(const QString &storageName, QObject *parent = nullptr)

Constructs a new profile with the storage name storageName and parent parent.

The storage name must be unique.

A disk-based QWebEngineProfile should be destroyed on or before application exit, otherwise the cache and persistent data may not be fully flushed to disk.

See also storageName().

QString QWebEngineProfile::cachePath() const

Returns the path used for caches.

By default, this is below StandardPaths::CacheLocation in a QtWebengine/StorageName specific subdirectory.

See also setCachePath(), storageName(), and QStandardPaths::writableLocation().

Clears all links from the visited links database.

See also clearVisitedLinks().

void QWebEngineProfile::clearHttpCache()

Removes the profile's cache entries.

Clears the links in urls from the visited links database.

See also clearAllVisitedLinks().

QWebEngineClientCertificateStore *QWebEngineProfile::clientCertificateStore()

Returns the profile's client certificate store.

QWebEngineCookieStore *QWebEngineProfile::cookieStore()

Returns the cookie store for this profile.

[static] QWebEngineProfile *QWebEngineProfile::defaultProfile()

Returns the default profile.

The default profile is off-the-record.

See also storageName().

QString QWebEngineProfile::downloadPath() const

The path to the location where the downloaded files are stored.

Note: By default, the download path is QStandardPaths::DownloadLocation.

See also setDownloadPath() and QStandardPaths::writableLocation().

[signal] void QWebEngineProfile::downloadRequested(QWebEngineDownloadRequest *download)

This signal is emitted whenever a download has been triggered. The download argument holds the state of the download. The download has to be explicitly accepted with QWebEngineDownloadRequest::accept() or it will be cancelled by default. The download item is parented by the profile. If it is not accepted, it will be deleted immediately after the signal emission. This signal cannot be used with a queued connection.

See also QWebEngineDownloadRequest and QWebEnginePage::download().

QString QWebEngineProfile::httpAcceptLanguage() const

Returns the value of the Accept-Language HTTP request-header field.

See also setHttpAcceptLanguage().

int QWebEngineProfile::httpCacheMaximumSize() const

Returns the maximum size of the HTTP cache in bytes.

Will return 0 if the size is automatically controlled by QtWebEngine.

See also setHttpCacheMaximumSize() and httpCacheType().

QWebEngineProfile::HttpCacheType QWebEngineProfile::httpCacheType() const

Returns the type of HTTP cache used.

If the profile is off-the-record, MemoryHttpCache is returned.

See also setHttpCacheType() and cachePath().

QString QWebEngineProfile::httpUserAgent() const

Returns the user-agent string sent with HTTP to identify the browser.

Note: On Windows 8.1 and newer, the default user agent will always report "Windows NT 6.2" (Windows 8), unless the application does contain a manifest that declares newer Windows versions as supported.

See also setHttpUserAgent().

void QWebEngineProfile::installUrlSchemeHandler(const QByteArray &scheme, QWebEngineUrlSchemeHandler *handler)

Registers a handler handler for custom URL scheme scheme in the profile.

It is necessary to first register the scheme with QWebEngineUrlScheme::registerScheme at application startup.

bool QWebEngineProfile::isOffTheRecord() const

Returns true if this is an off-the-record profile that leaves no record on the computer.

This will force cookies and HTTP cache to be in memory, but also force all other normally persistent data to be stored in memory.

[since 6.5] bool QWebEngineProfile::isPushServiceEnabled() const

Returns true if the push messaging service is enabled.

Note: By default the push messaging service is disabled.

This function was introduced in Qt 6.5.

See also setPushServiceEnabled().

bool QWebEngineProfile::isSpellCheckEnabled() const

Returns true if the spell checker is enabled; otherwise returns false.

See also setSpellCheckEnabled().

QWebEngineProfile::PersistentCookiesPolicy QWebEngineProfile::persistentCookiesPolicy() const

Returns the current policy for persistent cookies.

If the profile is off-the-record, NoPersistentCookies is returned.

See also setPersistentCookiesPolicy().

QString QWebEngineProfile::persistentStoragePath() const

Returns the path used to store persistent data for the browser and web content.

Persistent data includes persistent cookies, HTML5 local storage, and visited links.

By default, this is below QStandardPaths::DataLocation in a QtWebengine/StorageName specific subdirectory.

Note: Use QStandardPaths::writableLocation(QStandardPaths::DataLocation) to obtain the QStandardPaths::DataLocation path.

See also setPersistentStoragePath(), storageName(), and QStandardPaths::writableLocation().

void QWebEngineProfile::removeAllUrlSchemeHandlers()

Removes all custom URL scheme handlers installed in the profile.

void QWebEngineProfile::removeUrlScheme(const QByteArray &scheme)

Removes the custom URL scheme scheme from the profile.

See also removeUrlSchemeHandler().

void QWebEngineProfile::removeUrlSchemeHandler(QWebEngineUrlSchemeHandler *handler)

Removes the custom URL scheme handler handler from the profile.

See also removeUrlScheme().

[since 6.2] void QWebEngineProfile::requestIconForIconURL(const QUrl &url, int desiredSizeInPixel, std::function<void (const QIcon &, const QUrl &)> iconAvailableCallback) const

Requests an icon with the specified url from the database. Each profile has its own icon database and it is stored in the persistent storage thus the stored icons can be accessed without network connection too. The icon must be previously loaded to be stored in the database.

url specifies the URL of the icon. In case of more than one available icons the one with the size closest to desiredSizeInPixel will be returned. The result icon is resized to desiredSizeInPixel. If desiredSizeInPixel is 0 the largest available icon is returned.

This function is asynchronous and the result is returned by iconAvailableCallback. The callback is called if a request for an icon is performed. If the requested icon is available, the first parameter (with type QIcon) is the result. Otherwise, it is null.

The second parameter stores the URL of the requested icon. It is empty if the icon can't be fetched.

Note: Icons can't be requested with an off-the-record profile.

This function was introduced in Qt 6.2.

See also requestIconForPageURL().

[since 6.2] void QWebEngineProfile::requestIconForPageURL(const QUrl &url, int desiredSizeInPixel, std::function<void (const QIcon &, const QUrl &, const QUrl &)> iconAvailableCallback) const

Requests an icon for a previously loaded page with this profile from the database. Each profile has its own icon database and it is stored in the persistent storage thus the stored icons can be accessed without network connection too. The icon must be previously loaded to be stored in the database.

url specifies the URL of the page what the icon is requested for. In case of more than one available icons the one with the size closest to desiredSizeInPixel will be returned. The result icon is resized to desiredSizeInPixel. If desiredSizeInPixel is 0 the largest available icon is returned.

This function is asynchronous and the result is returned by iconAvailableCallback. The callback is called if a request for an icon is performed. If the requested icon is available, the first parameter (with type QIcon) is the result. Otherwise, it is null.

The second parameter stores the URL of the requested icon. It is empty if the icon can't be fetched.

The third parameter stores the URL of the page which the icon is assigned.

Note: Icons can't be requested with an off-the-record profile.

This function was introduced in Qt 6.2.

See also requestIconForIconURL().

QWebEngineScriptCollection *QWebEngineProfile::scripts() const

Returns the collection of scripts that are injected into all pages that share this profile.

See also QWebEngineScriptCollection, QWebEngineScript, QWebEnginePage::scripts(), and Script Injection.

void QWebEngineProfile::setCachePath(const QString &path)

Overrides the default path used for disk caches, setting it to path.

If set to the null string, the default path is restored.

See also cachePath().

void QWebEngineProfile::setDownloadPath(const QString &path)

Overrides the default path used for download location, setting it to path.

If set to the null string, the default path is restored.

See also downloadPath().

void QWebEngineProfile::setHttpAcceptLanguage(const QString &httpAcceptLanguage)

Sets the value of the Accept-Language HTTP request-header field to httpAcceptLanguage.

See also httpAcceptLanguage().

void QWebEngineProfile::setHttpCacheMaximumSize(int maxSize)

Sets the maximum size of the HTTP cache to maxSize bytes.

Setting it to 0 means the size will be controlled automatically by QtWebEngine.

See also httpCacheMaximumSize() and setHttpCacheType().

void QWebEngineProfile::setHttpCacheType(QWebEngineProfile::HttpCacheType httpCacheType)

Sets the HTTP cache type to httpCacheType.

See also httpCacheType() and setCachePath().

void QWebEngineProfile::setHttpUserAgent(const QString &userAgent)

Overrides the default user-agent string, setting it to userAgent.

See also httpUserAgent().

void QWebEngineProfile::setNotificationPresenter(std::function<void (std::unique_ptr<QWebEngineNotification>)> notificationPresenter)

Sets the function notificationPresenter as responsible for presenting sent notifications.

See also QWebEngineNotification.

void QWebEngineProfile::setPersistentCookiesPolicy(QWebEngineProfile::PersistentCookiesPolicy newPersistentCookiesPolicy)

Sets the policy for persistent cookies to newPersistentCookiesPolicy.

See also persistentCookiesPolicy().

void QWebEngineProfile::setPersistentStoragePath(const QString &path)

Overrides the default path used to store persistent web engine data.

If path is set to the null string, the default path is restored.

See also persistentStoragePath().

[since 6.5] void QWebEngineProfile::setPushServiceEnabled(bool enable)

Enables the push messaging service if enable is true, otherwise disables it.

Note: Qt WebEngine uses Firebase Cloud Messaging (FCM) as a browser push service. Therefore, all push messages will go through the Google push service and its respective servers.

This function was introduced in Qt 6.5.

See also isPushServiceEnabled().

void QWebEngineProfile::setSpellCheckEnabled(bool enable)

Enables spell checker if enable is true, otherwise disables it.

See also isSpellCheckEnabled().

void QWebEngineProfile::setSpellCheckLanguages(const QStringList &languages)

Sets the current list of languages for the spell checker. Each language should match the name of the .bdic dictionary. For example, the language en-US will load the en-US.bdic dictionary file.

See the Spellchecker feature documentation for how dictionary files are searched.

For more information about how to compile .bdic dictionaries, see the Spellchecker Example.

See also spellCheckLanguages().

void QWebEngineProfile::setUrlRequestInterceptor(QWebEngineUrlRequestInterceptor *interceptor)

Registers a request interceptor singleton interceptor to intercept URL requests.

The profile does not take ownership of the pointer.

See also QWebEngineUrlRequestInfo and QWebEngineUrlRequestInterceptor.

QWebEngineSettings *QWebEngineProfile::settings() const

Returns the default settings for all pages in this profile.

QStringList QWebEngineProfile::spellCheckLanguages() const

Returns the list of languages used by the spell checker.

See also setSpellCheckLanguages().

QString QWebEngineProfile::storageName() const

Returns the storage name for the profile.

The storage name is used to give each profile that uses the disk separate subdirectories for persistent data and cache.

const QWebEngineUrlSchemeHandler *QWebEngineProfile::urlSchemeHandler(const QByteArray &scheme) const

Returns the custom URL scheme handler register for the URL scheme scheme.

bool QWebEngineProfile::visitedLinksContainsUrl(const QUrl &url) const

Returns true if url is considered a visited link by this profile.

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