Stellarium
0.17.0
|
Data Structures | |
struct | HttpConnectionHandlerSettings |
Contains all settings for the connection handler. More... | |
class | HttpConnectionHandler |
The connection handler accepts incoming connections and dispatches incoming requests to to a request mapper. More... | |
struct | HttpConnectionHandlerPoolSettings |
Contains all settings for the connection handler pool and the child connection handlers. More... | |
class | HttpConnectionHandlerPool |
Pool of http connection handlers. More... | |
class | HttpCookie |
HTTP cookie as defined in RFC 2109. More... | |
struct | HttpListenerSettings |
Contains all settings for HttpListener and supporting classes. More... | |
class | HttpListener |
Listens for incoming TCP connections and and passes all incoming HTTP requests to your implementation of HttpRequestHandler, which processes the request and generates the response (usually a HTML document). More... | |
class | HttpRequest |
This object represents a single HTTP request. More... | |
class | HttpRequestHandler |
The request handler generates a response for each HTTP request. More... | |
class | HttpResponse |
This object represents a HTTP response, used to return something to the web client. More... | |
struct | StaticFileControllerSettings |
Contains all the settings for the StaticFileController. More... | |
class | StaticFileController |
Delivers static files. More... | |
class | ITemplateTranslationProvider |
Interface for Template::translate calls. More... | |
Typedefs | |
typedef int | tSocketDescriptor |
Alias type definition, for compatibility to different Qt versions. | |
typedef QSslConfiguration | HttpSslConfiguration |
Alias for QSslConfiguration if OpenSSL is not supported. | |
Functions | |
DECLSPEC const char * | getQtWebAppLibVersion () |
Get the library version number. | |
The QtWebApp library is developed by Stefan Frings (http://stefanfrings.de/qtwebapp/index-en.html). It is used by the Stellarium Remote Control Plug-in to provide the HTTP server that serves the plugin's API.
Some changes have been made to the library to fit it better into Stellarium. The main differences are:
struct HttpConnectionHandlerSettings |
Data Fields | |
int | readTimeout |
Defines the maximum time to wait for a complete HTTP request in msec. More... | |
int | maxRequestSize |
Maximum size of a request in bytes. More... | |
int | maxMultipartSize |
Maximum size of a multipart request in bytes. More... | |
int HttpConnectionHandlerSettings::maxMultipartSize |
Default 1048576 (1MB)
int HttpConnectionHandlerSettings::maxRequestSize |
Default 16384.
int HttpConnectionHandlerSettings::readTimeout |
Default 10000.
class HttpConnectionHandler |
Since HTTP clients can send multiple requests before waiting for the response, the incoming requests are queued and processed one after the other.
Example for the required configuration settings:
readTimeout=60000 maxRequestSize=16000 maxMultiPartSize=1000000
The readTimeout value defines the maximum time to wait for a complete HTTP request.
Public Slots | |
void | handleConnection (tSocketDescriptor socketDescriptor) |
Received from from the listener, when the handler shall start processing a new connection. More... | |
Public Member Functions | |
HttpConnectionHandler (const HttpConnectionHandlerSettings &settings, HttpRequestHandler *requestHandler, HttpSslConfiguration *sslConfiguration=Q_NULLPTR) | |
Constructor. More... | |
virtual | ~HttpConnectionHandler () |
Destructor. | |
bool | isBusy () |
Returns true, if this handler is in use. More... | |
void | setBusy () |
Mark this handler as busy. | |
HttpConnectionHandler::HttpConnectionHandler | ( | const HttpConnectionHandlerSettings & | settings, |
HttpRequestHandler * | requestHandler, | ||
HttpSslConfiguration * | sslConfiguration = Q_NULLPTR |
||
) |
settings | Configuration settings of the HTTP webserver |
requestHandler | Handler that will process each incoming HTTP request |
sslConfiguration | SSL (HTTPS) will be used if not Q_NULLPTR |
|
slot |
socketDescriptor | references the accepted connection. |
bool HttpConnectionHandler::isBusy | ( | ) |
struct HttpConnectionHandlerPoolSettings |
Data Fields | |
int | minThreads |
The minimal number of threads kept in the pool at all times. More... | |
int | maxThreads |
The maximal number of threads. More... | |
int | cleanupInterval |
The time after which inactive threads are stopped in msec. More... | |
QString | sslKeyFile |
The file path to the SSL key file. More... | |
QString | sslCertFile |
The file path to the SSL cert file. More... | |
Data Fields inherited from HttpConnectionHandlerSettings | |
int | readTimeout |
Defines the maximum time to wait for a complete HTTP request in msec. More... | |
int | maxRequestSize |
Maximum size of a request in bytes. More... | |
int | maxMultipartSize |
Maximum size of a multipart request in bytes. More... | |
int HttpConnectionHandlerPoolSettings::cleanupInterval |
Default 1000.
int HttpConnectionHandlerPoolSettings::maxThreads |
If a new connection arrives when this amount of threads is already busy, the new connection will be dropped. Default 100.
int HttpConnectionHandlerPoolSettings::minThreads |
Default 1.
QString HttpConnectionHandlerPoolSettings::sslCertFile |
Default empty.
QString HttpConnectionHandlerPoolSettings::sslKeyFile |
Default empty.
class HttpConnectionHandlerPool |
The size of the pool grows and shrinks on demand.
Example for the required configuration settings:
minThreads=4 maxThreads=100 cleanupInterval=60000 readTimeout=60000 ;sslKeyFile=ssl/my.key ;sslCertFile=ssl/my.cert maxRequestSize=16000 maxMultiPartSize=1000000
After server start, the size of the thread pool is always 0. Threads are started on demand when requests come in. The cleanup timer reduces the number of idle threads slowly by closing one thread in each interval. But the configured minimum number of threads are kept running.
For SSL support, you need an OpenSSL certificate file and a key file. Both can be created with the command
openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout my.key -out my.cert
Visit http://slproweb.com/products/Win32OpenSSL.html to download the Light version of OpenSSL for Windows.
Please note that a listener with SSL settings can only handle HTTPS protocol. To support both HTTP and HTTPS simultaneously, you need to start two listeners on different ports - one with SLL and one without SSL.
Public Member Functions | |
HttpConnectionHandlerPool (const HttpConnectionHandlerPoolSettings &settings, HttpRequestHandler *requestHandler) | |
Constructor. More... | |
virtual | ~HttpConnectionHandlerPool () |
Destructor. | |
HttpConnectionHandler * | getConnectionHandler () |
Get a free connection handler, or 0 if not available. More... | |
HttpConnectionHandlerPool::HttpConnectionHandlerPool | ( | const HttpConnectionHandlerPoolSettings & | settings, |
HttpRequestHandler * | requestHandler | ||
) |
settings | Configuration settings for the HTTP server. Must not be 0. |
requestHandler | The handler that will process each received HTTP request. |
HttpConnectionHandler* HttpConnectionHandlerPool::getConnectionHandler | ( | ) |
class HttpCookie |
This class can also parse RFC 2965 cookies, but skips fields that are not defined in RFC 2109.
Public Member Functions | |
HttpCookie () | |
Creates an empty cookie. | |
HttpCookie (const QByteArray name, const QByteArray value, const int maxAge, const QByteArray path="/", const QByteArray comment=QByteArray(), const QByteArray domain=QByteArray(), const bool secure=false) | |
Create a cookie and set name/value pair. More... | |
HttpCookie (const QByteArray source) | |
Create a cookie from a string. More... | |
QByteArray | toByteArray () const |
Convert this cookie to a string that may be used in a Set-Cookie header. More... | |
void | setName (const QByteArray name) |
Set the name of this cookie. | |
void | setValue (const QByteArray value) |
Set the value of this cookie. | |
void | setComment (const QByteArray comment) |
Set the comment of this cookie. | |
void | setDomain (const QByteArray domain) |
Set the domain of this cookie. | |
void | setMaxAge (const int maxAge) |
Set the maximum age of this cookie in seconds. More... | |
void | setPath (const QByteArray path) |
Set the path for that the cookie will be sent, default="/" which means the whole domain. | |
void | setSecure (const bool secure) |
Set secure mode, so that the cookie will only be sent on secure connections. | |
QByteArray | getName () const |
Get the name of this cookie. | |
QByteArray | getValue () const |
Get the value of this cookie. | |
QByteArray | getComment () const |
Get the comment of this cookie. | |
QByteArray | getDomain () const |
Get the domain of this cookie. | |
int | getMaxAge () const |
Set the maximum age of this cookie in seconds. More... | |
QByteArray | getPath () const |
Set the path of this cookie. | |
bool | getSecure () const |
Get the secure flag of this cookie. | |
int | getVersion () const |
Returns always 1. | |
Static Public Member Functions | |
static QList< QByteArray > | splitCSV (const QByteArray source) |
Split a string list into parts, where each part is delimited by semicolon. More... | |
HttpCookie::HttpCookie | ( | const QByteArray | name, |
const QByteArray | value, | ||
const int | maxAge, | ||
const QByteArray | path = "/" , |
||
const QByteArray | comment = QByteArray() , |
||
const QByteArray | domain = QByteArray() , |
||
const bool | secure = false |
||
) |
name | name of the cookie |
value | value of the cookie |
maxAge | maximum age of the cookie in seconds. 0=discard immediately |
path | Path for that the cookie will be sent, default="/" which means the whole domain |
comment | Optional comment, may be displayed by the web browser somewhere |
domain | Optional domain for that the cookie will be sent. Defaults to the current domain |
secure | If true, the cookie will only be sent on secure connections |
HttpCookie::HttpCookie | ( | const QByteArray | source | ) |
source | String as received in a HTTP Cookie2 header. |
int HttpCookie::getMaxAge | ( | ) | const |
void HttpCookie::setMaxAge | ( | const int | maxAge | ) |
0=discard immediately
|
static |
Semicolons within double quotes are skipped. Double quotes are removed.
QByteArray HttpCookie::toByteArray | ( | ) | const |
struct HttpListenerSettings |
Data Fields | |
QString | host |
The local IP address to bind to. More... | |
int | port |
The HTTP port to use. More... | |
Data Fields inherited from HttpConnectionHandlerPoolSettings | |
int | minThreads |
The minimal number of threads kept in the pool at all times. More... | |
int | maxThreads |
The maximal number of threads. More... | |
int | cleanupInterval |
The time after which inactive threads are stopped in msec. More... | |
QString | sslKeyFile |
The file path to the SSL key file. More... | |
QString | sslCertFile |
The file path to the SSL cert file. More... | |
Data Fields inherited from HttpConnectionHandlerSettings | |
int | readTimeout |
Defines the maximum time to wait for a complete HTTP request in msec. More... | |
int | maxRequestSize |
Maximum size of a request in bytes. More... | |
int | maxMultipartSize |
Maximum size of a multipart request in bytes. More... | |
QString HttpListenerSettings::host |
Default empty (listen on all interfaces).
int HttpListenerSettings::port |
Default 8080.
class HttpListener |
Example for the required settings in the config file:
;host=192.168.0.100 port=8080 minThreads=1 maxThreads=10 cleanupInterval=1000 readTimeout=60000 ;sslKeyFile=ssl/my.key ;sslCertFile=ssl/my.cert maxRequestSize=16000 maxMultiPartSize=1000000
The optional host parameter binds the listener to one network interface. The listener handles all network interfaces if no host is configured. The port number specifies the incoming TCP port that this listener listens to.
Signals | |
void | handleConnection (tSocketDescriptor socketDescriptor) |
Sent to the connection handler to process a new incoming connection. More... | |
Public Member Functions | |
HttpListener (const HttpListenerSettings &settings, HttpRequestHandler *requestHandler, QObject *parent=Q_NULLPTR) | |
Constructor. More... | |
virtual | ~HttpListener () |
Destructor. | |
void | listen () |
Restart listeing after close(). | |
void | close () |
Closes the listener, waits until all pending requests are processed, then closes the connection pool. | |
Protected Member Functions | |
void | incomingConnection (tSocketDescriptor socketDescriptor) |
Serves new incoming connection requests. | |
HttpListener::HttpListener | ( | const HttpListenerSettings & | settings, |
HttpRequestHandler * | requestHandler, | ||
QObject * | parent = Q_NULLPTR |
||
) |
Creates a connection pool and starts listening on the configured host and port.
settings | Configuration settings for the HTTP server. Must not be 0. |
requestHandler | Processes each received HTTP request, usually by dispatching to controller classes. |
parent | Parent object. |
|
signal |
socketDescriptor | references the accepted connection. |
class HttpRequest |
It reads the request from a TCP socket and provides getters for the individual parts of the request.
The follwing config settings are required:
maxRequestSize=16000 maxMultiPartSize=1000000
MaxRequestSize is the maximum size of a HTTP request. In case of multipart/form-data requests (also known as file-upload), the maximum size of the body must not exceed maxMultiPartSize. The body is always a little larger than the file itself.
Public Types | |
enum | RequestStatus { waitForRequest, waitForHeader, waitForBody, complete, abort } |
Values for getStatus() | |
Public Member Functions | |
HttpRequest (const int maxRequestSize, const int maxMultiPartSize) | |
Constructor. More... | |
virtual | ~HttpRequest () |
Destructor. | |
void | readFromSocket (QTcpSocket *socket) |
Read the HTTP request from a socket. More... | |
RequestStatus | getStatus () const |
Get the status of this reqeust. More... | |
QByteArray | getMethod () const |
Get the method of the HTTP request (e.g. More... | |
QByteArray | getPath () const |
Get the decoded path of the HTPP request (e.g. More... | |
const QByteArray & | getRawPath () const |
Get the raw path of the HTTP request (e.g. More... | |
QByteArray | getVersion () const |
Get the version of the HTPP request (e.g. More... | |
QByteArray | getHeader (const QByteArray &name) const |
Get the value of a HTTP request header. More... | |
QList< QByteArray > | getHeaders (const QByteArray &name) const |
Get the values of a HTTP request header. More... | |
QMultiMap< QByteArray, QByteArray > | getHeaderMap () const |
Get all HTTP request headers. | |
QByteArray | getParameter (const QByteArray &name) const |
Get the value of a HTTP request parameter. More... | |
QList< QByteArray > | getParameters (const QByteArray &name) const |
Get the values of a HTTP request parameter. More... | |
QMultiMap< QByteArray, QByteArray > | getParameterMap () const |
Get all HTTP request parameters. More... | |
QByteArray | getBody () const |
Get the HTTP request body. More... | |
QTemporaryFile * | getUploadedFile (const QByteArray fieldName) const |
Get an uploaded file. More... | |
QByteArray | getCookie (const QByteArray &name) const |
Get the value of a cookie. More... | |
QMap< QByteArray, QByteArray > & | getCookieMap () |
Get all cookies. More... | |
QHostAddress | getPeerAddress () const |
Get the address of the connected client. More... | |
Static Public Member Functions | |
static QByteArray | urlDecode (const QByteArray source) |
Decode an URL parameter. More... | |
Friends | |
class | HttpSessionStore |
HttpRequest::HttpRequest | ( | const int | maxRequestSize, |
const int | maxMultiPartSize | ||
) |
settings | Configuration settings |
QByteArray HttpRequest::getBody | ( | ) | const |
QByteArray HttpRequest::getCookie | ( | const QByteArray & | name | ) | const |
name | Name of the cookie |
QMap<QByteArray,QByteArray>& HttpRequest::getCookieMap | ( | ) |
QByteArray HttpRequest::getHeader | ( | const QByteArray & | name | ) | const |
name | Name of the header |
QList<QByteArray> HttpRequest::getHeaders | ( | const QByteArray & | name | ) | const |
name | Name of the header |
QByteArray HttpRequest::getMethod | ( | ) | const |
"GET")
QByteArray HttpRequest::getParameter | ( | const QByteArray & | name | ) | const |
name | Name of the parameter |
QMultiMap<QByteArray,QByteArray> HttpRequest::getParameterMap | ( | ) | const |
QList<QByteArray> HttpRequest::getParameters | ( | const QByteArray & | name | ) | const |
name | Name of the parameter |
QByteArray HttpRequest::getPath | ( | ) | const |
"/index.html")
QHostAddress HttpRequest::getPeerAddress | ( | ) | const |
Note that multiple clients may have the same IP address, if they share an internet connection (which is very common).
const QByteArray& HttpRequest::getRawPath | ( | ) | const |
"/file%20with%20spaces.html")
RequestStatus HttpRequest::getStatus | ( | ) | const |
QTemporaryFile* HttpRequest::getUploadedFile | ( | const QByteArray | fieldName | ) | const |
The file is already open. It will be closed and deleted by the destructor of this HttpRequest object (after processing the request).
For uploaded files, the method getParameters() returns the original fileName as provided by the calling web browser.
QByteArray HttpRequest::getVersion | ( | ) | const |
"HTTP/1.1")
void HttpRequest::readFromSocket | ( | QTcpSocket * | socket | ) |
This method is called by the connection handler repeatedly until the status is RequestStatus::complete or RequestStatus::abort.
socket | Source of the data |
|
static |
E.g. replace "%23" by '#' and replace '+' by ' '.
source | The url encoded strings |
class HttpRequestHandler |
Web Applications usually have one central request handler that maps incoming requests to several controllers (servlets) based on the requested path.
You need to override the service() method or you will always get an HTTP error 501.
Public Member Functions | |
HttpRequestHandler (QObject *parent=Q_NULLPTR) | |
Constructor. More... | |
virtual | ~HttpRequestHandler () |
Destructor. | |
virtual void | service (HttpRequest &request, HttpResponse &response) |
Generate a response for an incoming HTTP request. More... | |
HttpRequestHandler::HttpRequestHandler | ( | QObject * | parent = Q_NULLPTR | ) |
parent | Parent object. |
|
virtual |
request | The received HTTP request |
response | Must be used to return the response |
Reimplemented in StaticFileController, RequestHandler, and APIController.
class HttpResponse |
response.setStatus(200,"OK"); // optional, because this is the default response.writeBody("Hello"); response.writeBody("World!",true);
Example how to return an error:
response.setStatus(500,"server error"); response.write("The request cannot be processed because the servers is broken",true);
In case of large responses (e.g. file downloads), a Content-Length header should be set before calling write(). Web Browsers use that information to display a progress bar.
Public Member Functions | |
HttpResponse (QTcpSocket *socket) | |
Constructor. More... | |
void | setHeader (QByteArray name, QByteArray value) |
Set a HTTP response header. More... | |
void | setHeader (QByteArray name, int value) |
Set a HTTP response header. More... | |
bool | hasHeader (const QByteArray name) const |
Returns wether this header has already been set. | |
QMap< QByteArray, QByteArray > & | getHeaders () |
Get the map of HTTP response headers. | |
QMap< QByteArray, HttpCookie > & | getCookies () |
Get the map of cookies. | |
void | setStatus (int statusCode, QByteArray description=QByteArray()) |
Set status code and description. More... | |
int | getStatusCode () const |
Return the status code. More... | |
void | write (QByteArray data, bool lastPart=false) |
Write body data to the socket. More... | |
bool | hasSentLastPart () const |
Indicates whether the body has been sent completely (write() has been called with lastPart=true). | |
void | setCookie (const HttpCookie &cookie) |
Set a cookie. More... | |
void | redirect (const QByteArray &url) |
Send a redirect response to the browser. More... | |
void | flush () |
Flush the output buffer (of the underlying socket). More... | |
bool | isConnected () const |
May be used to check whether the connection to the web client has been lost. More... | |
HttpResponse::HttpResponse | ( | QTcpSocket * | socket | ) |
socket | used to write the response |
void HttpResponse::flush | ( | ) |
You normally don't need to call this method because flush is automatically called after HttpRequestHandler::service() returns.
int HttpResponse::getStatusCode | ( | ) | const |
bool HttpResponse::isConnected | ( | ) | const |
This might be useful to cancel the generation of large or slow responses.
void HttpResponse::redirect | ( | const QByteArray & | url | ) |
Cannot be combined with write().
url | Destination URL |
void HttpResponse::setCookie | ( | const HttpCookie & | cookie | ) |
You must call this method before the first write().
void HttpResponse::setHeader | ( | QByteArray | name, |
QByteArray | value | ||
) |
You must call this method before the first write().
name | name of the header |
value | value of the header |
void HttpResponse::setHeader | ( | QByteArray | name, |
int | value | ||
) |
You must call this method before the first write().
name | name of the header |
value | value of the header |
void HttpResponse::setStatus | ( | int | statusCode, |
QByteArray | description = QByteArray() |
||
) |
The default is 200,OK. You must call this method before the first write().
void HttpResponse::write | ( | QByteArray | data, |
bool | lastPart = false |
||
) |
The HTTP status line, headers and cookies are sent automatically before the body.
If the response contains only a single chunk (indicated by lastPart=true), then a Content-Length header is automatically set.
Chunked mode is automatically selected if there is no Content-Length header and also no Connection:close header.
data | Data bytes of the body |
lastPart | Indicates that this is the last chunk of data and flushes the output buffer. |
struct StaticFileControllerSettings |
Data Fields | |
QString | path |
The path to the document root. More... | |
QString | encoding |
The assumed encoding of textual files (txt, html). More... | |
int | maxAge |
Maximum age of files in the browser cache (HTTP Cache-Control: max-age), in seconds. More... | |
int | cacheTime |
Maximum age of files in the serverside cache (in msec). More... | |
int | cacheSize |
Total serverside cache size in bytes. More... | |
int | maxCachedFileSize |
Maximum size of a single file in the serverside cache. More... | |
int StaticFileControllerSettings::cacheSize |
Default 1048576 (1MB)
int StaticFileControllerSettings::cacheTime |
Default 60000.
QString StaticFileControllerSettings::encoding |
Default UTF-8
int StaticFileControllerSettings::maxAge |
Default 60.
int StaticFileControllerSettings::maxCachedFileSize |
Default 65536 (64KB)
QString StaticFileControllerSettings::path |
Default empty (= current working directory).
class StaticFileController |
It is usually called by the applications main request handler when the caller requests a path that is mapped to static files.
The following settings are required in the config file:
path=../docroot encoding=UTF-8 maxAge=60000 cacheTime=60000 cacheSize=1000000 maxCachedFileSize=65536
The path is relative to the directory of the config file. In case of windows, if the settings are in the registry, the path is relative to the current working directory.
The encoding is sent to the web browser in case of text and html files.
The cache improves performance of small files when loaded from a network drive. Large files are not cached. Files are cached as long as possible, when cacheTime=0. The maxAge value (in msec!) controls the remote browsers cache.
Do not instantiate this class in each request, because this would make the file cache useless. Better create one instance during start-up and call it when the application received a related HTTP request.
Public Member Functions | |
StaticFileController (const StaticFileControllerSettings &settings, QObject *parent=Q_NULLPTR) | |
Constructor. | |
void | service (HttpRequest &request, HttpResponse &response) |
Generates the response. | |
QString | getDocRoot () const |
Public Member Functions inherited from HttpRequestHandler | |
HttpRequestHandler (QObject *parent=Q_NULLPTR) | |
Constructor. More... | |
virtual | ~HttpRequestHandler () |
Destructor. | |
Static Public Member Functions | |
static QByteArray | getContentType (QString fileName, QString encoding) |
Returns the content type of this file. More... | |
|
static |
This is currently only determined by file name.
class ITemplateTranslationProvider |
Public Member Functions | |
virtual QString | getTranslation (const QString &key)=0 |
Implement this method to provide a translated string for a given key. | |