diff options
author | Mårten Nordheim <marten.nordheim@qt.io> | 2020-12-07 14:51:24 +0100 |
---|---|---|
committer | Mårten Nordheim <marten.nordheim@qt.io> | 2021-09-01 14:51:29 +0000 |
commit | 81a9335c653661f70d8bfa8f37d2d72bdef60d41 (patch) | |
tree | 30a85deacc657af491ae95ab81e39d0ac8ff9091 /src/network/access/qnetworkaccessbackend.cpp | |
parent | 81a7344e1dea562271865ddf94a7d7138e663ce4 (diff) |
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 <edward.welbourne@qt.io>
Diffstat (limited to 'src/network/access/qnetworkaccessbackend.cpp')
-rw-r--r-- | src/network/access/qnetworkaccessbackend.cpp | 111 |
1 files changed, 111 insertions, 0 deletions
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 @@ -126,6 +126,76 @@ QStringList QNetworkAccessManagerPrivate::backendSupportedSchemes() const } /*! + \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 Use the values in this enum to specify what type of target @@ -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 |