httpConnect()

Synopsis

int httpConnect(string|function_ptr callBackFunc, string resourceName [, string contentType = "text/html"]);

Parameter

Return value

httpConnect() returns 0 on success, otherwise -1.

Error

Errors can be queried with getLastError(). Errors can be:

• Too few arguments
• No httpServer() is installed
• httpConnect() is called from a different script than the httpServer() was installed from
• The given callback-function does not exist
• The given resourceName is already registered

Description

The function httpConnect() registers a CTRL-function as a callback-function under the given Web-Resource name in the httpServer.

The URL can also be registered with a pattern. A requested URL will be compared against an exact match of the registered URL and if no exact match was found an additional check with patternMatch() will be done.

The CTRL-function is executed when the resourceName is requested. A given Web-Resource can only call one CTRL-function, that means a second call to httpConnect() with the same Web-Resource name with lead to an error, and -1 is returned.

The callback-function must return a string, which will then be sent to the client. The content of this string must be of the type, which was given at the registration with httpConnect(). Default is: text/html.

The given callback-function must have the following definition:

string|dyn_string workCB([
      
dyn_string

names [,
      
dyn_string

values [,
      
string

user [,
      
string

ip [, dyn_string headerNames [, dyn_string headerValues [, int connectionIndex]]]]]]])

The name of the work-function is arbitrary.

The arguments names and values contain the list of variable-names and the corresponding values, which are extracted from the query-part of a given URL. The IP address is according to the common DOT notation. The user is the authorized, or "", if no authorization is desired.

If a client sends the following request

www.x.y/example?firstVar=value1&secondVar=value2

then the registered CTRL-function will have 2 elements in the dyn_string names argument, whereby the 1. is "firstVar" and the 2. is "secondVar", and 2 elements in the dyn_string values, whereby the 1. is "value1" and the 2. is "value2".

• There are 2 further optional parameters for CTRL callback functions. The parameters are used to pass all HTTP Headers (headerNames) and values (headerValues) to the function.
• The CTRL callback function may return a dyn_string, a blob, a file or a dyn_mixed instead of a string, for a dyn_string the first entry is the content (for example, HTML page). All further elements are passed as HTTP header of the response message to the client. The system checks, whether an HTTP header contains a ":" , otherwise the entry is discarded (an error message is shown). In case of a dyn_mixed the first field has to be of typestring, blob or file (content). All other fields have to be of type string (header). Status is the first row, for example, "Status: 404 Not found" Internally the prefix "HTTP/1.1" is added and replaces the mandatory "Status: " element. This results in the return value "HTTP/1.1 404 Not found" which is returned by the server.

Example

Return value if a page could be displayed successfully:

return makeDynString(content, "Status: 200 OK");

The server returns following header to the client: "HTTP/1.1 200 OK"

Example

Return value if the page could not be found.

return makeDynString("", "Status: 404 Not found");

The server returns following header to the client: "HTTP/1.1 404 Not found"

Example

Return value if the position of the page was changed:

return makeDynString("", "Status: 301 Moved Permanently", "Location: /download");

The server returns following header lines to the client: Line 1: "HTTP/1.1 301 Moved Permanently", Line 2: "Location: /download"

• The CTRL callback function may also return an empty string as a content. Thereby, the system sends the message "No content" to the client. Thus, the client does not build a new page and the current page remains.
• No result of a callback function is cached, this means a refresh of a dynamic page creates the page new.

• The POST method is possible.

  If a client sends data in the content type "application/x-www-form-urlencoded" to the HTTP server, the CTRL callback functions get field names and field values in the same form as the GET method (in the GET method the field names and values are coded in the query of the URI) that means in the first two dyn_string parameters.

  If a content type of the main group "text/" is used, the content of the callback is passed as a string, according to the following syntax:

string workCB([string content [, string user [, string ip [, dyn_string headerNames [, dyn_string headerValues [, int connectionIndex]]]]]]])

When using other content types, the content of the CTRL callback function has to be a blob, according to the following syntax:

