Shared Variables legacy server

From SpinetiX Support Wiki

Jump to: navigation, search
Note  
This article is a stub. Main article: Shared Variables.
Note  

Introduction

The legacy implementation provides unprotected access to the Shared Variables server through raw TCP socket connections or HTTP GET requests to the predefined end-points.

Note Note:
A secure alternative to this is to use the Web Storage bridge.

TCP interface

The TCP interface can be accessed by opening a raw TCP socket connection to the server HMP and sending a string of characters in a predefined format:

COMMAND [timestamp] "name" ["value"]\r\n

where:

  • COMMAND
    An uppercase command to be executed by the server; can be one of the following: UPDATE, EVENT, SUBSCRIBE, or UNSUBSCRIBE.
  • timestamp
    An optional Unix time(i.e., the number of microseconds since 00:00:00 UTC on January 1, 1970) to use for UPDATE or EVENT commands. If omitted, the server will use the time when the command is received as the timestamp.
  • name
    The Shared Variable name to which the command is applied or the event name in case of an "EVENT" command.
  • value
    The value to which a Shared Variable is updated in case of an "UPDATE" command or the event parameters in case of an "EVENT" command.
Note Notes:
  • The pairs of square brackets are just used as a conventional way to specify that the term is optional.
  • Individual commands are separated by the \r\n (0x0D 0x0A) two-byte sequence. This sequence should not appear inside the command.
  • Some special characters need to be escaped with a backslash: newline (0x0A) with \n, carriage return (0x0D) with \r, double quote (0x22) with \", null byte (0x00) with \0 and backslash itself with \\.

Update command

The UPDATE / update command is used to change (update) the value of a Shared Variable. If the Shared Variable does not exist, it is created on the server.

Event command

The EVENT / event command is used to send a UI event to the player; in fact, this command updates a special Shared Variable "%EVENTS%". The following events are supported:

  • keydown, keyup
    The value can be an SVG key identifier (e.g., Enter, PageUp, F5 etc.), a character (e.g., A ... Z, a ... z etc.) or a hexadecimal Unicode character (e.g., U+0041, U+007A etc.). It may be prefixed by one or more of the following modifiers: Ctrl+, Shift+, Alt+, Meta+, AltGr+ (e.g., Shift+A, Ctrl+z etc.).
  • textInput
    The value is an utf-8 encoded text string.
  • mousemove
    The value is a string containing the x and y coordinates, separated by comma (e.g., "x=45,y=20").
  • mousedown, mouseup
    The value is a string containing the x and y coordinates, and the button type, separated by comma (e.g., "x=45,y=20,button=0"). The button type can be: 0 for left button, 1 for middle button and 2 for right button; for mice configured for left-handed usage, the values are reversed.
  • mousewheel
    The value is a string containing the x and y coordinates, and the delta value, separated by comma (e.g., "x=45,y=20,delta=8"). The delta value is the distance the wheel has rotated around the y-axis. A positive value indicates that the wheel was rotated up (or left), while a negative indicates the opposite.
  • focusin, focusout
    The value is an empty string (i.e. "").

Subscribe command

The SUBSCRIBE command is used to subscribe for receiving notifications from the server whenever a certain Shared Variable is updated (e.g., SUBSCRIBE "var1") or an event is generated on the server (upon subscribing to the special Shared Variable "%EVENTS%" - i.e. SUBSCRIBE "%EVENTS%").

  • The clients will receive from the server either an UPDATE command (the first case) or an EVENT command (the second case). The notification always carries an absolute UTC timestamp.
  • If a Shared Variable has a value and a client subscribes to it, the client will immediately receive a notification from the server. Note that only a notification with the latest value is sent by the server regardless of the Shared Variable being updated multiple times before the moment of subscription.
  • In the case of a server reboot, all the Shared Variables are reset. The server doesn't notify the subscribed clients about this reset (so the clients are keeping the last-know value), but it will resume sending notifications as before the reboot. This is possible because the HMP clients are constantly sending connection keep-alive messages and the TCP socket connection is restored after the server reboot.

Unsubscribe command

The UNSUBSCRIBE command is used to stop receiving notifications from the server about a certain Shared Variable (e.g., UNSUBSCRIBE "var1") or the events generated on the server (i.e. UNSUBSCRIBE "%EVENTS%").

Examples

Using Telnet:

UPDATE "var1" "some value"
UPDATE 1391763640616399 "var2" "some value"
EVENT "mouseup" "x=33,y=44,button=0"
SUBSCRIBE "var2"

See also this tutorial about how to send commands to the HMP using a Telnet client.

Using PHP:

// updating a Shared Variable
function send_update( $host, $port, $name, $value ) { 
    $s = fsockopen( $host, $port ); 
    fwrite( $s, "UPDATE \"$name\" \"$value\"\r\n" ); 
    fclose( $s ); 
}

// sending a keydown event for the key 'V' with control modifier pressed
function send_copy_key( $host, $port ) {
    $s = fsockopen( $host, $port ); 
    fwrite( $s, "EVENT \"keydown\" \"Ctrl+V\"\r\n" );
    fclose( $s );
}

Note: this simplified example does not handle the escaping of control characters.

HTTP endpoints

The following endpoint are exposed:

  • GET http(s)://HMP_address:port/update?name1=value1&name2=value2...
    Updates one or more Shared Variables on the player.
  • GET http(s)://HMP_address:port/event?name1=value1&name2=value2...
    Triggers one or more events on the player.

Where:

  • port
    The port number, as configured on the Network Settings page. Usually, this is 1234.
  • update or event
    A lowercase command (as opposed to uppercase for the TCP interface) to update a Shared Variable or to trigger an event.
  • name1, name2, ...
    The Shared Variable name in case of an "update" command or the event name in case of an "event" command.
  • value1, value2, ...
    The value to which a Shared Variable is updated in case of an "update" command or the event parameters in case of an "event" command.
Note Notes:
  • The server response to the HTTP GET request is "204 No Content" and the connection is closed immediately.
  • Multiple name=value pairs can be chained using the ampersand sign (&).
  • If name or value contain special characters (e.g., "?", "=", "&" etc.), these characters must be encoded (e.g., use "%3D" for the equal sign).
  • There are no endpoints for subscribe / unsubscribe commands, thus it is not possible to get the value of a Shared Variable using this interface.
  • For a sample script using the (unprotected) "update" endpoint, see the "Shared Variable Updater" html script.

Examples

Type the following in the address bar of the browser and replace the HMP serial number or IP with the one of your HMP player.

http://spx-hmp-001d50100033:1234/update?var1=value1
http://192.168.1.10:1234/update?var1=new value 1&var2=value2
http://172.3.21.21:1234/event?mousedown=x%3D45,y%3D20,button%3D0&mouseup=x%3D45,y%3D20,button%3D0
This page was last modified on 28 October 2020, at 18:38.