Skip to main content
Version: 4.2 (beta)

Java Callback Methods API

Callback methods are called by the HSYCO events management system.

By implementing these methods, you can associate your custom Java code to each event.

In some cases, the return values of these methods can influence the behavior of HSYCO.

Most of the methods, propagate exceptions to the top, that is to HSYCO internal code. In this case, HSYCO generates an error message in the log.

System Functions​

DaylightEvent​

static void DaylightEvent(boolean day)

Called at sunrise and sunset, according to the latitude and longitude values set in hsyco.ini, and the optional SunriseOffsetMinutes and SunsetOffsetMinutes parameters.

Parameters:

  • day: boolean - true at sunrise, false at sunset.

getUserVersion​

static String getUserVersion()

This method returns a string, used by the HSYCO run-time to generate the plugins version information log line at startup.

It is recommended to return a meaningful string with an appropriate identification of your plugin and its version.

Returns:

  • String - plugin version information.

haActiveEvent​

static void haActiveEvent(boolean active)

Triggered by the change of state of an HSYCO server in a master/slave high availability configuration.

Parameters:

  • active: boolean - true if the server is active, false if not active.

PowerEvent​

static int PowerEvent(int power)

Triggered by a change of the current power load level, as set using the powerSet() Java API or the POWER action.

Thanks to this method, you are allowed to alter the power value shown in the Web interface, for example to aggregate power readings acquired from other sensors.

Parameters:

  • power: int - the power level, in Watts.

Returns:

  • int - if PowerEvent() returns -1 or doesn't return a value, HSYCO status is updated with the detected power value, the value returned by PowerEvent() is otherwise used.

programTimerEvent​

static void programTimerEvent(String name)

Called when a program timer is activated.

Program timers are set using programTimerSet(), programTimerReset(), programTimerRepeat(), or using the corresponding actions in EVENTS. The name of the timer is in uppercase.

Parameters:

  • name: String - uppercase program timer name.

SchedulerEvent​

static void SchedulerEvent(String groupname, String schedulename)

This callback blocking method allows to call user methods at configurable intervals.

Schedules are defined using a group name and a schedule name.

Schedules under the same group run in the same thread and are executed sequentially, based on their interval in milliseconds. Schedules in different groups run in parallel.

Parameters:

  • groupname: String - the scheduler’s group name
  • schedulename: String - the scheduler’s name.

StartupEvent​

static void StartupEvent()

Called only once when HSYCO starts, after the initialization and HTTP server start-up, but before the execution of the different field interface threads. It is not executed in a thread, it is therefore a blocking method, that must complete its execution before all other HSYCO services can be started.

SunPositionEvent​

static void SunPositionEvent(int azimuth, int elevation)

Called when the Sun changes its height with respect to the horizon or its angle from true north.

Parameters:

  • azimuth: int - the current Sun angle from true north, in decimal degrees
  • elevation: int - the current Sun elevation in decimal degrees from the horizon. Elevation is negative at night.

TimeEvent​

static void TimeEvent(long time)

Called every 60 seconds.

HSYCO tries to synchronize the execution at the beginning of the minute, executing this method at seconds 0 of every minute.

note

However, the execution is not guaranteed. In case of heavy load HSYCO might not be able to execute the call with accurate timing. In extreme cases, it could occasionally skip some calls.

Parameters:

  • time: long - the current time in milliseconds.

varEvent​

static void varEvent(String name, String value)

Triggered by the change of value of a program variable.

Parameters:

  • name: String - the variable name, uppercase.
  • value: String - the value to be assigned to the program variable.

Cameras​

CameraCommandEvent​

static int cameraCommandEvent(String function, String action, String camera)

Triggered by a camera control input from the Web interface.

It can be used to execute arbitrary actions when the user clicks on the active areas of the camera view, or to replace some or all of the standard PTZ commands with custom actions.

Parameters:

  • function: String - see the table below
  • action: String - see the table below
  • camera: String - the camera name.

Returns:

  • int - if CameraCommandEvent() returns -1 or doesn't return a value, the standard PTZ command associated to the PTZ driver is skipped, otherwise it is executed normally.
