/*! \mainpage X-Plane Remote Access Plugin and Client Library Documentation
 *
 * \section intro Introduction
 *
 * The X-Plane Remote Access (XPLRA) plugin provides a gateway to external
 * applications to access some internals of X-Plane. This document
 * describes the plugin and its usage. It is assumed that the reader
 * is somewhat familiar with the X-Plane plugin SDK. The plugin
 * currently works on Linux and Windows, but porting to Mac should be
 * easy. If you would volunteer, let me know! :)
 *
 * The XPLRA plugin allows the extern applications to perform the
 * following:
 * - Get and set the values of datarefs either individually or in
 *   batch. Batches can also be pre-registered in case the same set of
 *   datarefs is to be queried or modified several times. This avoids
 *   having to send and resolve the dataref names every time.
 * - Query the versions of X-Plane, XPLM (the plugin manager) and
 *   XPLRA.
 * - Show a message in a window for the pilot for a specified amount
 *   of time.
 * - Register and then monitor hotkeys.
 *
 * Currently the plugin can be accessed locally, i.e. from the same
 * computer that runs X-Plane, but extending it with TCP/IP-based or
 * network access would not be difficult. While client libraries are
 * provided for C, C++ and Python, the communication protocol between
 * clients and the plugin is open and is \ref proto "described" in
 * this documentation. So you can write your own client, if you wish.
 */
/*! \page proto Protocol
 *
 * On Linux a Unix stream socket is created with the name
 * \c /tmp/xplra-\<user name\>, where \c \<user name\> is the login
 * account name of the user running X-Plane. On Windows a named pipe
 * is created with the name \c \\\\\.\\pipe\\xplra. The usual methods
 * provided by the OS can be used to connect to these.
 *
 * The protocol is a binary protocol. The client initiates commands
 * which are executed by the plugin. Each command is a byte followed
 * by the arguments of the command. The plugin responds with a result
 * code, which is also a byte, which may be followed by the rest of
 * the reply, e.g. the data queried or a parameter to an error code.
 *
 * \section protodata Protocol data types
 *
 * The protocol's basic data elements are: 8-, 16- and 32-bit signed
 * and unsigned integers, single and double precision floating point
 * values and strings. The endianness of the values is that of the
 * host operating system.

 * Strings are encoded as a variable-length length followed by as many
 * bytes making up the actual contents of the string. The
 * variable-length length consists of bytes whose most-significant bit
 * is 1, if there is another byte and 0 for the last byte. The first
 * byte contains the least significant 7 bits of the length, the
 * second byte contains bits 7-13, and so on. Some examples:
 * - 12 => 0x0c
 * - 123 => 0x7b
 * - 128 => 0x80 0x01
 * - 210 => 0xd2 0x01
 * - 7345 => 0xb1 0x39
 * - 90000 => 0x90 0xbf 0x05
 *
 * \section commands Commands
 *
 * This section describes the commands of the protocol with their
 * parameters and the possible replies.
 *
 * \subsection command_get_single The GET_SINGLE command (0x01)
 *
 * This command can be used to query the value of a single
 * dataref. Such a data can either be a scalar (integer, float or
 * double) or an array of floats, integers or bytes.
 *
 * The command byte  is followed by the following data:
 * - the name of the dataref to query (string)
 * - the type of the dataref (8-bit unsigned, one of the \c TYPE_XXX
 * constants). If the type is an array:
 * - the length of the data to query (32-bit signed integer, -1 to use
 * the full length of the data)
 * - the offset of the data to query (32-bit signed integer)
 *
 * The reply consists of the following:
 * - the result code (8-bit unsigned, one of the \c RESULT_XXX constants)
 *
 * If the result code is \ref RESULT_OK, it is followed by the value.
 *
 * For scalars it is:
 * - the value of the dataref:
 *   - a 32-bit signed integer for an integer,
 *   - a 32-bit single-precision floating point value for a float, or
 *   - a 64-bit double-precision floating point value for a double.
 *
 * For arrays it is:
 * - the number of items in the array (32-bit signed integer)
 * - the data items making up the array:
 *   - 32-bit single-precision floating point values for a float array,
 *   - 32-bit signed integer values for an integer array, or
 *   - 8-bit unsigned integer values for a byte array (or as you want
 *     to interpret it).
 */