Data exchange protocol

From ISPWiki

Jump to: navigation, search

Receiving data

Script handlers use two formats to receive data:

  • cgi - data is transferred in the same manner as CGI-scripts and you can use libraries for CGI available for all programming languages. This means is not flexible, but simple and can be used by most handlers.
  • xml - data in the form of XML is transferred to STDIN. This data contains user interface description, text messages and values that this user enters (in the form of tags, which names match a parameter name).

Environment variables also include some data you may need.

Data output

Regardless the type that was used to receive data, a script handler should output a valid XML document. If cgi is used, an output document will merge one formed by the control panel; if xml is used, it will fully replace the data formed earlier. If output data has invalid format, the control panel will display a plug-in error message that may cause malfunctioning of main functions.

There are several types of the output data:

  • Error message, for example
<?xml version="1.0" encoding="UTF-8"?>
<doc>
  <error code="1">Oops!</error>
</doc>

Please, read the article Error codes for more detail. When receiving this tag the control panel will display an error message regardless other data in the output document.


  • Redirect, for example
<?xml version="1.0" encoding="UTF-8"?>
<doc>
<redirect>location='ispmgr?func=usrparam'</redirect>
</doc>

The content of the redirect tag will be sent to client in the form of javascript. It is used when creating a setup wizard, a step-by-step instruction with several consequent forms. In our case this data will open a user property form. All other data in the xml document will be ignored.

  • Successful operation message, for example
<?xml version="1.0" encoding="UTF-8"?>
<doc>
<ok>top</ok>
</doc>

Such a document is usually formed when performing an operation that does not return data, but informs results and requires additional actions. The ok tag may have the following values:

    • top - once the operation is complete, the browser will read the whole user interface, rather than its forms; it can be used, if your function can affect the menu elements, language and other global parameters.
    • restart - once the function is complete, the browser will block the interface by showing an in-progress operation; the restart function will be called to restart the web-server. When the server is up and running again, the interface will be unblocked.

An empty tag means that no action are required.

  • Data table, for example
<?xml version="1.0" encoding="UTF-8"?>
<doc>
 <elem>
  <id>10</id>
  <name>Element1</name>
 </elem>
 <elem>
  <id>12</id>
  <name>Element2</name>
 </elem>
</doc>

The elem tag describes a data field and can include several tags that contain data. The names of these tag should correspond to column names from the interface description. The column description is not required for all the data. Data without columns can be used either as a key field (the key attribute if the metadata tag when describing the table interface), or for API calls.

  • Form data, for example
<?xml version="1.0" encoding="UTF-8"?>
<doc>
  <id>10</id>
  <name>Element1</name>
</doc>

Practically, this document can have tags with random names (except for special error, redirect, etc.), tag names will correspond to form fields.

Was this helpful? Yes | No
Views
Personal tools