httpServer()

Installs and activates an HTTP server.

Synopsis

int httpServer([ bool authRequired = true | string authMethod | dyn_string authMethods[, unsigned portNr = 80 [, unsigned SecurePortNr = 443]]]);

Parameter

Parameter Description
authRequired / authMethod / authMethods

Optional / Note: Only one of the parameters can be used.

authRequired

Defines whether the HTTP server requires authentication. TRUE ... authentication necessary, FALSE ... no authentication necessary. Default: TRUE

Note : If an authentication is required, an authentication token always is sent back by the server, independent of the HTTP status code (e.g. "200 OK").
authMethod / authMethods

Defines the used mode. Possible values are:

"Basic" | "Basic realm = myRealm" - The realm is arbitrary (a web browser remembers a password per realm and host)

"Negotiate" (Windows)

"NTLM" (Windows)
portNr

Optional.

Defines the port number, on which the HTTP server waits for on incoming queries. Default port: 80

If 0 is specified, no HTTP port will be opened and only HTTPS ports are accessible.
SecurePortNr

Optional.

Defines the communication via HTTPS. If you do not want to use the HTTPS communication, set the parameter to 0. Default port: 443. If another port number should be used, define the port number.

For the use of HTTPS it is necessary to specify both port numbers (portNr and SecurePortNr).

Return value

0 on success, otherwise -1.

Error

Errors are dependent on the operating system. A common error is, that the port number is already used by another HTTP server on the same system.

Description

To use the (default) port 80 (or 443 for HTTPS) under Linux, the CTRL Manager (HTTP Server) has to be started as root (other users must not open a port <= 1024).

The function httpServer() starts an HTTP server module, which then listens to client requests. Only one HTTP server per manager is allowed .

With the HTTP-Server you can either register CTRL Callback functions under a specific web-resource name (see httpConnect()) or you can transfer static HTML or other files to the client.

Static files have to be located under

"/pictures/"

"/images/"

"/colorDB/"

"/xml/"

"/nls/"

"/bin/"

"/data/"

"/log/"

but never under "/config/".

Files can be downloaded from the panels and scripts/ directories but the files are encrypted due to the security requirements.

"/panels/" and

"/scripts/"

  • It is possible to use and address subdirectories as needed.

  • The files are searched in all defined project directories (hierarchical search).

  • If the root-resource "/" is not registered extra via httpConnect(), the HTTP-Server searches the file <proj_path>/data/index.html in case of requests.

  • The HTTP server implements only methods POST, HEAD, GET and CONNECT.

If you want to use a secure HTTP communication (= HTTPS) under Windows, define a secure port number for the communication by using the last parameter of the function.

For the use of HTTPS (and thus also the httpsPort config entry) under Windows the installation of openSSL is required. See HTTPS_(SSL_connections).

The HTTP Server will obey different behavior of HTTP/1.0 and HTTP/1.1 clients with respect to connection management: A 1.0 client expects a connection being closed unless it stated otherwise, a 1.1 client expects a connection being kept open unless stated otherwise.

Debugging

By using the debug-flag -dbg HTTP the data transfer of the HTTP-Server can be monitored.

Content Types

The following Content-Types are known by the HTTP-Server:

Filetype Filename extension Content type
GIF image file .gif image/gif
X11 Bitmap .xbm image/x-xbitmap
JPG image file .jpg or .jpeg image/jpeg
PNG image file .png image/png
BMP image file .bmp image/bmp
SVG image file .svg image/svg+xml
X PixMap .xpm image/x-xpm
HTML file .htm or .html text/html
JavaScript File .js text/javascript
Text File .txt text/plain
Cascading Style Sheet .css text/css
WML file .wml text/vnd.wap.wml
compiled WML .wmlc application/vnd.wap.wmlc
Java Network Launching Protocol .jnlp application/x-java-jnlp-fil
Java Archive .jar application/x-java-archive
PDF file .pdf application/pdf
WML Script .wmlscript or .wsc text/vnd.wap.wmlscript
Wireless Bitmap .wbmp image/vnd.wap.wbmp
unknown none or unknown application/octet-stream

Example 1

The CTRL-function example() should be called when a client requests the resource "/firstExample"

main()
{
  httpServer(); // installs the HTTP server
  httpConnect("example", "/firstExample");
}
string example()
{
  return "<html><head><title>First
  Example</title></head>"
  "<body>This is my first HTML
  example</body></html>";
}

Example 2

The user "Smith" has been created in a WinCC OAproject. The HTTP server as service will be started with "Negotiate". The following script will be started in PMON by a CTRL manager:

#uses "CtrlHTTP"
main()
{
  httpServer("Negotiate");
  httpConnect("work", "/");
}
void work(dyn_string names, dyn_string values, string user)
{
  return "<html>Your name is: " + user + "</html>";
}

After accessing http://localhost by using a browser you can see (with entered debug flag -dbg HTTP ) that a "Negotiate" HTTP traffic is executed. The web side can be accesses automatically and the following result is displayed:

"Your name is: Smith"

Assignment

CTRL PlugIn

Availability

CTRL