IconFunctionAction
CAMERACOMMAND camera over fffocusfar
CAMERACOMMAND camera over fnfocusnear
CAMERACOMMAND camera over zinzoomtele
CAMERACOMMAND camera over zoutzoomwide
CAMERACOMMAND camera over lmoveleft
CAMERACOMMAND camera over rmoveright
CAMERACOMMAND camera over umoveup
CAMERACOMMAND camera over dmovedown
movestop

CameraMotionEvent​

static void CameraMotionEvent(String eventName, long remoteTime)

Called when HSYCO starts recording video from a camera.

Recording starts when a camera notifies a recording request with the recording HTTP API call (the zone=id portion is optional):

http://192.168.0.50/x/camerarec?camera=name&zone=id

Recording can also be triggered by the CameraRecTrigger() Java method or JavaScript function, or the CAMERAREC or CAMERARECFULL actions in EVENTS.

Parameters:

  • eventName: String - the event identification string, either the camera name only or name:id if recording is triggered by a camerarec HTTP call with the optional zone=id parameter
  • remoteTime: long - the current time in milliseconds.

CameraViewEvent​

static void CameraViewEvent(String camera, boolean active)

CameraViewEvent() is called on changes of the live view status of cameras.

When at least one web client is showing the live feed from a camera, the camera is marked as active.

When no live feed request is received for a several consecutive seconds, the camera is marked as not active.

Parameters:

  • camera: String - the camera name
  • active: boolean - true if active, false if not.

Datasources​

See Data Sources for an overview of data sources, and how to implement custom data sources with these callbacks.

dataSourceQuery​

JSONObject dataSourceQuery(String session, String userid, String datasourceid, String[] columns)

Called when datasource data is requested.

Supports direct callback by @dataSourceQuery annotations. See Annotations examples.

Parameters:

  • session: String - session id string that uniquely identifies the client session.
  • userid: String - the user id.
  • dataSourceId: String - the identifier of the datasource from which data is requested.
  • columns: String[] - an array of column identifiers specifying the fields requested by the client. Contains "*" if all columns are requested.

Returns:

  • JSONObject - either the requested data or error information.

Success Response Structure:

  • columns: JSONObject[] - an array of objects describing each column’s metadata:
    • name: String - the column name. It has to be unique within the datasource.
    • type: String - the column data type, which can be varchar, integer, decimal, boolean, date, time or timestamp.
    • key: boolean - indicates whether the column is a primary key. Optional, default is false. 0/1 values are also accepted.
    • size: int - the column size, in bytes. Optional.
    • nullable: (0|1) - indicates whether the column can contain null values. Optional, default is 0 (false).
    • readonly: (0|1) - indicates whether the column is read-only. Optional, default is 0 (false).
  • rows: JSONArray - rows, where each row is an array of values corresponding to the specified columns. If "*" is received in the columns parameter, all available columns should be included in the response.

Error Response Structure:

  • error: a JSON object returned when the query fails:
    • code: int - a standard Command API error code. Optional.
    • message: String - a descriptive message explaining the error. Optional.
    • display: String - set to popup to display the error in a modal popup. Optional.

Query errors are shown as non-blocking toasts by default; use display: "popup" for a modal. The browser developer console logs the datasource id and any returned error code or message.

Response Example:

Successful Query:

{
  "columns": [
    { "name": "username", "type": "string", "key": true },
    { "name": "password", "type": "string" }
  ],
  "rows": [
    ["user1", "abc12"],
    ["user2", "xyz34"]
  ]
}

Error Example:

{
  "error": {
    "code": 500
  }
}

dataSourceInsert​

JSONObject dataSourceInsert(String session, String userid, String datasourceid, String[] columns, JSONObject data, boolean before)

Called when an insert operation is attempted, before and/or after executing the SQL statement, based on the dataSourceOption configuration (callback.before and callback.after).

  • Before: If null is returned, the SQL statement executes normally. If a JSONObject is returned, the SQL statement is skipped, and the returned object is sent to the client UI.

  • After Execution (callback.after): This is triggered only when the SQL statement executes successfully. If a JSONObject is returned, it is sent to the client UI, replacing the SQL result.

It automatically triggers a global refresh of the data source if it returns a not null value, or a session refresh if the data source's refresh option is set to false with dataSourceOption().

