httpConnect()

Registers a CTRL function as a Web resource

Synopsis

int httpConnect(string work, string resourceName [, string contentType]);

Parameter

Parameter	Description
work	Work function, which is called when the given web-resource is requested.
resourceName	The URL name, which calls the given CTRL function when requested.
contentType	optional definition of the type of the result, which is generated by the given CTRL function and sent to the client. Default: text/html

Return value

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

Errors

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 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 ]]]]]])

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 a 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 type string, 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" ==> "HTTP/1.1 404 Not found" .

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]]]]])

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]]]]])

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

Note

The communication between a server and a client can block the system. Make sure that the HTTP server is started in an 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.

CAUTION

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>First Example</title></head>"

"<body>This is my first HTML example</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

Enter 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;

i = httpServer(); /* Installs the HTTP Server */

string t = "text/plain";

httpConnect("example", "/Example", t);

DebugN("HTTP server installed",i,"Format",t);

dyn_errClass err;

err = getLastError();

if(dynlen(err) > 0)

{

errorDialog(err);

throwError(err);

}

else

{

DebugN("OK"); /* No error */

}

string example()
{
  string res;
  fileToString("/tmp/myFile", res);
  return res;
}

Member of

CTRL PlugIn

Availability

CTRL