Difference between revisions of "Java Callback Methods API"
(58 intermediate revisions by 5 users not shown) | |||
Line 1: | Line 1: | ||
− | + | [[Category:Java]] | |
− | |||
Callback methods are called by the HSYCO events management system. | Callback methods are called by the HSYCO events management system. | ||
Line 13: | Line 12: | ||
=== DaylightEvent === | === DaylightEvent === | ||
− | + | <source lang="java">static void DaylightEvent(boolean day)</source> | |
Called at sunrise and sunset, according to the latitude and longitude values set in hsyco.ini, and the optional SunriseOffsetMinutes and SunsetOffsetMinutes parameters. | Called at sunrise and sunset, according to the latitude and longitude values set in hsyco.ini, and the optional SunriseOffsetMinutes and SunsetOffsetMinutes parameters. | ||
Line 23: | Line 22: | ||
=== getUserVersion === | === getUserVersion === | ||
− | + | <source lang="java">static String getUserVersion()</source> | |
This method returns a string, used by the HSYCO run-time to generate the user code version information log line at startup. | This method returns a string, used by the HSYCO run-time to generate the user code version information log line at startup. | ||
Line 36: | Line 35: | ||
=== haActiveEvent === | === haActiveEvent === | ||
− | + | <source lang="java">static void haActiveEvent(boolean active)</source> | |
Triggered by the change of state of an HSYCO server in a master/slave high availability configuration. | Triggered by the change of state of an HSYCO server in a master/slave high availability configuration. | ||
Line 43: | Line 42: | ||
'''Parameters:''' | '''Parameters:''' | ||
* active: boolean - true if the server is active, false if not active. | * active: boolean - true if the server is active, false if not active. | ||
− | |||
=== PowerEvent === | === PowerEvent === | ||
− | + | <source lang="java">static int PowerEvent(int power)</source> | |
Triggered by a change of the current power load level, as set using the powerSet() Java API or the POWER action. | 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 | + | 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:''' | '''Parameters:''' | ||
− | * power: | + | * power: int - the power level, in Watts. |
Line 63: | Line 61: | ||
=== programTimerEvent === | === programTimerEvent === | ||
− | + | <source lang="java">static void programTimerEvent(String name)</source> | |
Called when a program timer is activated. | Called when a program timer is activated. | ||
Line 75: | Line 73: | ||
=== SchedulerEvent === | === SchedulerEvent === | ||
− | + | <source lang="java">static void SchedulerEvent(String groupname, String schedulename)</source> | |
− | This callback blocking | + | 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. | 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. | ||
Line 85: | Line 83: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * groupname: | + | * groupname: String - the scheduler’s group name |
− | * schedulename: | + | * schedulename: String - the scheduler’s name. |
− | |||
=== StartupEvent === | === StartupEvent === | ||
− | + | <source lang="java">static void StartupEvent()</source> | |
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. | 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. | ||
Line 97: | Line 94: | ||
=== SunPositionEvent === | === SunPositionEvent === | ||
− | + | <source lang="java">static void SunPositionEvent(int azimuth, int elevation)</source> | |
Called when the Sun changes its height with respect to the horizon or its angle from true north. | Called when the Sun changes its height with respect to the horizon or its angle from true north. | ||
Line 103: | Line 100: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | *azimuth: | + | *azimuth: int - the current Sun angle from true north, in decimal degrees |
− | *elevation: | + | *elevation: int - the current Sun elevation in decimal degrees from the horizon. Elevation is negative at night. |
− | |||
=== TimeEvent === | === TimeEvent === | ||
− | + | <source lang="java">static void TimeEvent(long time)</source> | |
Called every 60 seconds. | Called every 60 seconds. | ||
Line 123: | Line 119: | ||
=== varEvent === | === varEvent === | ||
− | + | <source lang="java">static void varEvent(String name, String value)</source> | |
Triggered by the change of value of a program variable. | Triggered by the change of value of a program variable. | ||
Line 129: | Line 125: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * name: | + | * name: String - the variable name. Names are case-insensitive |
− | * value: | + | * value: String - the value to be assigned to the program variable. |
== Cameras == | == Cameras == | ||
Line 136: | Line 132: | ||
=== CameraCommandEvent === | === CameraCommandEvent === | ||
− | + | <source lang="java">static int cameraCommandEvent(String function, String action, String camera)</source> | |
Triggered by a camera control input from the Web interface. | Triggered by a camera control input from the Web interface. | ||
Line 157: | Line 153: | ||
=== CameraMotionEvent === | === CameraMotionEvent === | ||
− | + | <source lang="java">static void CameraMotionEvent(String eventName, long remoteTime)</source> | |
Called when HSYCO starts recording video from a camera. | Called when HSYCO starts recording video from a camera. | ||
Line 175: | Line 171: | ||
=== CameraViewEvent === | === CameraViewEvent === | ||
− | + | <source lang="java">static void CameraViewEvent(String camera, boolean active)</source> | |
CameraViewEvent() is called on changes of the live view status of cameras. | CameraViewEvent() is called on changes of the live view status of cameras. | ||
Line 193: | Line 189: | ||
=== DmxEvent === | === DmxEvent === | ||
− | + | <source lang="java">static void DmxEvent(int channel, int state)</source> | |
Called after changes to DMX-512 channels. | Called after changes to DMX-512 channels. | ||
Line 205: | Line 201: | ||
=== DmxFilter === | === DmxFilter === | ||
− | + | <source lang="java">static int DmxFilter(int channel, int state, boolean reverse)</source> | |
This method allows to filter the value of the status of each channel on the DMX-512 buses, sending to the gateway different values from those set in HSYCO. | This method allows to filter the value of the status of each channel on the DMX-512 buses, sending to the gateway different values from those set in HSYCO. | ||
Line 231: | Line 227: | ||
=== DmxStartupEvent === | === DmxStartupEvent === | ||
− | + | <source lang="java">static void DmxStartupEvent(int serverIndex)</source> | |
Called when starting the monitor threads for each DMX bus, once per bus at the start of the execution of HSYCO, and also after every restart of the monitor thread, for example after communication errors. | Called when starting the monitor threads for each DMX bus, once per bus at the start of the execution of HSYCO, and also after every restart of the monitor thread, for example after communication errors. | ||
Line 248: | Line 244: | ||
=== IREvent === | === IREvent === | ||
− | + | <source lang="java">static void IREvent(boolean received, int irtransid, String event)</source> | |
This method is called when an IRTrans receives or sends an IR command from its local IR database. | This method is called when an IRTrans receives or sends an IR command from its local IR database. | ||
Line 265: | Line 261: | ||
=== IOEvent === | === IOEvent === | ||
− | + | <source lang="java">static void IOEvent(String id, String value)</source> | |
Triggered by the value change of any data point of an I/O server. | Triggered by the value change of any data point of an I/O server. | ||
Line 277: | Line 273: | ||
=== IOStartupEvent === | === IOStartupEvent === | ||
− | + | <source lang="java">static void IOStartupEvent(int serverIndex)</source> | |
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. | 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. | ||
Line 289: | Line 285: | ||
== Modbus == | == 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 http://www.modbus.org/docs/Modbus_Application_Protocol_V1_1b.pdf] | ||
+ | |||
=== ModbusEvent === | === ModbusEvent === | ||
− | + | <source lang="java">static byte[] ModbusEvent(String name, InetAddress addr, int unitid, byte[] pdu)</source> | |
Called by the Modbus Server I/O Server on every Modbus request received from a Modbus client. | Called by the Modbus Server I/O Server on every Modbus request received from a Modbus client. | ||
Line 310: | Line 309: | ||
* byte[] - the response PDU data. | * byte[] - the response PDU data. | ||
− | == | + | == Location Services == |
=== LocationEvent === | === LocationEvent === | ||
− | + | <source lang="java">static void LocationEvent(long mac, InetAddress ip, int zoneId)</source> | |
Called, if the location service is active, when a variation in the association of a client to the Wi-Fi Access Points is detected. | Called, if the location service is active, when a variation in the association of a client to the Wi-Fi Access Points is detected. | ||
Line 324: | Line 323: | ||
* 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) | * 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. | * 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 === | ||
+ | <div style="color:#CC0000">'''{{Note|<center>WARNING! The Beacons functionality for iOS is experimental and subject to changes.</center>}}''' | ||
+ | </div> | ||
+ | <source lang="java">static void LocationBeaconEvent(String session, String address, String userid, String zone, String distance, boolean background)</source> | ||
+ | |||
+ | 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 === | ||
+ | |||
+ | <source lang="java">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)</source> | ||
+ | |||
+ | 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 === | ||
+ | |||
+ | <source lang="java">static String httpCallEvent(String address, boolean secure, String query)</source> | ||
+ | |||
+ | 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 | ||
+ | <source>http://HSYCO SERVER IP/x/httpcall?example=1</source> | ||
+ | |||
+ | {{tip|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 user.java or 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 === | ||
+ | |||
+ | <source lang="java">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)</source> | ||
+ | |||
+ | Called when the HSYCO HTTP server receives a GET or POST request with the following path: | ||
+ | /x/raw | ||
+ | |||
+ | {{tip|The httpRawEvent is called only if the HTTP client's IP address is in the trusted network range and the HTTPServerLowSecurityEnabled option is true, or if the request has a valid user authentication cookie}} | ||
+ | |||
+ | The application code inside the httpRawEvent() method should write a complete HTTP response (both headers and body) to the BufferedOutputStream passed as parameter. | ||
+ | |||
+ | If multiple httpRawEvent() callbacks are defined, only one should write the HTTP response to the BufferedOutputStream. | ||
+ | |||
+ | |||
+ | '''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", "POST" or "HEAD" | ||
+ | * 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 that the application code should read to retrieve the POST data, or null for GET or HEAD requests. | ||
+ | |||
+ | |||
+ | '''Example:''' | ||
+ | |||
+ | <source lang="java"> | ||
+ | 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 { | ||
+ | Writer w = new OutputStreamWriter(out, "UTF-8"); | ||
+ | SimpleDateFormat dateFormat = new SimpleDateFormat(DateUtils.PATTERN_RFC1123); | ||
+ | |||
+ | if (httpmethod.equals("POST")) { | ||
+ | byte[] bb = new byte[1024]; | ||
+ | int i = 0; | ||
+ | StringBuffer sb = new StringBuffer(); | ||
+ | while((i = in.read(bb)) != -1) { | ||
+ | sb.append(new String(bb, 0, i, "UTF-8")); | ||
+ | } | ||
+ | String content = "Post data echoed from host [" + host + "] : " + sb.toString() + "\r\n"; | ||
+ | w.write(version); | ||
+ | w.write(" 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.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(); | ||
+ | } else { | ||
+ | w.write(version); | ||
+ | w.write(" 400 Not Found\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(); | ||
+ | } | ||
+ | } | ||
+ | </source> | ||
+ | |||
+ | === SysLogEvent === | ||
+ | |||
+ | <source lang="java">static void SysLogEvent(String address, String log)</source> | ||
+ | |||
+ | 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 == | == PBX == | ||
Line 329: | Line 487: | ||
=== PBXCallEvent === | === PBXCallEvent === | ||
− | + | <source lang="java">static boolean PBXCallEvent(String host, String caller, String called)</source> | |
Called when a call notification is sent to HSYCO by the PBX system. | 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. | 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: | ||
+ | |||
+ | <nowiki>http://192.168.0.50/x/vcall/<from>/<to></nowiki> | ||
+ | |||
+ | or: | ||
+ | |||
+ | <nowiki>http://192.168.0.50/x/vcall?from=<from>&to=<to></nowiki> | ||
+ | |||
+ | For example, the HTTP request: | ||
+ | |||
+ | <nowiki>http://192.168.0.50/x/vcall?from=21&to=25</nowiki> | ||
+ | |||
+ | is interpreted as a call notification from internal number 21 to number 25. | ||
+ | |||
+ | {{tip|The HTTP client's IP address must be in the trusted network range, or the httpcall request will be rejected.}} | ||
+ | |||
Line 351: | Line 526: | ||
=== SlimPowerEvent === | === SlimPowerEvent === | ||
− | + | <source lang="java">static void SlimPowerEvent(int index, int power)</source> | |
Called when a Squeezebox player is turned on or off. | Called when a Squeezebox player is turned on or off. | ||
Line 363: | Line 538: | ||
=== SlimStatusEvent === | === SlimStatusEvent === | ||
− | + | <source lang="java">static void SlimStatusEvent(int index, int status)</source> | |
Called when a Squeezebox player changes its playback mode. | Called when a Squeezebox player changes its playback mode. | ||
Line 375: | Line 550: | ||
=== SlimVolumeEvent === | === SlimVolumeEvent === | ||
− | + | <source lang="java">static void SlimVolumeEvent(int index, int volume)</source> | |
Called when a Squeezebox player changes its volume level. | Called when a Squeezebox player changes its volume level. | ||
Line 389: | Line 564: | ||
=== UserTimerEvent === | === UserTimerEvent === | ||
− | + | <source lang="java">static boolean UserTimerEvent(String name, boolean active)</source> | |
Called when a user timer or scheduler’s rule should be activated, and before executing the associated action in EVENTS. | Called when a user timer or scheduler’s rule should be activated, and before executing the associated action in EVENTS. | ||
Line 421: | Line 596: | ||
=== pageEvent === | === pageEvent === | ||
− | + | <source lang="java">static void pageEvent(String address, String session, String userid, String project, String page)</source> | |
Called when a Web client initially loads a project and when navigating between pages. | Called when a Web client initially loads a project and when navigating between pages. | ||
Line 432: | Line 607: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * address: | + | * address: String - the client’s IP address string in textual presentation |
− | * session: | + | * session: String - session id string that uniquely identifies the client session |
− | * userid: | + | * userid: String - the user id |
− | * project: | + | * project: String - project’s id |
− | * page: | + | * page: String - the page id of the current page, with the #landscape or #portrait suffix if the page has distinct orientation versions in the project. |
+ | |||
+ | === loginEvent === | ||
+ | |||
+ | <source lang="java">static void loginEvent(String address, String session, String userid)</source> | ||
+ | |||
+ | 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 === | ||
+ | |||
+ | <source lang="java">static void logoutEvent(String address, String session, String userid, boolean lock)</source> | ||
+ | |||
+ | 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 === | === uiClearEvent === | ||
− | + | <source lang="java">static void uiClearEvent(String session)</source> | |
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). | 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). | ||
Line 448: | Line 653: | ||
'''Parameters:''' | '''Parameters:''' | ||
− | * session: | + | * session: String - session id string that uniquely identifies the client session. |
+ | === userCommand === | ||
− | = | + | <source lang="java">static String userCommand(String name, String param)</source> |
− | + | Called by user clicks on buttons created in the Web interface with the (user), (usermini), (usermicro), (userrgb) or (userimage) objects, by a USER action in EVENTS, or by the user() Java method and JavaScript function. Also triggered by by the screensaver (see the '''[[Screensaver| Screensaver]]''' page for more details). | |
− | + | 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 “!”. | |
− | + | {{userCommand return values}} | |
− | + | {{tip|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.}} | |
Line 470: | Line 676: | ||
'''Returns:''' | '''Returns:''' | ||
− | * | + | * null: an [ERROR] status is logged in the log file, while any other string causes the log of an [OK] status. |
+ | * "page:page name": navigate to the specified page | ||
+ | * "page:back": navigate to the previous page | ||
+ | * "page:forward": navigate to the next page | ||
+ | * "page:close": if the user button that generated the call has an open popup linked to it, close it | ||
+ | * "copy:<text>": tells the browser or [[HSYCO App]] to copy the text in the clipboard. On browser it will display a confirm popup with the text to be copied. | ||
+ | * "share:<text>": tells the [[HSYCO App]] to show a share popup with various options (copy, send through email, save to files etc.). On browser it will behave like copy. | ||
− | === userCommand with session information === | + | === userCommand - with session information === |
− | + | <source lang="java">static String userCommand(String session, String userid, String name, String param)</source> | |
Same as userCommand(String name, String param), but with additional session and user id information passed as parameters. You should only use one of the two userCommand() callback methods in user.java. If you declare both, only this four parameters version will be called. | Same as userCommand(String name, String param), but with additional session and user id information passed as parameters. You should only use one of the two userCommand() callback methods in user.java. If you declare both, only this four parameters version will be called. | ||
+ | |||
+ | {{tip|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.}} | ||
Line 489: | Line 703: | ||
'''Returns:''' | '''Returns:''' | ||
− | * | + | * null: an [ERROR] status is logged in the log file, while any other string causes the log of an [OK] status. |
+ | * "page:page name": navigate to the specified page | ||
+ | * "page:back": navigate to the previous page | ||
+ | * "page:forward": navigate to the next page | ||
+ | * "page:close": if the user button that generated the call has an open popup linked to it, close it | ||
+ | * "copy:<text>": tells the browser or [[HSYCO App]] to copy the text in the clipboard. On browser it will display a confirm popup with the text to be copied. | ||
+ | * "share:<text>": tells the [[HSYCO App]] to show a share popup with various options (copy, send through email, save to files etc.). On browser it will behave like copy. | ||
=== userSubmit === | === userSubmit === | ||
− | + | <source lang="java">static String userSubmit(String session, String uid, String name, HashMap<String, String> fields)</source> | |
This callback is similar to userCommand(String session, String uid, String name, String param) and should be used only when the four parameters version of userCommand() is also defined in user.java. | This callback is similar to userCommand(String session, String uid, String name, String param) and should be used only when the four parameters version of userCommand() is also defined in user.java. | ||
Line 503: | Line 723: | ||
This function can optionally return 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 “!”. | This function can optionally return 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 “!”. | ||
− | + | {{userCommand return values}} | |
+ | |||
+ | {{tip|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.}} | ||
Line 516: | Line 738: | ||
'''Returns:''' | '''Returns:''' | ||
− | * | + | * null: an [ERROR] status is logged in the log file, while any other string causes the log of an [OK] status. |
+ | * "page:page name": navigate to the specified page | ||
+ | * "page:back": navigate to the previous page | ||
+ | * "page:forward": navigate to the next page | ||
+ | * "page:close": if the user button that generated the call has an open popup linked to it, close it | ||
+ | * "copy:<text>": tells the browser or [[HSYCO App]] to copy the text in the clipboard. On browser it will display a confirm popup with the text to be copied. | ||
+ | * "share:<text>": tells the [[HSYCO App]] to show a share popup with various options (copy, send through email, save to files etc.). On browser it will behave like copy. | ||
=== WebRootRequestEvent === | === WebRootRequestEvent === | ||
− | + | <source lang="java">static String WebRootRequestEvent(InetAddress addr, boolean secure, String useragent)</source> | |
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. | 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. | ||
+ | |||
+ | {{tip|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:''' | '''Parameters:''' | ||
− | * addr: | + | * addr: InetAddress - the HTTP client’s address |
* secure: boolean - true if this is an HTTPS request | * secure: boolean - true if this is an HTTPS request | ||
− | * useragent: | + | * useragent: String - the Web browser’s user agent information. |
'''Returns:''' | '''Returns:''' | ||
− | * | + | * String - optional return string containing a valid absolute or relative URL |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− |
Latest revision as of 10:44, 3 April 2023
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.
Contents
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 user code version information log line at startup.
It is recommended to return a meaningful string with an appropriate identification of your user.java code and its version.
Returns:
- String - user code 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.
Parameters:
- name: String - 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.
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. Names are case-insensitive
- 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.
|
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.
DMX
DmxEvent
static void DmxEvent(int channel, int state)
Called after changes to DMX-512 channels.
Parameters:
- channel: int - DMX channel address, from 1 to 512 which might be preceded by the DMX gateway number, starting from 0
- state: int - the new channel value, from 0 to 255.
DmxFilter
static int DmxFilter(int channel, int state, boolean reverse)
This method allows to filter the value of the status of each channel on the DMX-512 buses, sending to the gateway different values from those set in HSYCO.
This way, it is possible to apply chromatic corrections, or any on the fly translation of channels values.
This is a blocking method and is called when sending commands to the DMX gateway.
It is also called after reading current channels values from the gateway. In this case the conversion function should be symmetric and return a complementary value.
Parameters:
- channel: int - the DMX channel address, from 1 to 512 which might be preceded by the DMX gateway number, starting from 0
- state: int - the unfiltered value of the channel, from 0 to 255
- reverse: boolean - false if called when writing to the gateway; true if called when reading from the gateway.
Returns:
- int - the channel value that will be sent to the DMX gateway.
The JavaScript DmxFilter function is called only when the Java DmxFilter callback is not defined or returned the original value.
DmxStartupEvent
static void DmxStartupEvent(int serverIndex)
Called when starting the monitor threads for each DMX bus, once per bus at the start of the execution of HSYCO, and also after every restart of the monitor thread, for example after communication errors.
It is safe, inside this method, to execute command methods for the same DMX gateway.
This is a blocking method. The DMX driver will start after this function returns.
Parameters:
- serverIndex: int - number of the DMX bus, starting from 0.
Infrared Control
IREvent
static void IREvent(boolean received, int irtransid, String event)
This method is called when an IRTrans receives or sends an IR command from its local IR database.
IRTrans can only receive and decode infrared commands that have been previously stored in its internal FLASH memory database.
Parameters:
- received: boolean - true if the command has been received by the IRTrans, false if sent
- irtransid: int - IRTrans number, starting from 0 for the first device, based on the listing order of the IRTrans parameter in hsyco.ini
- event: String - the string of the command received or issued, formatted as: "remote_name,command".
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.
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
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
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 user.java or 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 or POST request with the following path:
/x/raw
The httpRawEvent is called only if the HTTP client's IP address is in the trusted network range and the HTTPServerLowSecurityEnabled option is true, or if the request has a valid user authentication cookie
The application code inside the httpRawEvent() method should write a complete HTTP response (both headers and body) to the BufferedOutputStream passed as parameter.
If multiple httpRawEvent() callbacks are defined, only one should write the HTTP response to the BufferedOutputStream.
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", "POST" or "HEAD"
- 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 that the application code should read to retrieve the POST data, or null for GET or HEAD requests.
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 {
Writer w = new OutputStreamWriter(out, "UTF-8");
SimpleDateFormat dateFormat = new SimpleDateFormat(DateUtils.PATTERN_RFC1123);
if (httpmethod.equals("POST")) {
byte[] bb = new byte[1024];
int i = 0;
StringBuffer sb = new StringBuffer();
while((i = in.read(bb)) != -1) {
sb.append(new String(bb, 0, i, "UTF-8"));
}
String content = "Post data echoed from host [" + host + "] : " + sb.toString() + "\r\n";
w.write(version);
w.write(" 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.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();
} else {
w.write(version);
w.write(" 400 Not Found\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();
}
}
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.
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.
Squeezebox
SlimPowerEvent
static void SlimPowerEvent(int index, int power)
Called when a Squeezebox player is turned on or off.
Parameters:
- index: int - player number, starting from 0 for the first player, based on the listing order of the slimPlayers parameter in hsyco.ini
- power: int - 0: OFF, 1: ON.
SlimStatusEvent
static void SlimStatusEvent(int index, int status)
Called when a Squeezebox player changes its playback mode.
Parameters:
- index: int - player number, starting from 0 for the first player, based on the listing order of the slimPlayers parameter in hsyco.ini
- status: int - 0: OFF, 1: ON, 2: PAUSE, 3: PLAY, -1: UNKNOWN.
SlimVolumeEvent
static void SlimVolumeEvent(int index, int volume)
Called when a Squeezebox player changes its volume level.
Parameters:
- index: int - player number, starting from 0 for the first player, based on the listing order of the slimPlayers parameter in hsyco.ini
- volume: int - an integer number representing the volume change (not the absolute audio level) in a scale from 0 to 100; positive numbers correspond to a volume increase, negative numbers to a decrease.
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.
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.
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 if the page has distinct orientation versions in the project.
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 name, String param)
Called by user clicks on buttons created in the Web interface with the (user), (usermini), (usermicro), (userrgb) or (userimage) objects, by a USER action in EVENTS, or by the user() Java method and JavaScript function. Also triggered by by the screensaver (see the Screensaver page for more details).
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 navigate to a specific page when 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.
You can also use "page:back" or "page:forward" to move back and forth along the pages' navigation history. Use "page:close" to close a popup.
When the interface is loaded inside the HSYCO App (iOS or Android), you can send a specific command to the app by returning a string that starts with “app:“ followed by the command; the commands currently supported are “speech“, which enables the speech recognition, and “codescan“ which enables qr/bar code scanning.
Use "copy:<text>" to copy a text in the clipboard. In the HSYCO App you can also use "share:<text>" to open a popup with various options. This will behave like "copy" on browser.
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:
- name: String - the name field of the (user) object
- param: String - the param of the (user) object.
Returns:
- null: an [ERROR] status is logged in the log file, while any other string causes the log of an [OK] status.
- "page:page name": navigate to the specified page
- "page:back": navigate to the previous page
- "page:forward": navigate to the next page
- "page:close": if the user button that generated the call has an open popup linked to it, close it
- "copy:<text>": tells the browser or HSYCO App to copy the text in the clipboard. On browser it will display a confirm popup with the text to be copied.
- "share:<text>": tells the HSYCO App to show a share popup with various options (copy, send through email, save to files etc.). On browser it will behave like copy.
userCommand - with session information
static String userCommand(String session, String userid, String name, String param)
Same as userCommand(String name, String param), but with additional session and user id information passed as parameters. You should only use one of the two userCommand() callback methods in user.java. If you declare both, only this four parameters version will be called.
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 name field of the (user) object
- param: String - the param of the (user) object.
Returns:
- null: an [ERROR] status is logged in the log file, while any other string causes the log of an [OK] status.
- "page:page name": navigate to the specified page
- "page:back": navigate to the previous page
- "page:forward": navigate to the next page
- "page:close": if the user button that generated the call has an open popup linked to it, close it
- "copy:<text>": tells the browser or HSYCO App to copy the text in the clipboard. On browser it will display a confirm popup with the text to be copied.
- "share:<text>": tells the HSYCO App to show a share popup with various options (copy, send through email, save to files etc.). On browser it will behave like copy.
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) and should be used only when the four parameters version of userCommand() is also defined in user.java.
When userSubmit() is defined, it will be called when a (submit!id), (submitmini!id) or (submitmicro!id) button is pressed, while userCommand() will continue to be called on (user) buttons.
userSubmit() provides a more convenient access to the values of multiple input fields in a form.
This function can optionally return 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 navigate to a specific page when 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.
You can also use "page:back" or "page:forward" to move back and forth along the pages' navigation history. Use "page:close" to close a popup.
When the interface is loaded inside the HSYCO App (iOS or Android), you can send a specific command to the app by returning a string that starts with “app:“ followed by the command; the commands currently supported are “speech“, which enables the speech recognition, and “codescan“ which enables qr/bar code scanning.
Use "copy:<text>" to copy a text in the clipboard. In the HSYCO App you can also use "share:<text>" to open a popup with various options. This will behave like "copy" on browser.
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:
- null: an [ERROR] status is logged in the log file, while any other string causes the log of an [OK] status.
- "page:page name": navigate to the specified page
- "page:back": navigate to the previous page
- "page:forward": navigate to the next page
- "page:close": if the user button that generated the call has an open popup linked to it, close it
- "copy:<text>": tells the browser or HSYCO App to copy the text in the clipboard. On browser it will display a confirm popup with the text to be copied.
- "share:<text>": tells the HSYCO App to show a share popup with various options (copy, send through email, save to files etc.). On browser it will behave like copy.
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.
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