The returned JSON object can also include the standard Command API response keys. When the callback returns a custom response while the current form or table edit popup remains open, the top-level fields property can modify the current fields, for example to display field errors or change field values. This is mainly useful in before callbacks, or whenever the callback skips or replaces the SQL operation and keeps the editor open.

Supports direct callback by @dataSourceInsert annotations. See Annotations examples.

Parameters:

  • session: String - session id string that uniquely identifies the client session.
  • userid: String - the user id.
  • dataSourceId: String - the datasource id.
  • columns: String[] - array of column ids.
  • data: JSONObject - { "rows": [["<col 1 value>", "<col 2 value>", ...], ...] };
  • before: boolean - true if the callback was called before the execution of SQL code, false otherwise.

Returns:

  • JSONObject - inserted rows. Triggers a data source refresh.
    • inserted: int - The number of rows successfully inserted.
  • null - no action is taken.

Response Example:

{
  "inserted": 3
}

dataSourceUpdate​

JSONObject dataSourceUpdate(String session, String userid, String datasourceid, String[] columns, JSONObject data, boolean before)

Called when an update operation is attempted, before and/or after executing the SQL statement, based on the dataSourceOption configuration (callback.before and callback.after).

  • Before: If null is returned, the SQL statement executes normally. If a JSONObject is returned, the SQL statement is skipped, and the returned object is sent to the client UI.

  • After Execution (callback.after): This is triggered only when the SQL statement executes successfully. If a JSONObject is returned, it is sent to the client UI, replacing the SQL result.

It automatically triggers a global refresh of the data source if it returns a not null value, or a session refresh if the data source's refresh option is set to false with dataSourceOption().

To support table CSV imports, update callbacks should also include the keys of rows not found in the datasource in not_found. During import, keyed rows are tried as updates first; rows returned in not_found are then inserted. This protects filtered or stale datasource views, where a row that looks new to the client may already exist in the datasource. Returning only an update count is not enough for the insert fallback, because the table needs the specific missing keys.

The returned JSON object can also include the standard Command API response keys. When the callback returns a custom response while the current form or table edit popup remains open, the top-level fields property can modify the current fields, for example to display field errors or change field values. This is mainly useful in before callbacks, or whenever the callback skips or replaces the SQL operation and keeps the editor open.

Supports direct callback by @dataSourceUpdate annotations. See Annotations examples.

Parameters:

  • session: String - session id string that uniquely identifies the client session.
  • userid: String - the user id.
  • dataSourceId: String - the datasource id.
  • columns: String[] - array of column ids.
  • data: JSONObject - contains the data to update.
    • rows: Array – An array of objects, each representing a row to update:
      • <key value>: string – the key value identifying the row to update. This is the property name.
      • Value (Array): an array of column values corresponding to the column IDs specified in the columns parameter.
{
  "rows": [
    {
      "<key value>": ["<col 1 value>", "<col 2 value>", ...]
    },
    ...
  ]
}
  • before: boolean - true if the callback was called before the execution of SQL code, false otherwise.

Returns:

  • JSONObject - updated rows. Triggers a data source refresh.
    • updated: int - The number of rows successfully updated.
    • not_found: String[] - An array of keys not found in the datasource. Optional; required for table CSV import fallback.

Response Example:

{
  "updated": 2,
  "not_found": ["key1"]
}

dataSourceDelete​

JSONObject dataSourceDelete(String session, String userid, String datasourceid, JSONObject data, boolean before)

Called when a delete operation is attempted, before and/or after executing the SQL statement, based on the dataSourceOption configuration (callback.before and callback.after).

  • Before: If null is returned, the SQL statement executes normally. If a JSONObject is returned, the SQL statement is skipped, and the returned object is sent to the client UI.

  • After Execution (callback.after): This is triggered only when the SQL statement executes successfully. If a JSONObject is returned, it is sent to the client UI, replacing the SQL result.

It automatically triggers a global refresh of the data source if it returns a not null value, or a session refresh if the data source's refresh option is set to false with dataSourceOption().

The returned JSON object can also include the standard Command API response keys.

Supports direct callback by @dataSourceDelete annotations. See Annotations examples.

Parameters:

  • session: String - session id string that uniquely identifies the client session.
  • userid: String - the user id.
  • dataSourceId: String - the datasource id.
  • data: JSONObject - { "rows": ["key 1>", "key 2>", ... ] }
  • before : boolean - true if the callback was called before the execution of SQL code, false otherwise.

