Shared Variables legacy server

 

This article is a stub. Main article: Shared Variables.

 

Applies to all players, except HMP300 and DiVA.

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:

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.

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.

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