| 1 | /*! \mainpage X-Plane Remote Access Plugin and Client Library Documentation
|
|---|
| 2 | *
|
|---|
| 3 | * \section intro Introduction
|
|---|
| 4 | *
|
|---|
| 5 | * The X-Plane Remote Access (XPLRA) plugin provides a gateway to external
|
|---|
| 6 | * applications to access some internals of X-Plane. This document
|
|---|
| 7 | * describes the plugin and its usage. It is assumed that the reader
|
|---|
| 8 | * is somewhat familiar with the X-Plane plugin SDK. The plugin
|
|---|
| 9 | * currently works on Linux and Windows, but porting to Mac should be
|
|---|
| 10 | * easy. If you would volunteer, let me know! :)
|
|---|
| 11 | *
|
|---|
| 12 | * The XPLRA plugin allows the extern applications to perform the
|
|---|
| 13 | * following:
|
|---|
| 14 | * - Get and set the values of datarefs either individually or in
|
|---|
| 15 | * batch. Batches can also be pre-registered in case the same set of
|
|---|
| 16 | * datarefs is to be queried or modified several times. This avoids
|
|---|
| 17 | * having to send and resolve the dataref names every time.
|
|---|
| 18 | * - Query the versions of X-Plane, XPLM (the plugin manager) and
|
|---|
| 19 | * XPLRA.
|
|---|
| 20 | * - Show a message in a window for the pilot for a specified amount
|
|---|
| 21 | * of time.
|
|---|
| 22 | * - Register and then monitor hotkeys.
|
|---|
| 23 | *
|
|---|
| 24 | * Currently the plugin can be accessed locally, i.e. from the same
|
|---|
| 25 | * computer that runs X-Plane, but extending it with TCP/IP-based or
|
|---|
| 26 | * network access would not be difficult. While client libraries are
|
|---|
| 27 | * provided for C, C++ and Python, the communication protocol between
|
|---|
| 28 | * clients and the plugin is open and is \ref proto "described" in
|
|---|
| 29 | * this documentation. So you can write your own client, if you wish.
|
|---|
| 30 | */
|
|---|
| 31 | /*! \page proto Protocol
|
|---|
| 32 | *
|
|---|
| 33 | * On Linux a Unix stream socket is created with the name
|
|---|
| 34 | * \c /tmp/xplra-\<user name\>, where \c \<user name\> is the login
|
|---|
| 35 | * account name of the user running X-Plane. On Windows a named pipe
|
|---|
| 36 | * is created with the name \c \\\\\.\\pipe\\xplra. The usual methods
|
|---|
| 37 | * provided by the OS can be used to connect to these.
|
|---|
| 38 | *
|
|---|
| 39 | * The protocol is a binary protocol. The client initiates commands
|
|---|
| 40 | * which are executed by the plugin. Each command is a byte followed
|
|---|
| 41 | * by the arguments of the command. The plugin responds with a result
|
|---|
| 42 | * code, which is also a byte, which may be followed by the rest of
|
|---|
| 43 | * the reply, e.g. the data queried or a parameter to an error code.
|
|---|
| 44 | *
|
|---|
| 45 | * \section protodata Protocol data types
|
|---|
| 46 | *
|
|---|
| 47 | * The protocol's basic data elements are: 8-, 16- and 32-bit signed
|
|---|
| 48 | * and unsigned integers, single and double precision floating point
|
|---|
| 49 | * values and strings. The endianness of the values is that of the
|
|---|
| 50 | * host operating system.
|
|---|
| 51 |
|
|---|
| 52 | * Strings are encoded as a variable-length length followed by as many
|
|---|
| 53 | * bytes making up the actual contents of the string. The
|
|---|
| 54 | * variable-length length consists of bytes whose most-significant bit
|
|---|
| 55 | * is 1, if there is another byte and 0 for the last byte. The first
|
|---|
| 56 | * byte contains the least significant 7 bits of the length, the
|
|---|
| 57 | * second byte contains bits 7-13, and so on. Some examples:
|
|---|
| 58 | * - 12 => 0x0c
|
|---|
| 59 | * - 123 => 0x7b
|
|---|
| 60 | * - 128 => 0x80 0x01
|
|---|
| 61 | * - 210 => 0xd2 0x01
|
|---|
| 62 | * - 7345 => 0xb1 0x39
|
|---|
| 63 | * - 90000 => 0x90 0xbf 0x05
|
|---|
| 64 | *
|
|---|
| 65 | * \section commands Commands
|
|---|
| 66 | *
|
|---|
| 67 | * This section describes the commands of the protocol with their
|
|---|
| 68 | * parameters and the possible replies.
|
|---|
| 69 | *
|
|---|
| 70 | * \subsection command_get_single The GET_SINGLE command (0x01)
|
|---|
| 71 | *
|
|---|
| 72 | * This command can be used to query the value of a single
|
|---|
| 73 | * dataref. Such a data can either be a scalar (integer, float or
|
|---|
| 74 | * double) or an array of floats, integers or bytes.
|
|---|
| 75 | *
|
|---|
| 76 | * The command byte is followed by the following data:
|
|---|
| 77 | * - the name of the dataref to query (string)
|
|---|
| 78 | * - the type of the dataref (8-bit unsigned, one of the \c TYPE_XXX
|
|---|
| 79 | * constants). If the type is an array:
|
|---|
| 80 | * - the length of the data to query (32-bit signed integer, -1 to use
|
|---|
| 81 | * the full length of the data)
|
|---|
| 82 | * - the offset of the data to query (32-bit signed integer)
|
|---|
| 83 | *
|
|---|
| 84 | * The reply consists of the following:
|
|---|
| 85 | * - the result code (8-bit unsigned, one of the \c RESULT_XXX constants)
|
|---|
| 86 | *
|
|---|
| 87 | * If the result code is \ref RESULT_OK, it is followed by the value.
|
|---|
| 88 | *
|
|---|
| 89 | * For scalars it is:
|
|---|
| 90 | * - the value of the dataref:
|
|---|
| 91 | * - a 32-bit signed integer for an integer,
|
|---|
| 92 | * - a 32-bit single-precision floating point value for a float, or
|
|---|
| 93 | * - a 64-bit double-precision floating point value for a double.
|
|---|
| 94 | *
|
|---|
| 95 | * For arrays it is:
|
|---|
| 96 | * - the number of items in the array (32-bit signed integer)
|
|---|
| 97 | * - the data items making up the array:
|
|---|
| 98 | * - 32-bit single-precision floating point values for a float array,
|
|---|
| 99 | * - 32-bit signed integer values for an integer array, or
|
|---|
| 100 | * - 8-bit unsigned integer values for a byte array (or as you want
|
|---|
| 101 | * to interpret it).
|
|---|
| 102 | */
|
|---|