Returns:

  • JSONObject - deleted rows. Triggers a data source refresh.
    • deleted: int - the number of rows successfully deleted.
    • not_found: String[] - An array of keys not found in the datasource. Optional.
  • null - no action is taken.

Response Example:

{
  "deleted": 1,
  "not_found": ["key1"]  
}

Annotations examples​

In the Java computer programming language, an annotation is a form of syntactic metadata that can be added to Java source code. An annotation can be used in a datasource's callbacks to directly call a function whenever the datasource id matches the one specified in the annotation, as shown in the following example:

@dataSourceInsert("datasourceid") 
 public static JSONObject dataSourceInsertTask(String session, String userid, String datasourceid, String[] columns, JSONObject data, boolean before) { 
  ...
 }

Using annotations does not preclude the normal callback from being called.

I/O Servers​

IOEvent​

static void IOEvent(String id, String value)

Triggered by the value change of any data point of an I/O server.

Parameters:

  • id: String - the server id and the name of the data point. According to the type of server, the format changes but it generally appears as server name, as declared the ioServers parameter in hsyco.ini, followed by a specific name representing the data point within the system
  • value: String - the new value. For binary inputs or outputs, the returned values are 0 or 1.

IOStartupEvent​

static void IOStartupEvent(int serverIndex)

Triggered by the start of the communication thread of each I/O server - once for each server at the beginning of the execution of HSYCO, and also after every reboot of the communication thread, for example after communication errors.

note

This is a blocking method. The I/O server driver will start after this function returns.

Parameters:

  • serverIndex: int - the I/O server number, starting from 0, based on the listing order of the ioServers parameter in hsyco.ini.

Modbus​

For detailed information about the Modbus protocol, and the response PDU formats, you should refer to the MODBUS Application Protocol Specification V1.1b documentation at: http://www.modbus.org/docs/Modbus-Application-Protocol-V1-1b.pdf

ModbusEvent​

static byte[] ModbusEvent(String name, InetAddress addr, int unitid, byte[] pdu)

Called by the Modbus Server I/O Server on every Modbus request received from a Modbus client.

The returned byte array is used as the Modbus response PDU (function code and data).

Parameters:

  • name: String - the name of the Modbus Server I/O server
  • addr: InetAddress - IP address of the Modbus client
  • unitid: int - the unit id set in the received Modbus request
  • pdu: byte[] - the request PDU data, in hexadecimal string format.

Returns:

  • byte[] - the response PDU data.

Location Services​

LocationEvent​

static void LocationEvent(long mac, InetAddress ip, int zoneId)

Called, if the location service is active, when a variation in the association of a client to the Wi-Fi Access Points is detected.

Parameters:

  • mac: long - the MAC address of the client
  • ip: InetAddress - the IP address of the client, if available, or null (the IP address could be null if the associated device is not connected to the HSYCO Web interface)
  • zoneId: int - in case of association, it is the Access Point sequence number, according to the order defined in the LocationBases parameter in hsyco.ini; -1 if the client was de-associated from the Wi-Fi network.

LocationBeaconEvent​

caution

The Beacons functionality for iOS is experimental and subject to changes.

static void LocationBeaconEvent(String session, String address, String userid, String zone, String distance, boolean background)

Called when the HSYCO App detects a change in the proximity of one of the configured beacons. See Beacons on HSYCO App for iOS for additional information.

There is no guarantee that the event would be fired.

Network delays or errors could cause delayed triggering of this event.

Parameters:

  • session: String - session id string that uniquely identifies the client session
  • address: String - the beacon's address
  • userid: String - the user id
  • zone: String - the beacon's zone
  • distance: String - far, near, immediate or off
  • background: boolean - true if the app called the server while in background mode (app closed)

LocationGeoEvent​

LocationGeoEvent(String session, String address, String userid, double lat, double lon, double alt, double speed, double course, double ah, double av, double as, double ac, boolean background)

Called when a geographic location notification is sent by an HSYCO iOS or Android app.

