Drivers/Braille/Virtual/README - brltty - Git at Google

 The Virtual Braille Display Driver
 ----------------------------------

 This is a virtual braille display driver for BRLTTY.  It uses a simple
 text-based protocol over a socket to transmit information to, and to receive
 information from, the virtual braille display application (from now on, "the
 display"). The intention of this driver is two-fold:
  * Give interested developers the ability to test BRLTTY without requiring
    access to a real braille display.
  * Enable the implementation of a visual braille display based on this driver
    which allows a sighted person to see, and even to experience, how a blind
    person uses a braille display to work with a computer.

 This driver supports the following devices:
    client:[address]
       The driver periodically tries to connect to the display at the specified
       network address.
    server:[address]
       The driver waits on the specified network address for a connection
       request from the display.

 If the network address isn't specified then the driver's default TCP/IP port on
 the local host is used. The address may be:
    On Unix systems: /path/to/unix-socket-file
       If the address starts with a slash (/) then it's interpreted as the path
       to a Unix socket file. If the driver is the client then the socket file
       must already exist. If the driver is the server then the socket file is
       created by the driver and must not already exist.
    On Windows NT/2000/XP/2003 systems: \\.\pipe\pipename
       If the address starts with a backslash (\) then it's interpreted as the
       path to a named pipe. If the driver is the client, then the named pipe
       must already exist. If the driver is the server then the named pipe is
       created by the driver and must not already exist. Beware of the shell's
       interpretation of backslashes.
    On all systems: [host][:[port]]
       A TCP/IP address. Both the host and port components of the address are
       optional. The delimiting colon (:) is only required if the port is being
       specified. The host may be a name, an alias, or an IPV4 address (in
       dotted-decimal form); if it's omitted then the local host is assumed. The
       port may be a service name or a port number; if it's omitted then 35752
       is assumed.


 The Protocol
 ------------

 After the connection between the driver and the display is complete, data is
 exchanged between them via command lines. The driver first waits for a "cells"
 command in order to determine the dimensions of the braille window. After this
 has been taken care of, commands freely flow in both directions without any
 restrictions. The braille window dimensions are appropriately reconfigured
 whenever another "cells" command is received. The "quit" command, which is also
 recognized during the initial wait for the first "cells" command, instructs the
 driver to close its end of the connection and to restart.

 The command lines are in plain text. Each is terminated by a line-feed [0X0A]
 (usually known on Unix systems as a new-line). A carriage-return [0X0D] may
 optionally precede the line-feed. Command lines sent to the display contain a
 carriage-return if, and only if, the most recent command line received from the
 display contained one.

 Command lines are composed of space-delimited words, numbers, and strings.
 Space consists of one or more blanks and/or tabs. Case is only significant
 within a string.

 A "number" may be specified as decimal, octal, or hexadecimal. The usual C
 syntax is recognized. If the first digit is 0 then the number is octal. If the
 first digit isn't 0 then the number is decimal. If the number begins with
 either 0X or 0x then the number is hexadecimal. The following three numbers are
 the same:
    15   Decimal
    017  Octal
    0XF  Hexadecimal

 A "string" is a sequence of characters (including space characters) enclosed
 within double quotes ("). Special characters within a string are prefixed with
 a backslash (\). The following special characters are supported:
    \\   A literal backslash.
    \"   A literal double quote.
    \Xxx Any character specified via its hexadecimal value.
 For example: "A \" (double quote) must be escaped with a \\ (backslash)."

 A "dots" is a string which describes a braille character sequence. Space
 (blanks and/or tabs) within the string are ignored. The braille characters are
 separated from one another by a vertical bar (|). Each braille character
 consists of the numbers (1 through 8) of the dots which represent it. For
 example, the first three letters of the English alphabet would be "1|12|14".


 Commands Recognized by the Driver
 ---------------------------------

 Cells columns [rows]
    The number of columns and rows in the text portion of the display. If the
    number of rows isn't supplied then 1 is assumed. This is the first command
    which the display must send to the driver. It may be sent at any other time
    as well to notify the driver that the dimensions of the text portion of the
    display have changed.

 Quit
    Upon receipt of this command, the driver closes its end of the connection
    and then restarts. It's recognized at any time, including during the initial
    wait for the first "cells" command from the display.

 <basic-command> [state]
    A basic command for the BRLTTY core. It may be any of the BRL_CMD_ constants
    (without the BRL_CMD_ prefix) defined within "brldefs.h", e.g. LnDn. The
    optional <state> operand (which may be either on or off), when applied to an
    attribute toggling command, forces that attribute to the specified state.

 <cell-command> number
    A cell command for the BRLTTY core. It may be any of the BRL_BLK_ constants
    (without the BRL_BLK_ prefix) defined within "brldefs.h", e.g. Route. The cell
    number, starting at 1 for the leftmost cell, must be supplied. If the
    display has more than one row then the cells for the top row are counted
    first, e.g. if the display has 32 columns and 2 rows then 35 refers to the
    third cell on the second row.

 <key-command> [number]
    A key command for the BRLTTY core. It may be any of the VPK_ constants
    (without the VPK_ prefix) defined within "brldefs.h", e.g. Return. The
    Function command requires that the function key number, starting at 1, be
    supplied. All the other commands in this set don't accept a number operand.


 Commands Sent to the Display
 ----------------------------

 Braille dots
    Cells to be presented on the text portion of the display. Excess cells in
    the data should be ignored. Excess cells on the display should be blank.

 Visual string
    Characters to be presented on the visual portion of the display. Excess
    characters in the data should be ignored. Excess characters on the display
    should be blank.

 Status dots
    Cells to be presented on the status portion of the display. Excess cells in
    the data should be ignored. Excess cells on the display should be blank.

 <attribute> <setting>
    The current setting of any of several attributes within the BRLTTY core.
    These are only sent if "Status Style" is set to "Generic". <attribute> is
    the name of any of the STAT_ constants (without the STAT_ prefix) defined
    within "brldefs.h", e.g. BrlRow. <setting> is a number. Rows and columns
    start at 1. Flags use 0 for "off" and 1 for "on".


 Security Implications
 ---------------------

 Please be aware that this driver, when used carelessly, might open severe
 security holes. Connections to or from this driver are in no way authenticated
 so you yourself need to take care of protecting access to a BRLTTY instance
 which uses it. In particular, by sending out information about the currently
 active virtual console, this driver might expose valuable information about
 your system to a potential attacker. The attacker might also use the
 <key-command> family of commands to directly manipulate, possibly even
 inputting data to, your current, or even another, virtual console. In effect,
 this driver could be used to completely remote-control your system.

 Please be aware of these implications when experimenting with this driver. If
 you're using TCP/IP, be sure to protect access to the used host and port via
 facilities such as firewalls. You should take special precautions on multi-user
 systems where untrusted people could use unprotected access to this driver to
 gain root access to the machine.


  -- Mario Lang <mlang@delysid.org>
	The Virtual Braille Display Driver
	----------------------------------

	This is a virtual braille display driver for BRLTTY. It uses a simple
	text-based protocol over a socket to transmit information to, and to receive
	information from, the virtual braille display application (from now on, "the
	display"). The intention of this driver is two-fold:
	* Give interested developers the ability to test BRLTTY without requiring
	access to a real braille display.
	* Enable the implementation of a visual braille display based on this driver
	which allows a sighted person to see, and even to experience, how a blind
	person uses a braille display to work with a computer.

	This driver supports the following devices:
	client:[address]
	The driver periodically tries to connect to the display at the specified
	network address.
	server:[address]
	The driver waits on the specified network address for a connection
	request from the display.

	If the network address isn't specified then the driver's default TCP/IP port on
	the local host is used. The address may be:
	On Unix systems: /path/to/unix-socket-file
	If the address starts with a slash (/) then it's interpreted as the path
	to a Unix socket file. If the driver is the client then the socket file
	must already exist. If the driver is the server then the socket file is
	created by the driver and must not already exist.
	On Windows NT/2000/XP/2003 systems: \\.\pipe\pipename
	If the address starts with a backslash (\) then it's interpreted as the
	path to a named pipe. If the driver is the client, then the named pipe
	must already exist. If the driver is the server then the named pipe is
	created by the driver and must not already exist. Beware of the shell's
	interpretation of backslashes.
	On all systems: [host][:[port]]
	A TCP/IP address. Both the host and port components of the address are
	optional. The delimiting colon (:) is only required if the port is being
	specified. The host may be a name, an alias, or an IPV4 address (in
	dotted-decimal form); if it's omitted then the local host is assumed. The
	port may be a service name or a port number; if it's omitted then 35752
	is assumed.


	The Protocol
	------------

	After the connection between the driver and the display is complete, data is
	exchanged between them via command lines. The driver first waits for a "cells"
	command in order to determine the dimensions of the braille window. After this
	has been taken care of, commands freely flow in both directions without any
	restrictions. The braille window dimensions are appropriately reconfigured
	whenever another "cells" command is received. The "quit" command, which is also
	recognized during the initial wait for the first "cells" command, instructs the
	driver to close its end of the connection and to restart.

	The command lines are in plain text. Each is terminated by a line-feed [0X0A]
	(usually known on Unix systems as a new-line). A carriage-return [0X0D] may
	optionally precede the line-feed. Command lines sent to the display contain a
	carriage-return if, and only if, the most recent command line received from the
	display contained one.

	Command lines are composed of space-delimited words, numbers, and strings.
	Space consists of one or more blanks and/or tabs. Case is only significant
	within a string.

	A "number" may be specified as decimal, octal, or hexadecimal. The usual C
	syntax is recognized. If the first digit is 0 then the number is octal. If the
	first digit isn't 0 then the number is decimal. If the number begins with
	either 0X or 0x then the number is hexadecimal. The following three numbers are
	the same:
	15 Decimal
	017 Octal
	0XF Hexadecimal

	A "string" is a sequence of characters (including space characters) enclosed
	within double quotes ("). Special characters within a string are prefixed with
	a backslash (\). The following special characters are supported:
	\\ A literal backslash.
	\" A literal double quote.
	\Xxx Any character specified via its hexadecimal value.
	For example: "A \" (double quote) must be escaped with a \\ (backslash)."

	A "dots" is a string which describes a braille character sequence. Space
	(blanks and/or tabs) within the string are ignored. The braille characters are
	separated from one another by a vertical bar (\|). Each braille character
	consists of the numbers (1 through 8) of the dots which represent it. For
	example, the first three letters of the English alphabet would be "1\|12\|14".


	Commands Recognized by the Driver
	---------------------------------

	Cells columns [rows]
	The number of columns and rows in the text portion of the display. If the
	number of rows isn't supplied then 1 is assumed. This is the first command
	which the display must send to the driver. It may be sent at any other time
	as well to notify the driver that the dimensions of the text portion of the
	display have changed.

	Quit
	Upon receipt of this command, the driver closes its end of the connection
	and then restarts. It's recognized at any time, including during the initial
	wait for the first "cells" command from the display.

	<basic-command> [state]
	A basic command for the BRLTTY core. It may be any of the BRL_CMD_ constants
	(without the BRL_CMD_ prefix) defined within "brldefs.h", e.g. LnDn. The
	optional <state> operand (which may be either on or off), when applied to an
	attribute toggling command, forces that attribute to the specified state.

	<cell-command> number
	A cell command for the BRLTTY core. It may be any of the BRL_BLK_ constants
	(without the BRL_BLK_ prefix) defined within "brldefs.h", e.g. Route. The cell
	number, starting at 1 for the leftmost cell, must be supplied. If the
	display has more than one row then the cells for the top row are counted
	first, e.g. if the display has 32 columns and 2 rows then 35 refers to the
	third cell on the second row.

	<key-command> [number]
	A key command for the BRLTTY core. It may be any of the VPK_ constants
	(without the VPK_ prefix) defined within "brldefs.h", e.g. Return. The
	Function command requires that the function key number, starting at 1, be
	supplied. All the other commands in this set don't accept a number operand.


	Commands Sent to the Display
	----------------------------

	Braille dots
	Cells to be presented on the text portion of the display. Excess cells in
	the data should be ignored. Excess cells on the display should be blank.

	Visual string
	Characters to be presented on the visual portion of the display. Excess
	characters in the data should be ignored. Excess characters on the display
	should be blank.

	Status dots
	Cells to be presented on the status portion of the display. Excess cells in
	the data should be ignored. Excess cells on the display should be blank.

	<attribute> <setting>
	The current setting of any of several attributes within the BRLTTY core.
	These are only sent if "Status Style" is set to "Generic". <attribute> is
	the name of any of the STAT_ constants (without the STAT_ prefix) defined
	within "brldefs.h", e.g. BrlRow. <setting> is a number. Rows and columns
	start at 1. Flags use 0 for "off" and 1 for "on".


	Security Implications
	---------------------

	Please be aware that this driver, when used carelessly, might open severe
	security holes. Connections to or from this driver are in no way authenticated
	so you yourself need to take care of protecting access to a BRLTTY instance
	which uses it. In particular, by sending out information about the currently
	active virtual console, this driver might expose valuable information about
	your system to a potential attacker. The attacker might also use the
	<key-command> family of commands to directly manipulate, possibly even
	inputting data to, your current, or even another, virtual console. In effect,
	this driver could be used to completely remote-control your system.

	Please be aware of these implications when experimenting with this driver. If
	you're using TCP/IP, be sure to protect access to the used host and port via
	facilities such as firewalls. You should take special precautions on multi-user
	systems where untrusted people could use unprotected access to this driver to
	gain root access to the machine.


	-- Mario Lang <mlang@delysid.org>