Make QQuickWebEngineProfile public

Make QQuickWebEngineProfile a publicly exported class.
This allows users to set up and manipulate the profile from
C++, and removes the ugly hack needed to access the cookie store.

Change-Id: I99e1a8c2cb99d9d1a14e1c78bec5948ba1282fb3
Reviewed-by: Allan Sandfeld Jensen <allan.jensen@theqtcompany.com>

1 files changed, 164 insertions, 4 deletions

diff --git a/src/webengine/api/qquickwebengineprofile.cpp b/src/webengine/api/qquickwebengineprofile.cpp
index 4871957c2..83ebd8e6e 100644
--- a/src/webengine/api/qquickwebengineprofile.cpp
+++ b/src/webengine/api/qquickwebengineprofile.cpp
@@ -34,11 +34,11 @@
 **
 ****************************************************************************/
 
-#include "qquickwebengineprofile_p.h"
+#include "qquickwebengineprofile.h"
 
 #include "qquickwebenginedownloaditem_p.h"
 #include "qquickwebenginedownloaditem_p_p.h"
-#include "qquickwebengineprofile_p_p.h"
+#include "qquickwebengineprofile_p.h"
 #include "qquickwebenginesettings_p.h"
 #include "qwebenginecookiestore.h"
 
@@ -51,6 +51,68 @@ using QtWebEngineCore::BrowserContextAdapter;
 
 QT_BEGIN_NAMESPACE
 
+
+/*!
+    \class QQuickWebEngineProfile
+    \brief The QQuickWebEngineProfile class provides a web-engine profile shared by multiple pages.
+    \since 5.6
+
+    \inmodule QtWebEngine
+
+    QQuickWebEngineProfile contains settings, scripts, and the list of visited links shared by all
+    web engine pages that belong to the profile. As such, profiles can be used to isolate pages
+    from each other. A typical use case is a dedicated profile for a 'private browsing' mode.
+
+    The default profile is a built-in profile that all web pages not specifically created with
+    another profile belong to.
+*/
+
+/*!
+    \enum QQuickWebEngineProfile::HttpCacheType
+
+    This enum describes the HTTP cache type:
+
+    \value MemoryHttpCache Use an in-memory cache. This is the only setting possible if
+    \c off-the-record is set or no cache path is available.
+    \value DiskHttpCache Use a disk cache. This is the default.
+*/
+
+/*!
+    \enum QQuickWebEngineProfile::PersistentCookiesPolicy
+
+    This enum describes policy for cookie persistency:
+
+    \value  NoPersistentCookies
+            Both session and persistent cookies are stored in memory. This is the only setting
+            possible if \c off-the-record is set or no persistent data path is available.
+    \value  AllowPersistentCookies
+            Cookies 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.
+    \value  ForcePersistentCookies
+            Both session and persistent cookies are saved to and restored from disk.
+*/
+
+/*!
+  \fn QQuickWebEngineProfile::downloadRequested(QQuickWebEngineDownloadItem *download)
+
+  This signal is emitted whenever a download has been triggered.
+  The \a download argument holds the state of the download.
+  The download has to be explicitly accepted with
+  \c{QQuickWebEngineDownloadItem::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.
+*/
+
+/*!
+  \fn QQuickWebEngineProfile::downloadFinished(QQuickWebEngineDownloadItem *download)
+
+  This signal is emitted whenever downloading stops, because it finished successfully, was
+  cancelled, or was interrupted (for example, because connectivity was lost).
+  The \a download argument holds the state of the finished download instance.
+*/
+
 QQuickWebEngineProfilePrivate::QQuickWebEngineProfilePrivate(BrowserContextAdapter* browserContext)
         : m_settings(new QQuickWebEngineSettings())
         , m_browserContextRef(browserContext)
