Stellarium  0.17.0
Data Structures | Typedefs | Functions
QtWebApp library

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.
 

Detailed Description

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:

Author
Stefan Frings, Florian Schaukowitsch

Data Structure Documentation

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...
 

Field Documentation

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.

See also
HttpRequest for description of config settings maxRequestSize and maxMultiPartSize.

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.
 

Constructor & Destructor Documentation

HttpConnectionHandler::HttpConnectionHandler ( const HttpConnectionHandlerSettings settings,
HttpRequestHandler requestHandler,
HttpSslConfiguration sslConfiguration = Q_NULLPTR 
)
Parameters
settingsConfiguration settings of the HTTP webserver
requestHandlerHandler that will process each incoming HTTP request
sslConfigurationSSL (HTTPS) will be used if not Q_NULLPTR

Member Function Documentation

void HttpConnectionHandler::handleConnection ( tSocketDescriptor  socketDescriptor)
slot
Parameters
socketDescriptorreferences 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...
 

Field Documentation

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.

See also
HttpConnectionHandler for description of the readTimeout
HttpRequest for description of config settings maxRequestSize and maxMultiPartSize

Public Member Functions

 HttpConnectionHandlerPool (const HttpConnectionHandlerPoolSettings &settings, HttpRequestHandler *requestHandler)
 Constructor. More...
 
virtual ~HttpConnectionHandlerPool ()
 Destructor.
 
HttpConnectionHandlergetConnectionHandler ()
 Get a free connection handler, or 0 if not available. More...
 

Constructor & Destructor Documentation

HttpConnectionHandlerPool::HttpConnectionHandlerPool ( const HttpConnectionHandlerPoolSettings settings,
HttpRequestHandler requestHandler 
)
Parameters
settingsConfiguration settings for the HTTP server. Must not be 0.
requestHandlerThe handler that will process each received HTTP request.
Warning
The requestMapper gets deleted by the destructor of this pool

Member Function Documentation

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...
 

Constructor & Destructor Documentation

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 
)
Parameters
namename of the cookie
valuevalue of the cookie
maxAgemaximum age of the cookie in seconds. 0=discard immediately
pathPath for that the cookie will be sent, default="/" which means the whole domain
commentOptional comment, may be displayed by the web browser somewhere
domainOptional domain for that the cookie will be sent. Defaults to the current domain
secureIf true, the cookie will only be sent on secure connections
HttpCookie::HttpCookie ( const QByteArray  source)
Parameters
sourceString as received in a HTTP Cookie2 header.

Member Function Documentation

int HttpCookie::getMaxAge ( ) const
void HttpCookie::setMaxAge ( const int  maxAge)

0=discard immediately

static QList<QByteArray> HttpCookie::splitCSV ( const QByteArray  source)
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...
 

Field Documentation

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.

See also
HttpConnectionHandlerPool for description of config settings minThreads, maxThreads, cleanupInterval and ssl settings
HttpConnectionHandler for description of the readTimeout
HttpRequest for description of config settings maxRequestSize and maxMultiPartSize

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.
 

Constructor & Destructor Documentation

HttpListener::HttpListener ( const HttpListenerSettings settings,
HttpRequestHandler requestHandler,
QObject *  parent = Q_NULLPTR 
)

Creates a connection pool and starts listening on the configured host and port.

Parameters
settingsConfiguration settings for the HTTP server. Must not be 0.
requestHandlerProcesses each received HTTP request, usually by dispatching to controller classes.
parentParent object.
Warning
Ensure to close or delete the listener before deleting the request handler.

Member Function Documentation

void HttpListener::handleConnection ( tSocketDescriptor  socketDescriptor)
signal
Parameters
socketDescriptorreferences 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
 

Constructor & Destructor Documentation

HttpRequest::HttpRequest ( const int  maxRequestSize,
const int  maxMultiPartSize 
)
Parameters
settingsConfiguration settings

Member Function Documentation

QByteArray HttpRequest::getBody ( ) const
QByteArray HttpRequest::getCookie ( const QByteArray &  name) const
Parameters
nameName of the cookie
QMap<QByteArray,QByteArray>& HttpRequest::getCookieMap ( )
QByteArray HttpRequest::getHeader ( const QByteArray &  name) const
Parameters
nameName of the header
Returns
If the header occurs multiple times, only the last one is returned.
QList<QByteArray> HttpRequest::getHeaders ( const QByteArray &  name) const
Parameters
nameName of the header
QByteArray HttpRequest::getMethod ( ) const

"GET")

QByteArray HttpRequest::getParameter ( const QByteArray &  name) const
Parameters
nameName of the parameter
Returns
If the parameter occurs multiple times, only the last one is returned.
QMultiMap<QByteArray,QByteArray> HttpRequest::getParameterMap ( ) const
QList<QByteArray> HttpRequest::getParameters ( const QByteArray &  name) const
Parameters
nameName 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
See also
RequestStatus
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.

Parameters
socketSource of the data
static QByteArray HttpRequest::urlDecode ( const QByteArray  source)
static

E.g. replace "%23" by '#' and replace '+' by ' '.

Parameters
sourceThe url encoded strings
See also
QUrl::toPercentEncoding for the reverse direction
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.

Warning
Be aware that the main request handler instance must be created on the heap and that it is used by multiple threads simultaneously.
See also
StaticFileController which delivers static local files.

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...
 

Constructor & Destructor Documentation

HttpRequestHandler::HttpRequestHandler ( QObject *  parent = Q_NULLPTR)
Parameters
parentParent object.

Member Function Documentation

virtual void HttpRequestHandler::service ( HttpRequest request,
HttpResponse response 
)
virtual
Parameters
requestThe received HTTP request
responseMust be used to return the response
Warning
This method must be thread safe

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...
 

Constructor & Destructor Documentation

HttpResponse::HttpResponse ( QTcpSocket *  socket)
Parameters
socketused to write the response

Member Function Documentation

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().

Parameters
urlDestination 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().

Parameters
namename of the header
valuevalue of the header
void HttpResponse::setHeader ( QByteArray  name,
int  value 
)

You must call this method before the first write().

Parameters
namename of the header
valuevalue 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.

Parameters
dataData bytes of the body
lastPartIndicates 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...
 

Field Documentation

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...
 

Member Function Documentation

static QByteArray StaticFileController::getContentType ( QString  fileName,
QString  encoding 
)
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.