From 81a9335c653661f70d8bfa8f37d2d72bdef60d41 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A5rten=20Nordheim?= Date: Mon, 7 Dec 2020 14:51:24 +0100 Subject: [PATCH] Fix documentation of QNetworkAccessBackend The classes themselves were not documented, so...: Add some documentation for QNetworkAccessBackendFactory. Add some overall class docs for QNetworkAccessBackend. The class docs were marked \internal (because they mostly are). I don't think we yet have a defined way to handle semi-private APIs but having them be marked \internal and leaving the documentation in source seems fine (and was what someone suggested a while back). Add documentation for pure virtual functions which were overlooked. Pick-to: 6.2 Fixes: QTBUG-88774 Change-Id: Id7fe18ec92372abb96540cd29543608f87ec862e Reviewed-by: Edward Welbourne --- src/network/access/qnetworkaccessbackend.cpp | 111 +++++++++++++++++++ 1 file changed, 111 insertions(+) diff --git a/src/network/access/qnetworkaccessbackend.cpp b/src/network/access/qnetworkaccessbackend.cpp index 2284461099..acac03220a 100644 --- a/src/network/access/qnetworkaccessbackend.cpp +++ b/src/network/access/qnetworkaccessbackend.cpp @@ -125,6 +125,76 @@ QStringList QNetworkAccessManagerPrivate::backendSupportedSchemes() const return QStringList(); } +/*! + \class QNetworkAccessBackendFactory + \brief QNetworkAccessBackendFactory is the base class to inherit + from for Qt to instantiate and query your QNetworkAccessBackend + plugin. + \since 6.0 + \internal + + //![semi-private-notice] + The class is considered semi-private and as such requires linking + to "NetworkPrivate" to access the header. Furthermore it means + the class is not under the same binary compatibility restrictions + as the rest of Qt. While we still try to avoid breakage it may + still occur. The class is primarily meant to be used by plugins + which would be recompiled every time Qt is updated. + //![semi-private-notice] + + This class acts as the primary interface to the plugin and must + be derived from. It deals with both querying supported schemes + and the creation of QNetworkAccessBackend + + Since they are both abstract function you are required to + implement supportedSchemes() and create(). +*/ + +/*! + \fn QStringList QNetworkAccessBackendFactory::supportedSchemes() const + + Override this method in your own derived class to let Qt know + what schemes your class can handle. +*/ + +/*! + \fn QNetworkAccessBackendFactory::create(QNetworkAccessManager::Operation op, const QNetworkRequest &request) const + + Override this method in your own class and return a + heap-allocated instance of your class derived from + QNetworkAccessBackend. + + If \a op or a property of \a request is not supported (for + example the URL's scheme) then you must return \nullptr. + + \sa QNetworkRequest::attribute(), QNetworkRequest::url(), QUrl::scheme() +*/ + +/*! + \class QNetworkAccessBackend + \brief QNetworkAccessBackend is the base class for implementing + support for schemes used by QNetworkAccessManager. + \since 6.0 + \internal + + \snippet qnetworkaccessbackend.cpp semi-private-notice + + This class can be derived from to add support for further schemes + in QNetworkAccessManager. + + The design of QNetworkAccessBackend makes it possible to specialize + behavior as needed for certain backends. + This was done using the (currently) 3 enums TargetType, + SecurityFeatures and IOFeatures. For example while only open() + and close() are abstract functions you are also required to + implement either read() or readPointer() and advanceReadPointer() + depending on whether you enable IOFeature::ZeroCopy or not. + Read more about it in the documentation for each of the + enumerators. + + \sa TargetType, SecurityFeatures, IOFeatures +*/ + /*! \enum QNetworkAccessBackend::TargetType @@ -276,6 +346,47 @@ bool QNetworkAccessBackend::start() return true; } +/*! + \fn void QNetworkAccessBackend::open() = 0 + + You must implement this in your derived class. + During this call you must open the connection and begin the request + (see: request()). + + As the connection progresses you must call the various public and + protected slots on QNetworkAccessBackend. As an example, when you have + received some data you must call readyRead(). And when all the data has been + received you must call finished(). This could, for example, be done by + binding signals inside your own implementation to the slots, or by calling + them directly. + + \sa close() +*/ + +/*! + \fn void QNetworkAccessBackend::close() = 0 + + You must implement this function in your derived class. + This function gets called when the QNetworkReply is closed or aborted. + + You should not emit an error or call finished() during this call since + QtNetwork will set and emit the \c{QNetworkReply::OperationCanceledError} + error by itself after control flow returns from this function. +*/ + +/*! + \fn qint64 QNetworkAccessBackend::bytesAvailable() const = 0 + + You must implement this function in your derived class. + This function is called at various times. It may be called because the user + called QNetworkReply::bytesAvailable(), and it may be called before an + attempt to read is made. + + While this function doesn't technically need to return an accurate number, + it may result in reduced performance if it does not. This function must + return zero if there are no bytes available. +*/ + #if QT_CONFIG(ssl) /*! Passes a \a configuration with the user's desired TLS