Parameters:

  • session: String - session id string that uniquely identifies the client session
  • address: String - the beacon's address
  • userid: String - the user id
  • lat: double - geographic coordinates latitude, in decimal degrees (positive east, negative west)
  • lon: double - geographic coordinates longitude, in decimal degrees (positive north, negative south)
  • alt: double - altitude, in meters
  • speed: double - speed, in meters per second
  • course: double - course, in decimal degrees
  • ah: double - radius of uncertainty for the location, in meters
  • av: double - accuracy of the altitude value, in meters
  • as: double - accuracy of the speed value, in meters per second
  • ac: double - accuracy of the course value, in degrees
  • background: boolean - true if the app called the server while in background mode (app closed).

Network Services​

httpCallEvent​

static String httpCallEvent(String address, boolean secure, String query)

Called when the HSYCO HTTP server receives a GET request with the following path:

/x/httpcall?query

This is an example of an HTTP Call

http://HSYCO SERVER IP/x/httpcall?example=1
note

The HTTP client's IP address must be in the trusted network range, or the httpcall request will be rejected, unless HTTPServerLowSecurityEnabled is true and the request is sent using HTTPS

This method returns a string, that will be sent as the text/plain answer to the HTTP client (with HTTP response code 200).

HSYCO will return a 404 Not Found response code if all of the following conditions are true:

  • no HTTP event matches the query in EVENTS
  • the httpCallEvent JavaScript callback is not defined in EVENTS, or doesn't return a value
  • the httpCallEvent Java callback is not defined in any plugins, or returns null.

If the httpCallEvent is defined both in JavaScript and Java, the Java version return value (unless null) will be used in the HTTP response.

Parameters:

  • address: String - the IP address of the HTTP client
  • secure: boolean - true if the request is sent to the HTTPS server, false if the request is sent to the HTTP server
  • query: String - the string following the ? in the URL path.

Returns:

  • String - the string to send as the text/plain answer to the HTTP client.

httpRawEvent​

static void httpRawEvent(String host, boolean secure, String version, String httpmethod, boolean gzip, String contenttype, String query, String session, String userid, BufferedOutputStream out, BufferedInputStream in)

Called when the HSYCO HTTP server receives a GET, POST, PUT, PATCH or DELETE request with the following path:

/x/raw
note

The httpRawEvent method is invoked only if:

  • the request has a valid user authentication cookie or
  • the HTTP client's IP address is in the trusted network range and the request is sent using HTTPS or
  • the HTTP client's IP address is in the trusted network range and the HTTPServerLowSecurityEnabled option is true

The application code inside the httpRawEvent() method must write a complete HTTP response (both headers and body) to the provided BufferedOutputStream.

If multiple httpRawEvent() callbacks are defined, only one must write the HTTP response.

Parameters:

  • host: String - the IP address of the HTTP client
  • secure: boolean - true if the request is sent to the HTTPS server, false if the request is sent to the HTTP server
  • version: String - the HTTP version, as passed in the HTTP request header
  • httpmethod: String - the HTTP request's method, "GET", "HEAD", "POST", "PUT", "PATCH" or "DELETE"
  • gzip: boolean - true if the client accepts compressed content (the Accept-Encoding header contains "gzip")
  • contenttype: String - the HTTP request's content type (value of Content-Type header)
  • query: String - the string following the ? in the URL path, or null if not present
  • session: String - the authenticated session id, or null
  • userid: String - the user id for requests having a valid authentication cookie, null otherwise
  • out: BufferedOutputStream - the output stream that the application code should use to write the full HTTP response
  • in: BufferedInputStream - the input stream containing request body data for POST, PUT, PATCH, DELETE (null for GET or HEAD)

Example:

