philipp/qhttpengine
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update documentation to reflect new class names.

Browse Source
This commit is contained in:
Nathan Osman
2017-07-08 12:26:23 -07:00
parent 5c57fda4a8
commit 2df0aa0709
12 changed files with 104 additions and 173 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
doc/index.md
View File

@@ -23,7 +23,6 @@ QHttpEngine is designed in a portable way, so it may run on other compilers and
QHttpEngine uses CMake for building the library. The library recognizes four options during configuration, all of which are disabled by default (the library is built as a shared library):
- `BUILD_STATIC` - build and link a static library instead of a shared library
- `BUILD_DOC` - (requires Doxygen) generates documentation from the comments in the source code
- `BUILD_EXAMPLES` - builds the sample applications that demonstrate how to use QHttpEngine
- `BUILD_TESTS` - build the test suite
@@ -36,18 +35,18 @@ QHttpEngine includes all of the classes you will need to build your HTTP server
### Socket
In order to create an HTTP socket, create an instance of QHttpSocket and pass a QTcpSocket* in the constructor:
In order to create an HTTP socket, create an instance of [Socket](@ref QHttpEngine::Socket) and pass a QTcpSocket* in the constructor:
@code
QTcpSocket *tcpSocket = ...
QHttpSocket httpSocket(tcpSocket);
QHttpEngine::Socket httpSocket(tcpSocket);
@endcode
Once the QHttpSocket::headersParsed() signal is emitted (and QHttpSocket::isHeadersParsed() returns true), information about the request can easily be retrieved:
Once the [headersParsed()](@ref QHttpEngine::Socket::headersParsed) signal is emitted (and [isHeadersParsed()](@ref QHttpEngine::Socket::isHeadersParsed) returns true), information about the request can easily be retrieved:
@code
// Check if the method is GET
bool isGet = httpSocket.method() == QHttpSocket::GET;
bool isGet = httpSocket.method() == QHttpEngine::Socket::GET;
// Retrieve the path
QString path = httpSocket.path();
@@ -56,40 +55,40 @@ QString path = httpSocket.path();
QByteArray userAgent = httpSocket.headers().value("User-Agent");
@endcode
Because QHttpSocket derives from QIODevice, writing a response to the client is very simple:
Because [Socket](@ref QHttpEngine::Socket) derives from QIODevice, writing a response to the client is very simple:
@code
httpSocket.setStatusCode(QHttpSocket::OK);
httpSocket.setStatusCode(QHttpEngine::Socket::OK);
httpSocket.setHeader("Content-Type", "text/plain");
httpSocket.writeHeaders();
httpSocket.write("This is a sample message.");
@endcode
Writing a local file to the socket can be done with little effort by using the QIODeviceCopier class:
Writing a local file to the socket can be done with little effort by using the [QIODeviceCopier](@ref QHttpEngine::QIODeviceCopier) class:
@code
QFile file("somefile.txt");
file.open(QIODevice::ReadOnly);
QIODeviceCopier copier(&file, &httpSocket);
QHttpEngine::QIODeviceCopier copier(&file, &httpSocket);
copier.start();
// Wait for QIODeviceCopier::finished() signal
// Wait for the finished() signal from copier
@endcode
### Server
To create an HTTP server, simply create an instance of the QHttpServer class:
To create an HTTP server, simply create an instance of the [Server](@ref QHttpEngine::Server) class:
@code
QHttpServer server;
QHttpEngine::Server server;
server.listen();
@endcode
In order to route requests based on their path, a handler must be used. Handlers derive from the QHttpHandler class. The simplest of these is the QFilesystemHandler class:
In order to route requests based on their path, a handler must be used. Handlers derive from the [Handler](@ref QHttpEngine::Handler) class. The simplest of these is the [FilesystemHandler](@ref QHttpEngine::FilesystemHandler) class:
@code
QFilesystemHandler handler("/var/www");
QHttpEngine::FilesystemHandler handler("/var/www");
server.setHandler(&handler);
@endcode
@@ -97,20 +96,20 @@ A request to `/path` will cause the server to respond with the contents of `/var
### Slot Methods
Although it is possible to create a handler that manually routes requests, it is far easier to use the QObjectHandler class and register slots for each path - you can even use the new connection syntax:
Although it is possible to create a handler that manually routes requests, it is far easier to use the [QObjectHandler](@ref QHttpEngine::QObjectHandler) class and register slots for each path - you can even use the new connection syntax:
@code
class Api : public QObject
{
Q_OBJECT
public slots:
void doSomething(QHttpSocket *socket);
void doSomethingElse(QHttpSocket *socket);
void doSomething(QHttpEngine::Socket *socket);
void doSomethingElse(QHttpEngine::Socket *socket);
};
Api api;
QObjectHandler handler;
QHttpEngine::QObjectHandler handler;
handler.registerMethod("something", &api, &Api::doSomething);
@endcode
@@ -118,5 +117,5 @@ A request to `/something` will cause the `doSomething()` slot to be invoked.
## Where to Go From Here
- Middleware can be used to process requests before final routing: QHttpMiddleware
- Authentication middleware can be used to restrict access: QHttpBasicAuth, QLocalAuth
- Middleware can be used to process requests before final routing: [Middleware](@ref QHttpEngine::Middleware)
- Authentication middleware can be used to restrict access: [BasicAuthMiddleware](@ref QHttpEngine::BasicAuthMiddleware), [LocalAuthMiddleware](@ref QHttpEngine::LocalAuthMiddleware)

2
src/include/qhttpengine/basicauthmiddleware.h
View File

@@ -33,7 +33,7 @@ namespace QHttpEngine
class QHTTPENGINE_EXPORT BasicAuthMiddlewarePrivate;
/**
* @brief Middleware for HTTP basic authentication
* @brief %Middleware for HTTP basic authentication
*
* HTTP Basic authentication allows access to specific resources to be
* restricted. This class uses a map to store accepted username/password

6
src/include/qhttpengine/filesystemhandler.h
View File

@@ -33,7 +33,7 @@ namespace QHttpEngine
class QHTTPENGINE_EXPORT FilesystemHandlerPrivate;
/**
* @brief Handler for filesystem requests
* @brief %Handler for filesystem requests
*
* This handler responds to requests for resources on a local filesystem. The
* constructor is provided with a path to the root directory, which will be
@@ -41,7 +41,7 @@ class QHTTPENGINE_EXPORT FilesystemHandlerPrivate;
* serves files from the /var/www directory:
*
* @code
* QFilesystemHandler handler("/var/www");
* QHttpEngine::FilesystemHandler handler("/var/www");
* @endcode
*
* Requests for resources outside the root will be ignored. The document root
@@ -75,7 +75,7 @@ public:
protected:
/**
* @brief Reimplementation of QHttpHandler::process()
* @brief Reimplementation of [Handler::process()](QHttpEngine::Handler::process)
*/
virtual void process(Socket *socket, const QString &path);

23
src/include/qhttpengine/handler.h
View File

@@ -40,12 +40,13 @@ class QHTTPENGINE_EXPORT HandlerPrivate;
/**
* @brief Base class for HTTP handlers
*
* When a request is received by a QHttpServer, it invokes the route() method
* of the root handler which is used to determine what happens to the request.
* All HTTP handlers derive from this class and should override the protected
* process() method in order to process the request. Each handler also
* maintains a list of redirects and sub-handlers which are used in place of
* invoking process() when one of the patterns match.
* When a request is received by a [Server](@ref QHttpEngine::Server), it
* invokes the route() method of the root handler which is used to determine
* what happens to the request. All HTTP handlers derive from this class and
* should override the protected process() method in order to process the
* request. Each handler also maintains a list of redirects and sub-handlers
* which are used in place of invoking process() when one of the patterns
* match.
*
* To add a redirect, use the addRedirect() method. The first parameter is a
* QRegExp pattern that the request path will be tested against. If it
@@ -53,7 +54,7 @@ class QHTTPENGINE_EXPORT HandlerPrivate;
* closed. For example, to have the root path "/" redirect to "/index.html":
*
* @code
* QHttpHandler handler;
* QHttpEngine::Handler handler;
* handler.addRedirect(QRegExp("^$"), "/index.html");
* @endcode
*
@@ -64,7 +65,7 @@ class QHTTPENGINE_EXPORT HandlerPrivate;
* invoked when the path begins with "/api/":
*
* @code
* QHttpHandler handler, subHandler;
* QHttpEngine::Handler handler, subHandler;
* handler.addSubHandler(QRegExp("^api/"), &subHandler);
* @endcode
*
@@ -121,8 +122,10 @@ protected:
* @brief Process a request
*
* This method should process the request either by fulfilling it, sending
* a redirect with QHttpSocket::writeRedirect(), or writing an error to
* the socket using QHttpSocket::writeError().
* a redirect with
* [Socket::writeRedirect()](@ref QHttpEngine::Socket::writeRedirect), or
* writing an error to the socket using
* [Socket::writeError()](@ref QHttpEngine::Socket::writeError).
*/
virtual void process(Socket *socket, const QString &path);

8
src/include/qhttpengine/localauthmiddleware.h
View File

@@ -35,12 +35,12 @@ namespace QHttpEngine
class QHTTPENGINE_EXPORT LocalAuthMiddlewarePrivate;
/**
* @brief Middleware for local file-based authentication
* @brief %Middleware for local file-based authentication
*
* This class is intended for authenticating applications running under the
* same user account as the server. QLocalFile is used to expose a token to
* connecting applications. The client passes the token in a special header
* and the request is permitted.
* same user account as the server. [LocalFile](@ref QHttpEngine::LocalFile)
* is used to expose a token to connecting applications. The client passes the
* token in a special header and the request is permitted.
*
* The file consists of a JSON object in the following format:
*

2
src/include/qhttpengine/localfile.h
View File

@@ -40,7 +40,7 @@ class QHTTPENGINE_EXPORT LocalFilePrivate;
* typically used for storing authentication tokens:
*
* @code
* LocalFile file;
* QHttpEngine::LocalFile file;
* if (file.open()) {
* file.write("private data");
* file.close();

4
src/include/qhttpengine/proxyhandler.h
View File

@@ -35,7 +35,7 @@ namespace QHttpEngine
class QHTTPENGINE_EXPORT ProxyHandlerPrivate;
/**
* @brief Handler that routes HTTP requests to an upstream server
* @brief %Handler that routes HTTP requests to an upstream server
*/
class QHTTPENGINE_EXPORT ProxyHandler : public Handler
{
@@ -51,7 +51,7 @@ public:
protected:
/**
* @brief Reimplementation of QHttpHandler::process()
* @brief Reimplementation of [Handler::process()](QHttpEngine::Handler::process)
*/
virtual void process(Socket *socket, const QString &path);

2
src/include/qhttpengine/qiodevicecopier.h
View File

@@ -46,7 +46,7 @@ class QHTTPENGINE_EXPORT QIODeviceCopierPrivate;
* QFile srcFile("src.txt");
* QFile destFile("dest.txt");
*
* QIODeviceCopier copier(&srcFile, &destFile);
* QHttpEngine::QIODeviceCopier copier(&srcFile, &destFile);
* copier.start()
* @endcode
*

18
src/include/qhttpengine/qobjecthandler.h
View File

@@ -35,12 +35,12 @@ class Socket;
class QHTTPENGINE_EXPORT QObjectHandlerPrivate;
/**
* @brief Handler for invoking slots
* @brief %Handler for invoking slots
*
* This handler enables incoming requests to be processed by slots in a
* QObject-derived class or functor. Methods are registered by providing a
* name and slot to invoke. The slot may take a pointer to the QHttpSocket for
* the request as an argument.
* name and slot to invoke. The slot may take a pointer to the
* [Socket](@ref QHttpEngine::Socket) for the request as an argument.
*
* To use this class, simply create an instance and call the appropriate
* registerMethod() overload. For example:
@@ -50,13 +50,13 @@ class QHTTPENGINE_EXPORT QObjectHandlerPrivate;
* {
* Q_OBJECT
* public slots:
* void something(QHttpSocket *socket);
* void something(QHttpEngine::Socket *socket);
* };
*
* QObjectHandler handler;
* QHttpEngine::QObjectHandler handler;
* Object object;
* // Old connection syntax
* handler.registerMethod("something", &object, SLOT(something(QHttpSocket*)));
* handler.registerMethod("something", &object, SLOT(something(QHttpEngine::Socket*)));
* // New connection syntax
* handler.registerMethod("something", &object, &Object::something);
* @endcode
@@ -65,8 +65,8 @@ class QHTTPENGINE_EXPORT QObjectHandlerPrivate;
* to create a class and slot:
*
* @code
* QObjectHandler handler;
* handler.registerMethod("something", [](QHttpSocket *socket) {
* QHttpEngine::QObjectHandler handler;
* handler.registerMethod("something", [](QHttpEngine::Socket *socket) {
* // do something
* });
* @endcode
@@ -159,7 +159,7 @@ public:
protected:
/**
* @brief Reimplementation of QHttpHandler::process()
* @brief Reimplementation of [Handler::process()](QHttpEngine::Handler::process)
*/
virtual void process(Socket *socket, const QString &path);

126
src/include/qhttpengine/range.h
View File

@@ -40,24 +40,23 @@ class QHTTPENGINE_EXPORT RangePrivate;
* created, optional dataSize can be specified, so that relative ranges can
* be represented as absolute.
*
* Example:
* @code
* QHttpRange range(10, -1, 90);
* QHttpEngine::Range range(10, -1, 90);
* range.from(); // 10
* range.to(); // 89
* range.length(); // 80
*
* range = QHttpRange("-500", 1000);
* range = QHttpEngine::Range("-500", 1000);
* range.from(); // 500
* range.to(); // 999
* range.length(); // 500
*
* range = QHttpRange(0, -1);
* range = QHttpEngine::Range(0, -1);
* range.from(); // 0
* range.to(); // -1
* range.length(); // -1
*
* range = QHttpRange(range, 100);
* range = QHttpEngine::Range(range, 100);
* range.from(); // 0
* range.to(); // 99
* range.length(); // 100
@@ -78,8 +77,8 @@ public:
/**
* @brief Construct a range from the provided string
*
* Parses string representation range and constructs new Range.
* For raw header "Range: bytes=0-100" only "0-100" should be passed to
* Parses string representation range and constructs new Range. For raw
* header "Range: bytes=0-100" only "0-100" should be passed to
* constructor. dataSize may be supplied so that relative ranges could be
* represented as absolute values.
*/
@@ -89,16 +88,16 @@ public:
* @brief Construct a range from the provided offsets
*
* Initialises a new Range with from and to values. dataSize may be
* supplied so that relative ranges could be represented as
* absolute values.
* supplied so that relative ranges could be represented as absolute
* values.
*/
Range(qint64 from, qint64 to, qint64 dataSize = -1);
/**
* @brief Construct a range from the another range's offsets
*
* Initialises a new Range with from and to values of other
* QHttpRequest. Supplied dataSize is used instead of other dataSize.
* Initialises a new Range with from and to values of other Range.
* Supplied dataSize is used instead of other dataSize.
*/
Range(const Range &other, qint64 dataSize);
@@ -113,104 +112,32 @@ public:
Range& operator=(const Range &other);
/**
* @brief Return starting position of range
* @brief Retrieve starting position of range
*
* If range is set as 'last N bytes' and dataSize is not set, returns -N.
*
* Example:
* @code
* QHttpRange range("-500");
* range.from(); // -500
* range.to(); // -1
* range.length(); // 500
*
* range = QHttpRange(range, 800);
* range.from(); // 300
* range.to(); // 799
* range.length(); // 500
*
* range = QHttpRange("10-");
* range.from(); // 10
* range.to(); // -1
* range.length(); // -1
*
* range = QHttpRange(range, 100);
* range.from(); // 10
* range.to(); // 99
* range.length(); // 90
* @endcode
*
*/
qint64 from() const;
/**
* @brief Returns ending position of range.
* @brief Retrieve ending position of range
*
* If range is set as 'last N bytes' and dataSize is not set, returns -1.
* If ending position is not set, and dataSize is not set, returns -1.
*
* Example:
* @code
* QHttpRange range("-500");
* range.from(); // -500
* range.to(); // -1
* range.length(); // 500
*
* range = QHttpRange(range, 800);
* range.from(); // 300
* range.to(); // 799
* range.length(); // 500
*
* range = QHttpRange("10-");
* range.from(); // 10
* range.to(); // -1
* range.length(); // -1
*
* range = QHttpRange(range, 100);
* range.from(); // 10
* range.to(); // 99
* range.length(); // 90
* @endcode
*
*/
qint64 to() const;
/**
* @brief Returns length of range.
* @brief Retrieve length of range
*
* If ending position is not set, and dataSize is not set, and range is
* not set as 'last N bytes', returns -1. If range is invalid, returns -1.
*
* Example:
* @code
* QHttpRange range("-500");
* range.from(); // -500
* range.to(); // -1
* range.length(); // 500
*
* range = QHttpRange(range, 800);
* range.from(); // 300
* range.to(); // 799
* range.length(); // 500
*
* range = QHttpRange("10-");
* range.from(); // 10
* range.to(); // -1
* range.length(); // -1
*
* range = QHttpRange(range, 100);
* range.from(); // 10
* range.to(); // 99
* range.length(); // 90
* @endcode
*
*/
qint64 length() const;
/**
* @brief Returns dataSize of range.
* @brief Retrieve dataSize of range
*
* If dataSize is not set, returns -1.
* If dataSize is not set, this method returns -1.
*/
qint64 dataSize() const;
@@ -219,46 +146,45 @@ public:
*
* Range is considered invalid if it is out of bounds, that is when this
* inequality is false - (from <= to < dataSize).
*
* When QHttpRange(const QString&) fails to parse range string, resulting
* range is also considered invalid.
*
* Example:
* @code
* QHttpRange range(1, 0, -1);
* QHttpEngine::Range range(1, 0, -1);
* range.isValid(); // false
*
* range = QHttpRange(512, 1024);
* range = QHttpEngine::Range(512, 1024);
* range.isValid(); // true
*
* range = QHttpRange("-");
* range = QHttpEngine::Range("-");
* range.isValid(); // false
*
* range = QHttpRange("abccbf");
* range = QHttpEngine::Range("abccbf");
* range.isValid(); // false
*
* range = QHttpRange(0, 512, 128);
* range = QHttpEngine::Range(0, 512, 128);
* range.isValid(); // false
*
* range = QHttpRange(128, 64, 512);
* range = QHttpEngine::Range(128, 64, 512);
* range.isValid(); // false
* @endcode
*/
bool isValid() const;
/**
* @brief Returns representation suitable for Content-Range header.
* @brief Retrieve representation suitable for Content-Range header
*
* Example:
* @code
* QHttpRange range(0, 100, 1000);
* QHttpEngine::Range range(0, 100, 1000);
* range.contentRange(); // "0-100/1000"
*
* // When resource size is unknown
* range = QHttpRange(512, 1024);
* range = QHttpEngine::Range(512, 1024);
* range.contentRange(); // "512-1024/*"
*
* // if range request was bad, return resource size
* range = QHttpRange(1, 0, 1200);
* range = QHttpEngine::Range(1, 0, 1200);
* range.contentRange(); // "*\/1200"
* @endcode
*/

22
src/include/qhttpengine/server.h
View File

@@ -44,25 +44,27 @@ class QHTTPENGINE_EXPORT ServerPrivate;
* @brief TCP server for HTTP requests
*
* This class provides a TCP server that listens for HTTP requests on the
* specified address and port. When a new request is received, a QHttpSocket
* is created for the QTcpSocket which abstracts a TCP server socket. Once the
* request headers are received, the root handler is invoked and the request
* processed. The QHttpSocket assumes ownership of the QTcpSocket.
* specified address and port. When a new request is received, a
* [Socket](@ref QHttpEngine::Socket) is created for the QTcpSocket which
* abstracts a TCP server socket. Once the request headers are received, the
* root handler is invoked and the request processed. The server assumes
* ownership of the QTcpSocket.
*
* Because QHttpServer derives from QTcpServer, instructing the server to
* listen on an available port is as simple as invoking listen() with no
* parameters:
* Because [Server](@ref QHttpEngine::Server) derives from QTcpServer,
* instructing the server to listen on an available port is as simple as
* invoking listen() with no parameters:
*
* @code
* QHttpServer server;
* QHttpEngine::Server server;
* if (!server.listen()) {
* // error handling
* }
* @endcode
*
* Before passing the socket to the handler, the QTcpSocket's disconnected()
* signal is connected to the QHttpSocket's deleteLater() slot to ensure that
* the socket is deleted when the client disconnects.
* signal is connected to the [Socket](@ref QHttpEngine::Socket)'s
* deleteLater() slot to ensure that the socket is deleted when the client
* disconnects.
*/
class QHTTPENGINE_EXPORT Server : public QTcpServer
{

25
src/include/qhttpengine/socket.h
View File

@@ -42,18 +42,18 @@ class QHTTPENGINE_EXPORT SocketPrivate;
/**
* @brief Implementation of the HTTP protocol
*
* QHttpSocket provides a class derived from QIODevice that can be used to
* read data from and write data to an HTTP client through a QTcpSocket
* provided in the constructor. The QHttpSocket will assume ownership of the
* socket and ensure it is properly deleted. Consequently, the QTcpSocket must
* have been allocated on the heap:
* This class provides a class derived from QIODevice that can be used to read
* data from and write data to an HTTP client through a QTcpSocket provided in
* the constructor. The socket will assume ownership of the QTcpSocket and
* ensure it is properly deleted. Consequently, the QTcpSocket must have been
* allocated on the heap:
*
* @code
* QTcpSocket *tcpSock = new QTcpSocket;
* tcpSock->connectToHost(...);
* tcpSock->waitForConnected();
*
* QHttpSocket *httpSock = new QHttpSocket(tcpSock);
* QHttpEngine::Socket *httpSock = new QHttpEngine::Socket(tcpSock);
* @endcode
*
* Once the headersParsed() signal is emitted, information about the request
@@ -107,7 +107,8 @@ public:
/**
* @brief Map consisting of HTTP headers
*
* The key used for the map is the QIByteArray class, which allows for
* The key used for the map is the
* [IByteArray](@ref QHttpEngine::IByteArray) class, which allows for
* case-insensitive comparison.
*/
typedef QMultiMap<IByteArray, QByteArray> HeaderMap;
@@ -147,7 +148,7 @@ public:
Created = 201,
/// Request was accepted for processing, not completed yet.
Accepted = 202,
/// Range request was successful
/// %Range request was successful
PartialContent = 206,
/// Resource has moved permanently
MovedPermanently = 301,
@@ -169,16 +170,16 @@ public:
InternalServerError = 500,
/// Invalid response from server while acting as a gateway
BadGateway = 502,
/// Server unable to handle request due to overload
/// %Server unable to handle request due to overload
ServiceUnavailable = 503,
/// Server does not supports the HTTP version in the request
/// %Server does not supports the HTTP version in the request
HttpVersionNotSupported = 505
};
/**
* @brief Create a new QHttpSocket from a QTcpSocket
* @brief Create a new socket from a QTcpSocket
*
* This instance will assume ownership of the socket. That is, it will
* This instance will assume ownership of the QTcpSocket. That is, it will
* make itself the parent of the socket.
*/
Socket(QTcpSocket *socket, QObject *parent = 0);