Network.registerForEscapeSequence()

Overview

Registers an escape sequence handler. When the escape sequence is sent from the host, the handler processes it and may modify it or remove it from the host's data stream. If the escape sequence has parameters, use the terminator to describe where the parameters end. If the escape sequence does not have parameters, the terminator can be null.

All byte sequences used in this API are byte arrays encoded as strings. Each character in the string represents a byte value and should be between '\x00' and '\xff'.

Added in version 2.0.0

Format

var resultCallback = function(foundSequence) { /*...*/ };
var sequenceToken = Network.registerForEscapeSequence(introducer, terminator, extendedParameter, resultCallback);

Parameter	Description	Type	Required
introducer	Describes the incoming byte values that will initiate the escape sequence.	String	Required
terminator	Describes the terminating byte values that terminate the escape sequence if parameters are included. If null or undefined, no parameters will be found.	String	May be null or undefined
extendedParameter	Specifies whether the escape sequence parameters are normal characters or extended characters. The parameters follow the introducer and continue until the terminator. Use false if the parameters include characters between 0x20 and 0x3f inclusive. Use true if the parameters include characters between 0x20 and 0x7f inclusive.	Boolean	Required
resultCallback	A callback used when the complete escape sequence is found in the host's data stream. The return value from this function is used as a replacement for the sequence. If no return value is given or the return value is null then the sequence will be removed from the data stream.	Function	Required
foundSequence	Describes the complete sequence received including any parameters bytes. This is a parameter for resultCallback.	String	Parameter
sequenceToken	Returns an opaque object that represents the registered escape sequence. Returns null if registration failed. Return object can be used to deregister for an escape sequence.	Object	Return

Example 1

Copy

/* Registers for all Select Graphic Rendition (SGR) escape sequences.
 * Replaces all incoming requests for attributes with a reset all attributes.
 */
function onSGR(sequence) {
  return '\x1b[0m';
}
Network.registerForEscapeSequence('\x1b[', 'm', false, onSGR);

Example 2

Copy

/* Registers for special escape sequence to play warning sound.
 */
function onWarn(sequence) {
  Device.beepPlayFile("warn.wav");
}
Network.registerForEscapeSequence('\x1b@', null, false, onWarn);

Example 3

Copy

/* Play a sound specified in the escape sequence.
 */
function doSound(sequence) {
  Device.beepPlayFile(sequence.slice(6,-2));
}
Network.registerForEscapeSequence('\x1bXWAV:', '\x1b\\', true, doSound);