public static void httpRawEvent(String host, boolean secure, String version, String httpmethod, boolean gzip, String contenttype, String query, String session, String userid, BufferedOutputStream out, BufferedInputStream in) throws Exception {
	SimpleDateFormat dateFormat = new SimpleDateFormat(DateUtils.PATTERN_RFC1123);
	
	// Read request body if present (POST, PUT, PATCH, DELETE)
	String body = "";
	if (in != null) {
		StringBuilder sb = new StringBuilder();
		byte[] buffer = new byte[4096];
		int read;
		while ((read = in.read(buffer)) != -1) {
			sb.append(new String(buffer, 0, read, "UTF-8"));
		}
		body = sb.toString();
	}
	
	Writer w = new OutputStreamWriter(out, "UTF-8");

	// Build a response message depending on HTTP method
	String content;
	switch (httpmethod) {
	case "GET":
		content = "GET received from host [" + host + "]\r\nQuery: " + query + "\r\n";
		break;
	
	case "POST":
		content = "POST data received from host [" + host + "]:\r\n" + body + "\r\n";
		break;
	
	case "PUT":
		content = "PUT data received from host [" + host + "]:\r\n" + body + "\r\n";
		break;
	
	case "PATCH":
		content = "PATCH data received from host [" + host + "]:\r\n" + body + "\r\n";
		break;
	
	case "DELETE":
		content = "DELETE data received from host [" + host + "]:\r\n" + body + "\r\n";
		break;
	
	default:
		// Unknown method
		w.write(version + " 405 Method Not Allowed\r\n");
		w.write("Date: " + dateFormat.format(new Date()) + "\r\n");
		w.write("Server: HSYCO/" + hsyco.VERSION + "\r\n");
		w.write("Content-length: 0\r\n");
		w.write("Content-type: text/plain\r\n");
		w.write("Cache-Control: no-store, no-cache\r\n\r\n");
		w.flush();
		return;
	}

	// Write successful response
	w.write(version + " 200 OK\r\n");
	w.write("Date: " + dateFormat.format(new Date()) + "\r\n");
	w.write("Server: HSYCO/" + hsyco.VERSION + "\r\n");
	w.write("Content-length: " + content.getBytes("UTF-8").length + "\r\n");
	w.write("Content-type: text/plain\r\n");
	w.write("Cache-Control: no-store, no-cache\r\n\r\n");
	w.write(content);
	w.flush();

SysLogEvent​

static void SysLogEvent(String address, String log)

Called when the HSYCO SYSLOG server receives a log message from a network client.

Note that this is a blocking call. The SYSLOG server will not process further messages until the last call has been processed.

Parameters:

  • address: String - the IP address of the SYSLOG client
  • log: String - SYSLOG log message.

PBX​

PBXCallEvent​

static boolean PBXCallEvent(String host, String caller, String called)

Called when a call notification is sent to HSYCO by the PBX system.

If the method returns true, the request is recorded on the log file with the [OK] status, with [ERROR] otherwise.

The PBX should generate HTTP requests to the HSYCO Web Server, using the following formats:

http://192.168.0.50/x/vcall/<from>/<to>

or:

http://192.168.0.50/x/vcall?from=<from>&to=<to>

For example, the HTTP request:

http://192.168.0.50/x/vcall?from=21&to=25

is interpreted as a call notification from internal number 21 to number 25.

note

The HTTP client's IP address must be in the trusted network range, or the httpcall request will be rejected.

Parameters:

  • host: String - the IP address of the PBX server
  • caller: String - the caller number
  • called: String - the called number.

Returns:

  • boolean - return true to generate a log entry with [OK] status, false for [ERROR] status.

Timers and Schedulers​

UserTimerEvent​

static boolean UserTimerEvent(String name, boolean active)

Called when a user timer or scheduler’s rule should be activated, and before executing the associated action in EVENTS.

It is also executed at the timer or scheduler’s rule deactivation.

This method must return a true value in order to make the timer or rule actually active and the associated actions executed.

Whenever the method returns false, the timer will not be activated, and the method will be called again once a minute for the scheduled duration of the timer.

In the same way, if the method returns false when the timer or rule is deactivated, the timer or rule will not be deactivated, extending the timer activation beyond the scheduled duration.

This is a blocking method.

Parameters:

  • name: String - timer name or scheduler’s rule name
  • active: boolean - true when activating and false when deactivating the timer or scheduler’s rule.

Returns:

  • boolean - true to confirm the timer event, false to block the event.
note

The JavaScript UserTimerEvent function is alway called, but its return value is used only when the Java UserTimerEvent callback is not defined or returned true.

User Interface​

pageEvent​

static void pageEvent(String address, String session, String userid, String project, String page)

Called when a Web client initially loads a project and when navigating between pages. Popup and overlay pages do not trigger this event.

There is no guarantee that the event would be fired the exact moment the page is loaded.

Network delays or errors could cause delayed triggering of this event.

Parameters:

  • address: String - the client’s IP address string in textual presentation
  • session: String - session id string that uniquely identifies the client session
  • userid: String - the user id
  • project: String - project’s id
  • page: String - the page id of the current page, with the #landscape or #portrait suffix when the project's pages or overlays have an orientation. A page without an orientation is reported with the #landscape suffix.

loginEvent​

static void loginEvent(String address, String session, String userid)

Called when a user authenticates with a valid PIN or PIN/PUK.

Note that, while the session string passed to the pageEvent callback contains the browser global session id followed by a web view id, the session string passed to loginEvent only contains the global session id. The global session id is the portion of session id that is common between multiple web views open concurrently on the same web browser.

Parameters:

  • address: String - the client’s IP address string in textual presentation
  • session: String - session id string that uniquely identifies the client session
  • userid: String - the user id.

logoutEvent​

static void logoutEvent(String address, String session, String userid, boolean lock)

Called when a user logs out or locks the user interface.

Note that, while the session string passed to the pageEvent callback contains the browser global session id followed by a web view id, the session string passed to logoutEvent only contains the global session id. The global session id is the portion of session id that is common between multiple web views open concurrently on the same web browser.

Parameters:

  • address: String - the client’s IP address string in textual presentation
  • session: String - session id string that uniquely identifies the client session
  • userid: String - the user id
  • lock: boolean - false when logging out; true when the user locks the user interface.

uiClearEvent​

static void uiClearEvent(String session)

Called, following an explicit call of uiClear() or after the client session inactivity timeout expires, if the client session becomes active again (i.e. the client starts handshaking again with the server with the same session id).

Parameters:

  • session: String - session id string that uniquely identifies the client session.

userCommand​

static String userCommand(String session, String userid, String name, String param)

Called by user clicks on buttons created in the Web interface with the Button object in action Command mode, by a USER action in EVENTS, or by the user() Java method and JavaScript function. Also triggered by by the screensaver page.

This method can return a command response. See the Command API for supported response strings and JSON responses, including status logging, navigation, app actions, clipboard/share, downloads, toasts, popups, and errors.

JSON responses must be converted to strings before they are returned.

note

As this callback may return data synchronously to the Web interface in response to a user command, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.

Parameters:

  • session: string - a session id string that uniquely identifies the client session, or null when not available
  • userid: string - the user id, or null when not available
  • name: String - the name field of the (user) object
  • param: String - the param of the (user) object.

Returns:

  • String - optional command response, using the response syntax described in the Command API. If this function returns null, an [ERROR] status is logged in the log file. Any returned response logs an [OK] status by default.

userSubmit​

static String userSubmit(String session, String uid, String name, HashMap<String, String> fields)

This callback is similar to userCommand(String session, String uid, String name, String param).

When userSubmit() is defined, it will be called when a Button in Submit action mode is pressed, while userCommand() will continue to be called on Button in Command action mode.

userSubmit() provides a more convenient access to the values of multiple input fields in a form.

This function can optionally return a command response. See the Command API for supported response strings and JSON responses, including status logging, navigation, app actions, clipboard/share, downloads, toasts, popups, and errors.

JSON responses must be converted to strings before they are returned.

note

As this callback may return data synchronously to the Web interface in response to a user command, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.

Parameters:

  • session: String - a session id string that uniquely identifies the client session
  • userid: String - the user id
  • name: String - the id of the (submit!id) object
  • fields: HashMap< String, String> - the hash map of all input fields in the container where the (submit) object is located.

Returns:

  • String - optional command response, using the response syntax described in the Command API. If this function returns null, an [ERROR] status is logged in the log file. Any returned response logs an [OK] status by default.

WebRootRequestEvent​

static String WebRootRequestEvent(InetAddress addr, boolean secure, String useragent)

This method is called when the Web server receives a root URL request. It can return a string to redirect the browser to a valid URL, or null to prevent redirection.

note

As this callback returns data synchronously to the Web interface in response to the HTTP request, its execution should be fast enough to avoid the timeout of the browser's request. To ensure a safe margin, it should complete in no more than one second.

Parameters:

  • addr: InetAddress - the HTTP client’s address
  • secure: boolean - true if this is an HTTPS request
  • useragent: String - the Web browser’s user agent information.

Returns:

  • String - optional return string containing a valid absolute or relative URL