Difference between revisions of "Custom Drivers Callback Methods API"
(→loop) |
(→loop) |
||
| (13 intermediate revisions by 3 users not shown) | |||
| Line 1: | Line 1: | ||
| + | [[Category:Advanced Programming]] | ||
A few callback methods are called by the HSYCO core engine during initialization, exit, and for normal operations. | A few callback methods are called by the HSYCO core engine during initialization, exit, and for normal operations. | ||
| Line 72: | Line 73: | ||
'''Returns:''' | '''Returns:''' | ||
| − | * boolean - true if the initialization process is successful (HSYCO will | + | * boolean - true if the initialization process is successful (HSYCO will start calling the loop() callback); false to fail the initialization procedure (HSYCO will retry the initialization process later, calling init() again). |
=== loop === | === loop === | ||
| Line 83: | Line 84: | ||
This call should always return within about 30 seconds, to avoid the keep-alive watch-dog intervention. | This call should always return within about 30 seconds, to avoid the keep-alive watch-dog intervention. | ||
| + | |||
| + | |||
| + | {{note|HSYCO will consider the driver properly started only when loop() returns true at least once after init(). | ||
| + | |||
| + | If loop() keeps returning false after init(), HSYCO will not consider the driver as started, and will keep calling loop() until it returns true. | ||
| + | |||
| + | The keep-alive watch-dog is not activated until loop() returns true once.}} | ||
'''Returns:''' | '''Returns:''' | ||
| − | * boolean - | + | * boolean - return true if the loop processing is successful, false on errors. |
=== end === | === end === | ||
| Line 96: | Line 104: | ||
Should always return true. | Should always return true. | ||
| + | |||
| + | |||
| + | '''Returns:''' | ||
| + | |||
| + | * boolean - always return true. | ||
=== user === | === user === | ||
| − | String user(String session, String | + | String user(String session, String userid, String id, HashMap<String, String> fields) |
| − | Called on user keys, gui input objects, submit and | + | Called on user keys, gui input objects, submit and USER actions in Events or Java, when the user interface object identifier has a prefix that matches the driver's identifier followed by a "." character. |
{{tip|This method is optional, and doesn't need to be implemented if not required.}} | {{tip|This method is optional, and doesn't need to be implemented if not required.}} | ||
| + | |||
| + | This method returns a string. Any returned string causes the log of an [OK] status. If you want to prevent logging, for example to avoid sensitive information to be written in the log file, you should return the string “!”. | ||
| + | |||
| + | If you want to force the Web interface to show a specific page after the button is pressed (it would be like pressing a (link) object), return a string starting with “page:” followed by the page name; in this case, userCommand() will be called again when that popup or page is closed, with "/close" appended to param. | ||
| + | |||
| + | |||
| + | '''Parameters:''' | ||
| + | |||
| + | * session: string - a session id string that uniquely identifies the client session | ||
| + | * userid: string - the user id | ||
| + | * id: String - see the table below | ||
| + | * fields: HashMap<String, String> - see the table below. | ||
| + | |||
| + | |||
| + | {| class="wikitable" | ||
| + | | width=200 | '''Type of input''' | ||
| + | | width=250 | '''id''' | ||
| + | | width=250 | '''fields''' | ||
| + | |- | ||
| + | | single (user) type object | ||
| + | | <name>.<params> attributes of the (user) object. <name> is stripped of the driver's identifier prefix | ||
| + | | null | ||
| + | |- | ||
| + | | single (input) type object | ||
| + | | <id>.<value> where <id> is the (input) object identifier, without the driver's identifier prefix, and value is the (input) field value | ||
| + | | null | ||
| + | |- | ||
| + | | multiple (input) type objects in (container) with (submit) | ||
| + | | the ideintifier of the (submit) object, without the driver's identifier prefix | ||
| + | | the identifiers of all objects in the container, and their values | ||
| + | |} | ||
| + | |||
| + | |||
| + | '''Returns:''' | ||
| + | |||
| + | * String - log or go to page, see text above. If this function returns null, an [ERROR] status is logged in the log file, while any other string causes the log of an [OK] status. | ||
=== command === | === command === | ||
| Line 112: | Line 161: | ||
{{tip|This method is optional, and doesn't need to be implemented if not required.}} | {{tip|This method is optional, and doesn't need to be implemented if not required.}} | ||
| + | |||
| + | |||
| + | '''Parameters:''' | ||
| + | |||
| + | * name: String - the I/O data point name, stripped of the driver's identifier prefix | ||
| + | * value: String - the data point value. | ||
Latest revision as of 11:52, 6 November 2014
A few callback methods are called by the HSYCO core engine during initialization, exit, and for normal operations.
You should write your custom interface code inside these methods, and also set the default values of some static properties.
Contents
Static Properties
DEFAULTSOCKETPORT
DEFAULTSOCKETPORT
Used to set the default IP socket port, to be used when the port field is not set in the configuration. For example, if your driver is interfacing an HTTP-based service, you may want to set DEFAULTSOCKETPORT to 80.
COMMANDSQUEUESIZE
COMMANDSQUEUESIZE
Defines the size of the command queue.
The command queue is used to accumulate commands that the driver should execute, and are generated by ioSet() JavaScript or Java calls, the IOSET event or users pressing (button) objects in the Web user interface.
The command queue should be large enough to let the driver have time to consume incoming commands and not lose any. At the same time a queue that is too large could let a large number of messages to accumulate in case the driver has temporary issues talking to the external system.
HSYCO's built-in drivers usually have queue sizes between 64 and 1024. 256 is normally a good value.
SHUTDOWNWHENSLAVE
SHUTDOWNWHENSLAVE
This is the default value of the "shutdown when inactive" configuration parameter. If true and the "shutdown when inactive" is not defined, the driver will be automatically shut down when the HSYCO server is in a high availability configuration and the server is not the active server.
Callback Methods
init
boolean init(String name, HashMap<String, String> config)
Called once every time the driver is started.
Returning false will fail the initialization procedure, and the driver will not start.
Parameters:
- name: String - this driver's identifier
- config: HashMap<String, String> - a hash table of all basic configuration parameters, see the table below, and all options.
| Parameter | Description |
| comm | communication port identifier |
| host | the host IP name address |
| port | the IP port |
| user | user name |
| password | password |
| shutdowninactive | the shutdown when inactive parameter |
Returns:
- boolean - true if the initialization process is successful (HSYCO will start calling the loop() callback); false to fail the initialization procedure (HSYCO will retry the initialization process later, calling init() again).
loop
boolean loop()
Called repeatedly while the driver should be alive.
Returning false will not update the keep-alive timer, causing the driver to quit after a while.
This call should always return within about 30 seconds, to avoid the keep-alive watch-dog intervention.
If loop() keeps returning false after init(), HSYCO will not consider the driver as started, and will keep calling loop() until it returns true.
The keep-alive watch-dog is not activated until loop() returns true once.
Returns:
- boolean - return true if the loop processing is successful, false on errors.
end
boolean end()
Called once when the driver quits after it has started correctly.
Should always return true.
Returns:
- boolean - always return true.
user
String user(String session, String userid, String id, HashMap<String, String> fields)
Called on user keys, gui input objects, submit and USER actions in Events or Java, when the user interface object identifier has a prefix that matches the driver's identifier followed by a "." character.
This method is optional, and doesn't need to be implemented if not required.
This method returns a string. Any returned string causes the log of an [OK] status. If you want to prevent logging, for example to avoid sensitive information to be written in the log file, you should return the string “!”.
If you want to force the Web interface to show a specific page after the button is pressed (it would be like pressing a (link) object), return a string starting with “page:” followed by the page name; in this case, userCommand() will be called again when that popup or page is closed, with "/close" appended to param.
Parameters:
- session: string - a session id string that uniquely identifies the client session
- userid: string - the user id
- id: String - see the table below
- fields: HashMap<String, String> - see the table below.
| Type of input | id | fields |
| single (user) type object | <name>.<params> attributes of the (user) object. <name> is stripped of the driver's identifier prefix | null |
| single (input) type object | <id>.<value> where <id> is the (input) object identifier, without the driver's identifier prefix, and value is the (input) field value | null |
| multiple (input) type objects in (container) with (submit) | the ideintifier of the (submit) object, without the driver's identifier prefix | the identifiers of all objects in the container, and their values |
Returns:
- String - log or go to page, see text above. If this function returns null, an [ERROR] status is logged in the log file, while any other string causes the log of an [OK] status.
command
void command(String name, String value)
Called for each command that should be processed by the driver.
This method is optional, and doesn't need to be implemented if not required.
Parameters:
- name: String - the I/O data point name, stripped of the driver's identifier prefix
- value: String - the data point value.
