File indexing completed on 2024-06-16 10:06:09

0001 /*
0002     This file is part of the KDE project.
0003     SPDX-FileCopyrightText: 2008-2009 Urs Wolfer <uwolfer @ kde.org>
0004     SPDX-FileCopyrightText: 2009-2012 Dawit Alemayehu <adawit @ kde.org>
0005 
0006     SPDX-License-Identifier: LGPL-2.0-or-later
0007 */
0008 
0009 #ifndef KIO_ACCESSMANAGER_H
0010 #define KIO_ACCESSMANAGER_H
0011 
0012 #include "kiowidgets_export.h"
0013 #include <kio/global.h>
0014 #include <qwindowdefs.h> // WId
0015 
0016 #include <QNetworkAccessManager>
0017 #include <QNetworkCookieJar>
0018 #include <QNetworkRequest>
0019 
0020 #include <memory>
0021 
0022 class QWidget;
0023 
0024 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 107)
0025 
0026 namespace KIO
0027 {
0028 /**
0029  * @class KIO::AccessManager accessmanager.h <KIO/AccessManager>
0030  *
0031  * @short A KDE implementation of QNetworkAccessManager.
0032  *
0033  * Use this class instead of QNetworkAccessManager if you want to integrate
0034  * with KDE's KIO and KCookieJar modules for network operations and cookie
0035  * handling respectively.
0036  *
0037  * Here is a simple example that shows how to set the QtWebKit module to use KDE's
0038  * KIO for its network operations:
0039  * @code
0040  *   QWebView *view = new QWebView(this);
0041  *   KIO::Integration::AccessManager *manager = new KIO::Integration::AccessManager(view);
0042  *   view->page()->setNetworkAccessManager(manager);
0043  * @endcode
0044  *
0045  * To access member functions in the cookiejar class at a later point in your
0046  * code simply downcast the pointer returned by QWebPage::networkAccessManager
0047  * as follows:
0048  * @code
0049  *   KIO::Integration::AccessManager *manager = qobject_cast<KIO::Integration::AccessManager*>(view->page()->accessManager());
0050  * @endcode
0051  *
0052  * Please note that this class is in the KIO namespace for backward compatibility.
0053  * You should use KIO::Integration::AccessManager to access this class in your
0054  * code.
0055  *
0056  * <b>IMPORTANT</b>This class is not a replacement for the standard KDE API.
0057  * It should ONLY be used to provide KDE integration in applications that
0058  * cannot use the standard KDE API directly.
0059  *
0060  * @author Urs Wolfer \<uwolfer @ kde.org\>
0061  * @author Dawit Alemayehu \<adawit @ kde.org\>
0062  *
0063  * @deprecated since 5.107, use QNetworkAccessManager or KIO API.
0064  * @since 4.3
0065  */
0066 class KIOWIDGETS_EXPORT AccessManager : public QNetworkAccessManager
0067 {
0068     Q_OBJECT
0069 public:
0070     /*!
0071      * Extensions to QNetworkRequest::Attribute enums.
0072      * @since 4.3.2
0073      */
0074     enum Attribute {
0075         MetaData = QNetworkRequest::User, /** < Used to send KIO MetaData back and forth. type: QVariant::Map. */
0076         KioError, /**< Used to send KIO error codes that cannot be mapped into QNetworkReply::NetworkError. type: QVariant::Int */
0077     };
0078 
0079     /**
0080      * Constructor
0081      */
0082     KIOWIDGETS_DEPRECATED_VERSION(5, 107, "Use QNetworkAccessManager or KIO API")
0083     AccessManager(QObject *parent);
0084 
0085     /**
0086      * Destructor
0087      */
0088     ~AccessManager() override;
0089 
0090     /**
0091      * Set @p allowed to false if you don't want any external content to be fetched.
0092      * By default external content is fetched.
0093      */
0094     void setExternalContentAllowed(bool allowed);
0095 
0096     /**
0097      * Returns true if external content is going to be fetched.
0098      *
0099      * @see setExternalContentAllowed
0100      */
0101     bool isExternalContentAllowed() const;
0102 
0103 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 0)
0104     /**
0105      * Sets the cookiejar's window id to @p id.
0106      *
0107      * This is a convenience function that allows you to set the cookiejar's
0108      * window id. Note that this function does nothing unless the cookiejar in
0109      * use is of type KIO::Integration::CookieJar.
0110      *
0111      * By default the cookiejar's window id is set to false. Make sure you call
0112      * this function and set the window id to its proper value when create an
0113      * instance of this object. Otherwise, the KDE cookiejar will not be able
0114      * to properly manage session based cookies.
0115      *
0116      * @see KIO::Integration::CookieJar::setWindowId.
0117      * @since 4.4
0118      * @deprecated Since 5.0, use KIO::Integration::CookieJar::setWindowId
0119      */
0120     KIOWIDGETS_DEPRECATED_VERSION(5, 0, "Use KIO::Integration::CookieJar::setWindowId(...)")
0121     void setCookieJarWindowId(WId id);
0122 #endif
0123 
0124     /**
0125      * Sets the window associated with this network access manager.
0126      *
0127      * Note that @p widget will be used as a parent for dialogs in KIO as well
0128      * as the cookie jar. If @p widget is not a window, this function will
0129      * invoke @ref QWidget::window() to obtain the window for the given widget.
0130      *
0131      * @see KIO::Integration::CookieJar::setWindow.
0132      * @since 4.7
0133      */
0134     void setWindow(QWidget *widget);
0135 
0136 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 0)
0137     /**
0138      * Returns the cookiejar's window id.
0139      *
0140      * This is a convenience function that returns the window id associated
0141      * with the cookiejar. Note that this function will return a 0 if the
0142      * cookiejar is not of type KIO::Integration::CookieJar or a window id
0143      * has not yet been set.
0144      *
0145      * @see KIO::Integration::CookieJar::windowId.
0146      * @since 4.4
0147      * @deprecated Since 5.0, use KIO::Integration::CookieJar::windowId
0148      */
0149     KIOWIDGETS_DEPRECATED_VERSION(5, 0, "Use KIO::Integration::CookieJar::windowId()")
0150     WId cookieJarWindowid() const;
0151 #endif
0152 
0153     /**
0154      * Returns the window associated with this network access manager.
0155      *
0156      * @see setWindow
0157      * @since 4.7
0158      */
0159     QWidget *window() const;
0160 
0161     /**
0162      * Returns a reference to the temporary meta data container.
0163      *
0164      * See kdelibs/kio/DESIGN.metadata for list of supported KIO meta data.
0165      *
0166      * Use this function when you want to set per request KIO meta data that
0167      * will be removed after it has been sent once.
0168      *
0169      * @since 4.4
0170      */
0171     KIO::MetaData &requestMetaData();
0172 
0173     /**
0174      * Returns a reference to the persistent meta data container.
0175      *
0176      * See kdelibs/kio/DESIGN.metadata for list of supported KIO meta data.
0177      *
0178      * Use this function when you want to set per session KIO meta data that
0179      * will be sent with every request.
0180      *
0181      * Unlike @p requestMetaData, the meta data values set using the reference
0182      * returned by this function will not be deleted and will be sent with every
0183      * request.
0184      *
0185      * @since 4.4
0186      */
0187     KIO::MetaData &sessionMetaData();
0188 
0189     /**
0190      * Puts the KIO worker associated with the given @p reply on hold.
0191      *
0192      * This function is intended to make possible the implementation of
0193      * the special case mentioned in KIO::get's documentation within the
0194      * KIO-QNAM integration.
0195      *
0196      * @see KIO::get.
0197      * @since 4.6
0198      */
0199     static void putReplyOnHold(QNetworkReply *reply);
0200 
0201     /**
0202      * Sets the network reply object to emit readyRead when it receives meta data.
0203      *
0204      * Meta data is any information that is not the actual content itself, e.g.
0205      * HTTP response headers of the HTTP protocol.
0206      *
0207      * Calling this function will force the code connecting to QNetworkReply's
0208      * readyRead signal to prematurely start dealing with the content that might
0209      * not yet have arrived. However, it is essential to make the put worker on
0210      * hold functionality of KIO work in libraries like QtWebKit.
0211      *
0212      * @see QNetworkReply::metaDataChanged
0213      * @since 4.7
0214      */
0215     void setEmitReadyReadOnMetaDataChange(bool);
0216 
0217 protected:
0218     /**
0219      * Reimplemented for internal reasons, the API is not affected.
0220      *
0221      * @see QNetworkAccessManager::createRequest
0222      * @internal
0223      */
0224     QNetworkReply *createRequest(Operation op, const QNetworkRequest &req, QIODevice *outgoingData = nullptr) override;
0225 
0226 private:
0227     class AccessManagerPrivate;
0228     std::unique_ptr<AccessManagerPrivate> const d;
0229 };
0230 
0231 namespace Integration
0232 {
0233 // KDE5: Move AccessManager into the KIO::Integration namespace.
0234 typedef KIO::AccessManager AccessManager;
0235 
0236 /**
0237  * Maps KIO SSL meta data into the given QSslConfiguration object.
0238  *
0239  * @since 4.5
0240  * @return true if @p metadata contains ssl information and the mapping succeeded.
0241  */
0242 KIOWIDGETS_EXPORT bool sslConfigFromMetaData(const KIO::MetaData &metadata, QSslConfiguration &sslconfig);
0243 
0244 /**
0245  * @class KIO::CookieJar accessmanager.h <KIO/AccessManager>
0246  *
0247  * @short A KDE implementation of QNetworkCookieJar.
0248  *
0249  * Use this class in place of QNetworkCookieJar if you want to integrate with
0250  * KDE's cookiejar instead of the one that comes with Qt.
0251  *
0252  * Here is a simple example that shows how to set the QtWebKit module to use KDE's
0253  * cookiejar:
0254  * @code
0255  *   QWebView *view = new QWebView(this);
0256  *   KIO::Integration::CookieJar *cookieJar = new KIO::Integration::CookieJar;
0257  *   cookieJar->setWindowId(view->window()->winId());
0258  *   view->page()->networkAccessManager()->setCookieJar(cookieJar);
0259  * @endcode
0260  *
0261  * To access member functions in the cookiejar class at a later point in your
0262  * code simply downcast the pointer returned by QNetworkAccessManager::cookieJar
0263  * as follows:
0264  * @code
0265  *   KIO::Integration::CookieJar *cookieJar = qobject_cast<KIO::Integration::CookieJar*>(view->page()->accessManager()->cookieJar());
0266  * @endcode
0267  *
0268  * <b>IMPORTANT</b>This class is not a replacement for the standard KDE API.
0269  * It should ONLY be used to provide KDE integration in applications that
0270  * cannot use the standard KDE API directly.
0271  *
0272  * @see QNetworkAccessManager::setCookieJar for details.
0273  *
0274  * @author Dawit Alemayehu \<adawit @ kde.org\>
0275  * @since 4.4
0276  *
0277  * @deprecated since 5.107, use QNetworkCookieJar
0278  */
0279 class KIOWIDGETS_EXPORT CookieJar : public QNetworkCookieJar
0280 {
0281     Q_OBJECT
0282 public:
0283     /**
0284      * Constructs a KNetworkCookieJar with parent @p parent.
0285      */
0286     KIOWIDGETS_DEPRECATED_VERSION(5, 107, "Use QNetworkCookieJar")
0287     explicit CookieJar(QObject *parent = nullptr);
0288 
0289     /**
0290      * Destroys the KNetworkCookieJar.
0291      */
0292     ~CookieJar() override;
0293 
0294     /**
0295      * Returns the currently set window id. The default value is -1.
0296      */
0297     WId windowId() const;
0298 
0299     /**
0300      * Sets the window id of the application.
0301      *
0302      * This value is used by KDE's cookiejar to manage session cookies, namely
0303      * to delete them when the last application referring to such cookies is
0304      * closed by the end user.
0305      *
0306      * @see QWidget::window()
0307      * @see QWidget::winId()
0308      *
0309      * @param id the value of @ref QWidget::winId() from the window that contains your widget.
0310      */
0311     void setWindowId(WId id);
0312 
0313     /**
0314      * Reparse the KDE cookiejar configuration file.
0315      */
0316     void reparseConfiguration();
0317 
0318     /**
0319      * Reimplemented for internal reasons, the API is not affected.
0320      *
0321      * @see QNetworkCookieJar::cookiesForUrl
0322      * @internal
0323      */
0324     QList<QNetworkCookie> cookiesForUrl(const QUrl &url) const override;
0325 
0326     /**
0327      * Reimplemented for internal reasons, the API is not affected.
0328      *
0329      * @see QNetworkCookieJar::setCookiesFromUrl
0330      * @internal
0331      */
0332     bool setCookiesFromUrl(const QList<QNetworkCookie> &cookieList, const QUrl &url) override;
0333 
0334     /**
0335      * Returns true if persistent caching of cookies is disabled.
0336      *
0337      * @see setDisableCookieStorage
0338      * @since 4.6
0339      */
0340     bool isCookieStorageDisabled() const;
0341 
0342     /**
0343      * Prevent persistent storage of cookies.
0344      *
0345      * Call this function if you do not want cookies to be stored locally for
0346      * later access without disabling the cookiejar. All cookies will be discarded
0347      * once the sessions that are using the cookie are done.
0348      *
0349      * @since 4.6
0350      */
0351     void setDisableCookieStorage(bool disable);
0352 
0353 private:
0354     class CookieJarPrivate;
0355     std::unique_ptr<CookieJarPrivate> const d;
0356 };
0357 
0358 }
0359 
0360 }
0361 
0362 #endif
0363 
0364 #endif // KIO_ACCESSMANAGER_H