@@ -163,8 +225,12 @@ void QQuickWebEngineProfilePrivate::downloadUpdated(const DownloadItemInfo &info
     The \a download argument holds the state of the finished download instance.
 */
 
-QQuickWebEngineProfile::QQuickWebEngineProfile()
-    : d_ptr(new QQuickWebEngineProfilePrivate(new BrowserContextAdapter(false)))
+/*!
+    Constructs a new profile with the parent \a parent.
+*/
+QQuickWebEngineProfile::QQuickWebEngineProfile(QObject *parent)
+    : QObject(parent),
+      d_ptr(new QQuickWebEngineProfilePrivate(new BrowserContextAdapter(false)))
 {
     // Sets up the global WebEngineContext
     QQuickWebEngineProfile::defaultProfile();
@@ -178,6 +244,9 @@ QQuickWebEngineProfile::QQuickWebEngineProfile(QQuickWebEngineProfilePrivate *pr
     d_ptr->q_ptr = this;
 }
 
+/*!
+   \internal
+*/
 QQuickWebEngineProfile::~QQuickWebEngineProfile()
 {
 }
@@ -191,6 +260,15 @@ QQuickWebEngineProfile::~QQuickWebEngineProfile()
     \sa WebEngineProfile::persistentStoragePath, WebEngineProfile::cachePath
 */
 
+/*!
+    \property QQuickWebEngineProfile::storageName
+
+    The storage name that is used to create separate subdirectories for each profile that uses
+    the disk for storing persistent data and cache.
+
+    \sa QQuickWebEngineProfile::persistentStoragePath, QQuickWebEngineProfile::cachePath
+*/
+
 QString QQuickWebEngineProfile::storageName() const
 {
     const Q_D(QQuickWebEngineProfile);
@@ -221,6 +299,16 @@ void QQuickWebEngineProfile::setStorageName(const QString &name)
     An off-the-record profile forces cookies, the HTTP cache, and other normally persistent data
     to be stored only in memory.
 */
+
+
+/*!
+    \property QQuickWebEngineProfile::offTheRecord
+
+    Whether the web engine profile is \e off-the-record.
+    An off-the-record profile forces cookies, the HTTP cache, and other normally persistent data
+    to be stored only in memory.
+*/
+
 bool QQuickWebEngineProfile::isOffTheRecord() const
 {
     const Q_D(QQuickWebEngineProfile);
@@ -252,6 +340,18 @@ void QQuickWebEngineProfile::setOffTheRecord(bool offTheRecord)
     QStandardPaths::writableLocation(QStandardPaths::DataLocation) in a directory named using
     storageName.
 */
+
+/*!
+    \property QQuickWebEngineProfile::persistentStoragePath
+
+    The path to the location where the persistent data for the browser and web content are
+    stored. Persistent data includes persistent cookies, HTML5 local storage, and visited links.
+
+    By default, the storage is located below
+    QStandardPaths::writableLocation(QStandardPaths::DataLocation) in a directory named using
+    storageName.
+*/
+
 QString QQuickWebEngineProfile::persistentStoragePath() const
 {
     const Q_D(QQuickWebEngineProfile);
@@ -276,6 +376,17 @@ void QQuickWebEngineProfile::setPersistentStoragePath(const QString &path)
     below QStandardPaths::writableLocation(QStandardPaths::CacheLocation) in a directory named using
     storageName.
 */
+
+/*!
+    \property QQuickWebEngineProfile::cachePath
+
+    The path to the location where the profile's caches are stored, in particular the HTTP cache.
+
+    By default, the caches are stored
+    below QStandardPaths::writableLocation(QStandardPaths::CacheLocation) in a directory named using
+    storageName.
+*/
+
 QString QQuickWebEngineProfile::cachePath() const
 {
     const Q_D(QQuickWebEngineProfile);
@@ -296,6 +407,13 @@ void QQuickWebEngineProfile::setCachePath(const QString &path)
 
     The user-agent string sent with HTTP to identify the browser.
 */
+
+/*!
+    \property QQuickWebEngineProfile::httpUserAgent
+
+    The user-agent string sent with HTTP to identify the browser.
+*/
+
 QString QQuickWebEngineProfile::httpUserAgent() const
 {
     const Q_D(QQuickWebEngineProfile);
@@ -324,6 +442,14 @@ void QQuickWebEngineProfile::setHttpUserAgent(const QString &userAgent)
             Uses a disk cache. This is the default value.
 */
 
+/*!
+    \property QQuickWebEngineProfile::httpCacheType
+
+    This enumeration describes the type of the HTTP cache.
+
+    If the profile is off-the-record, MemoryHttpCache is returned.
+*/
+
 QQuickWebEngineProfile::HttpCacheType QQuickWebEngineProfile::httpCacheType() const
 {
     const Q_D(QQuickWebEngineProfile);
@@ -354,6 +480,13 @@ void QQuickWebEngineProfile::setHttpCacheType(QQuickWebEngineProfile::HttpCacheT
             Both session and persistent cookies are saved to and restored from disk.
 */
 
+/*!
+    \property QQuickWebEngineProfile::persistentCookiesPolicy
+
+    This enumeration describes the policy of cookie persistency.
+    If the profile is off-the-record, NoPersistentCookies is returned.
+*/
+
 QQuickWebEngineProfile::PersistentCookiesPolicy QQuickWebEngineProfile::persistentCookiesPolicy() const
 {
     const Q_D(QQuickWebEngineProfile);
@@ -377,6 +510,16 @@ void QQuickWebEngineProfile::setPersistentCookiesPolicy(QQuickWebEngineProfile::
 
     \sa httpCacheType
 */
+
+/*!
+    \property QQuickWebEngineProfile::httpCacheMaximumSize
+
+    The maximum size of the HTTP cache. If \c 0, the size will be controlled automatically by
+    QtWebEngine. The default value is \c 0.
+
+    \sa httpCacheType
+*/
+
 int QQuickWebEngineProfile::httpCacheMaximumSize() const
 {
     const Q_D(QQuickWebEngineProfile);
@@ -399,6 +542,13 @@ void QQuickWebEngineProfile::setHttpCacheMaximumSize(int maximumSize)
 
     \since QtWebEngine 1.2
 */
+
+/*!
+    \property QQuickWebEngineProfile::httpAcceptLanguage
+
+    The value of the Accept-Language HTTP request-header field.
+*/
+
 QString QQuickWebEngineProfile::httpAcceptLanguage() const
 {
     Q_D(const QQuickWebEngineProfile);
@@ -414,6 +564,13 @@ void QQuickWebEngineProfile::setHttpAcceptLanguage(const QString &httpAcceptLang
     emit httpAcceptLanguageChanged();
 }
 
+/*!
+    Returns the default profile.
+
+    The default profile uses the storage name "Default".
+
+    \sa storageName()
+*/
 QQuickWebEngineProfile *QQuickWebEngineProfile::defaultProfile()
 {
     static QQuickWebEngineProfile *profile = new QQuickWebEngineProfile(
@@ -422,6 +579,9 @@ QQuickWebEngineProfile *QQuickWebEngineProfile::defaultProfile()
     return profile;
 }
 
+/*!
+    Returns the cookie store singleton, if one has been set.
+*/
 QWebEngineCookieStore *QQuickWebEngineProfile::cookieStore() const
 {
     const Q_D(QQuickWebEngineProfile);