From 184ce9821a8f096781e380d4a0fb1f30e4f374e7 Mon Sep 17 00:00:00 2001
From: Andras Becsi <andras.becsi@theqtcompany.com>
Date: Fri, 14 Aug 2015 18:46:46 +0200
Subject: [PATCH] Add documentation for cookie API and request interception in
core
Change-Id: I6908ff3da9e0c78c3cf3d9b27d6c532029423d24
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@theqtcompany.com>
Reviewed-by: Allan Sandfeld Jensen <allan.jensen@theqtcompany.com>
---
src/core/api/qwebenginecookiestoreclient.cpp | 103 ++++++++++++++
src/core/api/qwebengineurlrequestinfo.cpp | 132 ++++++++++++++++++
.../api/qwebengineprofile.cpp | 19 ++-
3 files changed, 250 insertions(+), 4 deletions(-)
diff --git a/src/core/api/qwebenginecookiestoreclient.cpp b/src/core/api/qwebenginecookiestoreclient.cpp
index f4770927e..25480c1b3 100644
--- a/src/core/api/qwebenginecookiestoreclient.cpp
+++ b/src/core/api/qwebenginecookiestoreclient.cpp
@@ -171,6 +171,38 @@ void QWebEngineCookieStoreClientPrivate::onCookieChanged(const QNetworkCookie &c
Q_EMIT q->cookieAdded(cookie);
}
+/*!
+ \class QWebEngineCookieStoreClient
+ \inmodule QtWebEngineCore
+ \since 5.6
+ \brief The QWebEngineCookieStoreClient class provides access to Chromium's cookies.
+
+ By subclassing the QWebEngineCookieStoreClient and installing it on the profile, the user can
+ access HTTP cookies of Chromium.
+ It can be used to synchronize cookies of Chromium and the QNetworkAccessManager, as well as
+ to set, delete, and intercept cookies during navigation.
+ Because cookie operations are asynchronous, the user can choose to provide a callback function
+ to get notified about the success of the operation.
+ The signal handlers for removal and addition should not be used to execute heavy tasks,
+ because they might block the IO thread in case of a blocking connection.
+*/
+
+/*!
+ \fn void QWebEngineCookieStoreClient::cookieAdded(const QNetworkCookie &cookie)
+
+ This signal is emitted whenever a new \a cookie is added to the cookie store.
+*/
+
+/*!
+ \fn void QWebEngineCookieStoreClient::cookieRemoved(const QNetworkCookie &cookie)
+
+ This signal is emitted whenever a \a cookie is deleted from the cookie store.
+*/
+
+/*!
+ Creates a new QWebEngineCookieStoreClient object with \a parent.
+*/
+
QWebEngineCookieStoreClient::QWebEngineCookieStoreClient(QObject *parent)
: QObject(parent)
, d_ptr(new QWebEngineCookieStoreClientPrivate(this))
@@ -178,28 +210,69 @@ QWebEngineCookieStoreClient::QWebEngineCookieStoreClient(QObject *parent)
}
+/*!
+ Destroys this QWebEngineCookieStoreClient object.
+*/
+
QWebEngineCookieStoreClient::~QWebEngineCookieStoreClient()
{
}
+/*!
+ \fn void setCookieWithCallback(const QNetworkCookie &cookie, FunctorOrLambda resultCallback, const QUrl &origin = QUrl())
+
+ Adds \a cookie to the cookie store. When the operation finishes, \a resultCallback will be executed
+ on the caller thread.
+ It is possible to provide an optional \a origin URL argument to limit the scope of the cookie.
+ The provided URL should also include the scheme.
+
+ \sa setCookie()
+*/
+
void QWebEngineCookieStoreClient::setCookieWithCallback(const QNetworkCookie &cookie, const QWebEngineCallback<bool> &resultCallback, const QUrl &origin)
{
Q_D(QWebEngineCookieStoreClient);
d->setCookie(resultCallback, cookie, origin);
}
+/*!
+ Adds \a cookie to the cookie store. This function is provided for convenience and is
+ equivalent to calling setCookieWithCallback() with an empty callback.
+ It is possible to provide an optional \a origin URL argument to limit the scope of the cookie.
+ The provided URL should also include the scheme.
+
+ \sa setCookieWithCallback()
+*/
+
void QWebEngineCookieStoreClient::setCookie(const QNetworkCookie &cookie, const QUrl &origin)
{
setCookieWithCallback(cookie, QWebEngineCallback<bool>(), origin);
}
+/*!
+ Deletes \a cookie from the cookie store.
+ It is possible to provide an optional \a origin URL argument to limit the scope of the
+ cookie to be deleted.
+ The provided URL should also include the scheme.
+*/
+
void QWebEngineCookieStoreClient::deleteCookie(const QNetworkCookie &cookie, const QUrl &origin)
{
Q_D(QWebEngineCookieStoreClient);
d->deleteCookie(cookie, origin);
}
+/*!
+ \fn void QWebEngineCookieStoreClient::getAllCookies(FunctorOrLambda resultCallback)
+
+ Requests all the cookies in the cookie store. When the asynchronous operation finishes,
+ \a resultCallback will be called with a QByteArray as the argument containing the cookies.
+ This QByteArray can be parsed using QNetworkCookie::parseCookies().
+
+ \sa deleteCookie()
+*/
+
void QWebEngineCookieStoreClient::getAllCookies(const QWebEngineCallback<const QByteArray&> &resultCallback)
{
Q_D(QWebEngineCookieStoreClient);
@@ -211,6 +284,15 @@ void QWebEngineCookieStoreClient::getAllCookies(const QWebEngineCallback<const Q
d->getAllCookies();
}
+/*!
+ \fn void QWebEngineCookieStoreClient::deleteSessionCookiesWithCallback(FunctorOrLambda resultCallback)
+
+ Deletes all the session cookies in the cookie store. Session cookies do not have an
+ expiration date assigned to them.
+ When the asynchronous operation finishes, \a resultCallback will be called with the
+ number of cookies deleted as the argument.
+*/
+
void QWebEngineCookieStoreClient::deleteSessionCookiesWithCallback(const QWebEngineCallback<int> &resultCallback)
{
Q_D(QWebEngineCookieStoreClient);
@@ -222,6 +304,15 @@ void QWebEngineCookieStoreClient::deleteSessionCookiesWithCallback(const QWebEng
d->deleteSessionCookies();
}
+/*!
+ \fn void QWebEngineCookieStoreClient::deleteAllCookiesWithCallback(FunctorOrLambda resultCallback)
+
+ Deletes all the cookies in the cookie store. When the asynchronous operation finishes,
+ \a resultCallback will be called with the number of cookies deleted as the argument.
+
+ \sa deleteSessionCookiesWithCallback(), getAllCookies()
+*/
+
void QWebEngineCookieStoreClient::deleteAllCookiesWithCallback(const QWebEngineCallback<int> &resultCallback)
{
Q_D(QWebEngineCookieStoreClient);
@@ -233,11 +324,23 @@ void QWebEngineCookieStoreClient::deleteAllCookiesWithCallback(const QWebEngineC
d->deleteAllCookies();
}
+/*!
+ Deletes all the session cookies in the cookie store.
+
+ \sa deleteSessionCookiesWithCallback()
+*/
+
void QWebEngineCookieStoreClient::deleteSessionCookies()
{
deleteSessionCookiesWithCallback(QWebEngineCallback<int>());
}
+/*!
+ Deletes all the cookies in the cookie store.
+
+ \sa deleteAllCookiesWithCallback(), getAllCookies()
+*/
+
void QWebEngineCookieStoreClient::deleteAllCookies()
{
deleteAllCookiesWithCallback(QWebEngineCallback<int>());
diff --git a/src/core/api/qwebengineurlrequestinfo.cpp b/src/core/api/qwebengineurlrequestinfo.cpp
index e97b0c7b9..282361584 100644
--- a/src/core/api/qwebengineurlrequestinfo.cpp
+++ b/src/core/api/qwebengineurlrequestinfo.cpp
@@ -68,6 +68,57 @@ ASSERT_ENUMS_MATCH(QtWebEngineCore::WebContentsAdapterClient::BackForwardNavigat
ASSERT_ENUMS_MATCH(QtWebEngineCore::WebContentsAdapterClient::ReloadNavigation, QWebEngineUrlRequestInfo::NavigationTypeReload)
ASSERT_ENUMS_MATCH(QtWebEngineCore::WebContentsAdapterClient::OtherNavigation, QWebEngineUrlRequestInfo::NavigationTypeOther)
+/*!
+ \class QWebEngineUrlRequestInfo
+ \inmodule QtWebEngineCore
+ \since 5.6
+ \brief The QWebEngineUrlRequestInfo class provides information about URL requests.
+
+ The QWebEngineUrlRequestInfo is useful for setting extra header fields for requests
+ or for redirecting certain requests without payload data to another URL.
+ This class cannot be instantiated or copied by the user, instead it will
+ be created by Qt WebEngine and sent through the virtual function
+ QWebEngineUrlRequestInterceptor::interceptRequest() if an interceptor has been set.
+*/
+
+/*!
+ \class QWebEngineUrlRequestInterceptor
+ \inmodule QtWebEngineCore
+ \since 5.6
+ \brief The QWebEngineUrlRequestInterceptor class provides an abstract base class for URL interception.
+
+ Implementing the \l{QWebEngineUrlRequestInterceptor} interface and installing the
+ interceptor on the profile enables intercepting, blocking, and modifying URL requests
+ before they reach the networking stack of Chromium.
+
+ \sa QWebEngineUrlRequestInterceptor::interceptRequest, QWebEngineUrlRequestInfo
+*/
+
+/*!
+ \fn QWebEngineUrlRequestInterceptor::QWebEngineUrlRequestInterceptor(QObject * p = 0)
+
+ Creates a new QWebEngineUrlRequestInterceptor object with \a p as parent.
+*/
+
+/*!
+ \fn QWebEngineUrlRequestInterceptor::~QWebEngineUrlRequestInterceptor()
+
+ Destroys this QWebEngineUrlRequestInterceptor object.
+*/
+
+/*!
+ \fn bool QWebEngineUrlRequestInterceptor::interceptRequest(QWebEngineUrlRequestInfo &info)
+
+ Reimplementing this virtual function and setting the interceptor on a profile makes
+ it possible to intercept URL requests. This function is executed on the IO thread,
+ and therefore running long tasks here will block networking.
+ If this function is only used for inspection, it should return \c false, in which
+ case any modification to \a info will be ignored.
+
+ \sa QWebEngineProfile::setRequestInterceptor
+*/
+
+
QWebEngineUrlRequestInfoPrivate::QWebEngineUrlRequestInfoPrivate(QWebEngineUrlRequestInfo::ResourceType resource, QWebEngineUrlRequestInfo::NavigationType navigation, const QUrl &u, const QByteArray &m)
: resourceType(resource)
, navigationType(navigation)
@@ -77,53 +128,134 @@ QWebEngineUrlRequestInfoPrivate::QWebEngineUrlRequestInfoPrivate(QWebEngineUrlRe
{
}
+/*!
+ \internal
+*/
+
QWebEngineUrlRequestInfo::~QWebEngineUrlRequestInfo()
{
}
+/*!
+ \internal
+*/
+
QWebEngineUrlRequestInfo::QWebEngineUrlRequestInfo(QWebEngineUrlRequestInfoPrivate *p)
: d_ptr(p)
{
d_ptr->q_ptr = this;
}
+/*!
+ \enum QWebEngineUrlRequestInfo::ResourceType
+
+ This enum type holds the type of the requested resource:
+
+ \value ResourceTypeMainFrame Top level page.
+ \value ResourceTypeSubFrame Frame or iframe.
+ \value ResourceTypeStylesheet A CSS stylesheet.
+ \value ResourceTypeScript An external script.
+ \value ResourceTypeImage An image (JPG, GIF, PNG, and so on).
+ \value ResourceTypeFontResource A font.
+ \value ResourceTypeSubResource An "other" subresource.
+ \value ResourceTypeObject An object (or embed) tag for a plugin or a resource that a plugin requested.
+ \value ResourceTypeMedia A media resource.
+ \value ResourceTypeWorker The main resource of a dedicated worker.
+ \value ResourceTypeSharedWorker The main resource of a shared worker.
+ \value ResourceTypePrefetch An explicitly requested prefetch.
+ \value ResourceTypeFavicon A favicon.
+ \value ResourceTypeXhr An XMLHttpRequest.
+ \value ResourceTypePing A ping request for <a ping>.
+ \value ResourceTypeServiceWorker The main resource of a service worker.
+ \value ResourceTypeUnknown Unknown request type.
+*/
+
+/*!
+ Returns the resource type of the request.
+
+ \sa QWebEngineUrlRequestInfo::ResourceType
+*/
+
QWebEngineUrlRequestInfo::ResourceType QWebEngineUrlRequestInfo::resourceType() const
{
Q_D(const QWebEngineUrlRequestInfo);
return d->resourceType;
}
+/*!
+ \enum QWebEngineUrlRequestInfo::NavigationType
+
+ This enum type describes the navigation type of the request:
+
+ \value NavigationTypeLink Navigation initiated by clicking a link.
+ \value NavigationTypeTyped Navigation explicitly initiated by typing a URL.
+ \value NavigationTypeFormSubmitted Navigation submits a form.
+ \value NavigationTypeBackForward Navigation initiated by a history action.
+ \value NavigationTypeReload Navigation initiated by refreshing the page.
+ \value NavigationTypeOther None of the above.
+*/
+
+/*!
+ Returns the navigation type of the request.
+
+ \sa QWebEngineUrlRequestInfo::NavigationType
+*/
+
QWebEngineUrlRequestInfo::NavigationType QWebEngineUrlRequestInfo::navigationType() const
{
Q_D(const QWebEngineUrlRequestInfo);
return d->navigationType;
}
+/*!
+ Returns the request URL.
+*/
+
const QUrl &QWebEngineUrlRequestInfo::url() const
{
Q_D(const QWebEngineUrlRequestInfo);
return d->url;
}
+
+/*!
+ Returns the HTTP method of the request (for example, GET or POST).
+*/
+
const QByteArray &QWebEngineUrlRequestInfo::method() const
{
Q_D(const QWebEngineUrlRequestInfo);
return d->method;
}
+/*!
+ Redirects this request to \a url.
+ It is only possible to redirect requests that do not have payload data, such as GET requests.
+*/
+
void QWebEngineUrlRequestInfo::redirectTo(const QUrl &url)
{
Q_D(QWebEngineUrlRequestInfo);
d->url = url;
}
+/*!
+ Blocks this request if \a shouldBlock is true, so that it will not proceed.
+
+ This function can be used to prevent navigating away from a given domain, for example.
+*/
+
void QWebEngineUrlRequestInfo::blockRequest(bool shouldBlock)
{
Q_D(QWebEngineUrlRequestInfo);
d->shouldBlockRequest = shouldBlock;
}
+/*!
+ Sets an extra request header for this request with \a name and \a value.
+*/
+
void QWebEngineUrlRequestInfo::setExtraHeader(const QByteArray &name, const QByteArray &value)
{
Q_D(QWebEngineUrlRequestInfo);
diff --git a/src/webenginewidgets/api/qwebengineprofile.cpp b/src/webenginewidgets/api/qwebengineprofile.cpp
index f4d10a71c..db8c0dc89 100644
--- a/src/webenginewidgets/api/qwebengineprofile.cpp
+++ b/src/webenginewidgets/api/qwebengineprofile.cpp
@@ -434,8 +434,9 @@ void QWebEngineProfile::setHttpCacheMaximumSize(int maxSize)
}
/*!
- Returns the cookie store client for this browser.
+ Returns the cookie store client singleton, if one has been set.
*/
+
QWebEngineCookieStoreClient* QWebEngineProfile::cookieStoreClient()
{
Q_D(QWebEngineProfile);
@@ -443,8 +444,13 @@ QWebEngineCookieStoreClient* QWebEngineProfile::cookieStoreClient()
}
/*!
- Sets the cookie store client to \a client.
+ Registers a cookie store client singleton \a client to access Chromium's cookies.
+
+ The profile does not take ownership of the pointer.
+
+ \sa QtWebEngineCore::QWebEngineCookieStoreClient
*/
+
void QWebEngineProfile::setCookieStoreClient(QWebEngineCookieStoreClient *client)
{
Q_D(QWebEngineProfile);
@@ -452,8 +458,13 @@ void QWebEngineProfile::setCookieStoreClient(QWebEngineCookieStoreClient *client
}
/*!
- Sets the request interceptor to \a interceptor.
- */
+ Registers a request interceptor singleton \a interceptor to intercept URL requests.
+
+ The profile does not take ownership of the pointer.
+
+ \sa QtWebEngineCore::QWebEngineUrlRequestInfo
+*/
+
void QWebEngineProfile::setRequestInterceptor(QWebEngineUrlRequestInterceptor *interceptor)
{
Q_D(QWebEngineProfile);
--
GitLab