string workCB([blob content [, string user [, string ip [, dyn_string headerNames [, dyn_string headerValues [, int connectionIndex]]]]]])

The POST method limits the content length to 100 KByte and can be increased with the function httpSetMaxContentLength().

The content types, which are recognized by the server by their extension, can be extended configurable. (The existing types remain as hard coded defaults). The HTTP server loads all files with the name "contentTypes.txt" in the config directory in the project hierarchy. This file contains - separated by white spaces (tabs, blanks) - two entries per line: contentType FileExtension, for example, text/richtext rtf. In this case the server would send a file with the extension ".rtf" with the contentType "text/richtext". The check of the extension is case insensitive. Lines starting with "#" are ignored (comments).

The communication between a server and a client can block the system. Make sure that the HTTP server is started in its own CTRL manager to guarantee the correct functionality of all functions and of the WinCC OA system.

Example

The CTRL function example() is called if a client requests the resource "/firstExample". Enter http://localhost/firstExample to your browser and the resource firstExample "This is my first HTML example" is shown.

Note that if you call the functions via the UI, you have to include the "CtrlHTTP" dll to your code: #uses "CtrlHTTP".

main()
{
  httpServer();
/* installs the HTTP Server */
  httpConnect("example", "/firstExample");
}
string example()
{
  return "<html><head><title>Erstes Beispiel</title></head>"
  "<body>Das ist mein erstes HTML-Beispiel</body></html>";
}

Example

Enter http://localhost/t1 to your browser. In this example the return value is a dyn_string. The text: "This is a Test. X-User_defined_header: this is a test header" is shown.

main()
{
  httpConnect("t1", "/t1");
}
dyn_string t1()
{
  dyn_string result;
  result[1] = "<html><title>TEST</title><body>This is a Test</body></html>";
  result[2] = "X-User_defined_header: this is a test header";
  return result;
}

Example

E nter http://localhost/Example to your browser. In this example the return value is a dyn_mixed. The text: "This is a Test. Status: 404 Not found is shown.

#uses "CtrlHTTP"
main()
{
  int i;
  i = httpServer();
/* installs the HTTP Server */
  string t = "text/plain";
/* Content Type */
  httpConnect("example", "/Example", t);
  DebugN("HTTP Server installed",i,"Format",t);

/* check if the function httpServer was executed correctly */
  dyn_errClass err;
  err = getLastError();
/* check possible errors */
  if(dynlen(err) > 0)
  {
    errorDialog(err);
    throwError(err);
  }
  else
  {
    DebugN("OK");
//No errors
  }
}
dyn_mixed example()
{
  dyn_mixed n;
  dynAppend(n,"This is a test");
//first field
  dynAppend (n, "Status: 404 Not found");
//header
  return n;
}

Enter http://localhost/Example to your browser. In this example the return value is a string (content of a file). The file C:/TEXT.TXT has to exist.

#uses "CtrlHTTP"
main()
{
  int i;
  dyn_errClass err;
  i = httpServer();
/*  Installs the HTTP Server */
  string t = "text/plain";
  httpConnect("example", "/Example", t);
  err = getLastError();
  DebugN("HTTP server installed",i,"Format",t);
  if(dynlen(err) > 0)
  {
    errorDialog(err);
    throwError(err);
  }
  else
  {
    DebugN("OK");
/* No error */
  }
}
string example()
{
  string res;
  fileToString("/tmp/myFile", res);
  return res;
}

Example

Use of httpConnect with the new HttpServer class in a modified webclient_http.ctl.

#uses "classes/HttpServer"

class MyHttpServer : HttpServer
{
  public start()
  {
    HttpServer::start();

    httpConnect(callback, "/test2");  // connect to a class-static function
  }

  static string callback()
  {
    return "TEST2";
  }
};

MyHttpServer http;

main()
{
  http.setHttpPort(8084);
  http.setHttpsPort(8085);
  http.start();

  httpConnect("work", "/test");  // connect to a global function
}

string work()
{
  return "this is a test";
}

Assignment

CTRL PlugIn

Availability

CTRL