Index: doc/overview.dox
===================================================================
--- doc/overview.dox	(revision 67)
+++ doc/overview.dox	(revision 68)
@@ -43,5 +43,5 @@
  * the reply, e.g. the data queried or a parameter to an error code.
  *
- * \section protodata Protocol data types
+ * \section protodata Types of protocol data elements
  *
  * The protocol's basic data elements are: 8-, 16- and 32-bit signed
@@ -63,10 +63,105 @@
  * - 90000 => 0x90 0xbf 0x05
  *
+ * \section datatypes Data type codes
+ *
+ * Each dataref of X-Plane has a certain data type, and some datarefs
+ * can represent their values in multiple data types. Because of this
+ * ambiguity and the fact that users should know the data type anyway,
+ * especially when using a strongly typed language, the type should be
+ * sent with the dataref name in commands that refer to one or more
+ * datarefs.
+ *
+ * Each data type is represented as an 8-bit unsigned integer, whose
+ * possible values are given in the table below:
+ *
+ * Data type | Value | Constant name
+ * --------- | ----: | -------------
+ * 32-bit signed integer | 0x01 | \anchor TYPE_INT TYPE_INT
+ * single-precision floating-point value | 0x02 | \anchor TYPE_FLOAT TYPE_FLOAT
+ * double-precision floating-point value | 0x03 | \anchor TYPE_DOUBLE TYPE_DOUBLE
+ * array of single-precision floating-point values | 0x11 | \anchor TYPE_FLOAT_ARRAY TYPE_FLOAT_ARRAY
+ * array of 32-bit signed integers | 0x12 | \anchor TYPE_INT_ARRAY TYPE_INT_ARRAY
+ * array of 8-bit unsigned integers (bytes) | 0x13 | \anchor TYPE_BYTE_ARRAY TYPE_BYTE_ARRAY
+ *
+ * The constant name is the name used in both client APIs to identify
+ * the given type.
+ *
+ * The scalar data types are encoded as in the following table:
+ *
+ * Data type constant | Encoding
+ * ------------------ | --------
+ * \ref TYPE_INT | a 32-bit (4-byte) signed integer
+ * \ref TYPE_FLOAT | a 32-bit (4-byte) IEEE 754 single-precision floating point value
+ * \ref TYPE_DOUBLE | a 64-bit (8-byte) IEEE 754 double-precision floating point value
+ *
+ * The contents of an array is encoded as a sequence of values of the
+ * items' type. It is usually preceded by a 32-bit signed integer
+ * denoting the number of items and sometimes also by another 32-bit
+ * signed integer denoting the offset into the array.
+ *
+ * \section resultcodes Result codes
+ *
+ * The first byte of the reply message to each command is a result
+ * code. If the command could be executed properly, it is RESULT_OK
+ * followed by the results of the command if any, otherwise it is
+ * another code signifying some error. Most error codes are followed
+ * by no further data, but \ref RESULT_UNKNOWN_DATAREF may be followed by
+ * an index if a multi-dataref request is issued.
+ *
+ * The table summarizes the error codes:
+ *
+ * Meaning | Value | Constant name
+ * ------- | ----- | -------------
+ * Success, everything is OK | 0x00 | \anchor RESULT_OK RESULT_OK
+ * Invalid command | 0x01 | \anchor RESULT_INVALID_COMMAND RESULT_INVALID_COMMAND
+ * Unknown dataref | 0x02 | \anchor RESULT_UNKNOWN_DATAREF RESULT_UNKNOWN_DATAREF
+ * Invalid data type | 0x03 | \anchor RESULT_INVALID_TYPE RESULT_INVALID_TYPE
+ * Invalid length | 0x04 | \anchor RESULT_INVALID_LENGTH RESULT_INVALID_LENGTH
+ * Invalid offset | 0x05 | \anchor RESULT_INVALID_OFFSET RESULT_INVALID_OFFSET
+ * Invalid count | 0x06 | \anchor RESULT_INVALID_COUNT RESULT_INVALID_COUNT
+ * Invalid ID | 0x07 | \anchor RESULT_INVALID_ID RESULT_INVALID_ID
+ * Invalid duration | 0x08 | \anchor RESULT_INVALID_DURATION RESULT_INVALID_DURATION
+ * Other error | 0xff | \anchor RESULT_OTHER_ERROR RESULT_OTHER_ERROR
+ *
+ * \section limits Limits
+ *
+ * Certain parameters have limits, which are summarized in the
+ * following table:
+ *
+ * Description | Limit
+ * ------- | -----
+ * maximal number of array items | 2048
+ * maximal number of datarefs in a multi-dataref operation | 1024
+ * maximal duration of a message | 5 minutes
+ * maximal number of hotkeys that can be registered | 128
+ *
  * \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)
+ * parameters and the possible replies. Each command is represented by
+ * an 8-bit unsigned value, which is the first byte of the
+ * message. The table below summarizes the commands with their command
+ * byte and constant names:
+ *
+ * Description | Command byte | Constant Name
+ * ----------- | -----------: | -------------
+ * \ref command_get_single "Query the value of a single dataref" | 0x01 | \anchor COMMAND_GET_SINGLE COMMAND_GET_SINGLE
+ * \ref command_set_single "Set the value of a single dataref" | 0x02 | \anchor COMMAND_SET_SINGLE COMMAND_SET_SINGLE
+ * \ref command_get_multi "Query the values of multiple datarefs" | 0x03 | \anchor COMMAND_GET_MULTI COMMAND_GET_MULTI
+ * \ref command_set_multi "Set the values of multiple datarefs" | 0x04 | \anchor COMMAND_SET_MULTI COMMAND_SET_MULTI
+ * \ref command_register_get_multi "Register a multi-dataref query" | 0x11 | \anchor COMMAND_REGISTER_GET_MULTI COMMAND_REGISTER_GET_MULTI
+ * \ref command_unregister_get_multi "Unregister a multi-dataref query" | 0x12 | \anchor COMMAND_UNREGISTER_GET_MULTI COMMAND_UNREGISTER_GET_MULTI
+ * \ref command_execute_get_multi "Execute a registered multi-dataref query" | 0x13 | \anchor COMMAND_EXECUTE_GET_MULTI COMMAND_EXECUTE_GET_MULTI
+ * \ref command_register_set_multi "Register a multi-dataref update request" | 0x21 | \anchor COMMAND_REGISTER_SET_MULTI COMMAND_REGISTER_SET_MULTI
+ * \ref command_unregister_set_multi "Unregister a multi-dataref update request" | 0x22 | \anchor COMMAND_UNREGISTER_SET_MULTI COMMAND_UNREGISTER_SET_MULTI
+ * \ref command_execute_set_multi "Execute a registered multi-dataref update request" | 0x23 | \anchor COMMAND_EXECUTE_SET_MULTI COMMAND_EXECUTE_SET_MULTI
+ * \ref command_get_versions "Query the versions of X-Plane, XPLM and XPLRA" | 0x31 | \anchor COMMAND_GET_VERSIONS COMMAND_GET_VERSIONS
+ * \ref command_reload_plugins "Reload the plugins in X-Plane" | 0x32 | \anchor COMMAND_RELOAD_PLUGINS COMMAND_RELOAD_PLUGINS
+ * \ref command_show_message "Show a message in X-Plane's window" | 0x41 | \anchor COMMAND_SHOW_MESSAGE COMMAND_SHOW_MESSAGE
+ * \ref command_register_hotkeys "Register hotkeys to be listened to" | 0x51 | \anchor COMMAND_REGISTER_HOTKEYS COMMAND_REGISTER_HOTKEYS
+ * \ref command_query_hotkeys "Query the sate of the registered hotkeys" | 0x52 | \anchor COMMAND_QUERY_HOTKEYS COMMAND_QUERY_HOTKEYS
+ * \ref command_unregister_hotkeys "Unregister the previously registered hotkets" | 0x53 | \anchor COMMAND_UNREGISTER_HOTKEYS COMMAND_UNREGISTER_HOTKEYS
+ *
+ * \subsection command_get_single The GET_SINGLE command
  *
  * This command can be used to query the value of a single
@@ -74,29 +169,531 @@
  * 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).
+ * The format of the command is the following:
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | 0x01 (\ref COMMAND_GET_SINGLE)
+ * dataref_query_info | information about the dataref to query
+ *
+ * \anchor dataref_query_info \c dataref_query_info has the following
+ * format for scalar types:
+ *
+ * Type | Description
+ * ---- | ------
+ * string | the name of the dataref to query
+ * byte | the type of the dataref, one of the \ref datatypes "TYPE_XXX" constants
+ *
+ * \c dataref_query_info has the following format for array types:
+ *
+ * Type | Description
+ * ---- | ------
+ * string | the name of the dataref to query
+ * byte | the type of the dataref, one of the \ref datatypes "TYPE_XXX_ARRAY" constants
+ * 32-bit signed integer | the number of items to query, -1 to query all items
+ * 32-bit signed integer | the offset of the data within the array to query
+ *
+ * If the command is executed successfully, the reply has the
+ * following format for scalar types:
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | 0x00 (\ref RESULT_OK)
+ * dataref_value | the value of the dataref
+ *
+ * \anchor dataref_value dataref_value is encoded as follows for scalar types:
+ *
+ * Type | Description
+ * ---- | ------
+ * scalar type | the value of the dataref
+ *
+ * dataref_value is encoded as follows for array types:
+ *
+ * Type | Description
+ * ---- | ------
+ * 32-bit signed integer | n=the number of items returned
+ * n*type of the items | the data items themselves
+ *
+ * In case of an error:
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | the error code
+ *
+ * The following error codes may be returned:
+ *
+ * Code | Meaning
+ * ---- | -------
+ * \ref RESULT_UNKNOWN_DATAREF | the dataref with the given name was not found
+ * \ref RESULT_INVALID_TYPE | an unknown type code was given
+ * \ref RESULT_INVALID_LENGTH | the length given for an array is too large
+ * \ref RESULT_INVALID_OFFSET | the offset given for an array is negative
+ *
+ * \subsection command_set_single The SET_SINGLE command
+ *
+ * This command can be used to set 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 format of the command is the following for scalar values:
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | 0x02 (\ref COMMAND_SET_SINGLE)
+ * dataref_update_info | information about the dataref to set and the value itself
+ *
+ * \anchor dataref_update_info \c dataref_update_info has the
+ * following format for scalar values:
+ *
+ * Type | Description
+ * ---- | ------
+ * string | the name of the dataref to set
+ * byte | the type of the dataref, one of the \ref datatypes "TYPE_XXX" constants
+ * dataref's type | the value to set
+ *
+ * \c dataref_update_info has the following format for array values:
+ *
+ * Type | Description
+ * ---- | ------
+ * string | the name of the dataref to set
+ * byte | the type of the dataref, one of the \ref datatypes "TYPE_XXX_ARRAY" constants
+ * 32-bit signed integer | n=the number of items to set
+ * 32-bit signed integer | the offset from which to set the values
+ * n*type of the items | the actual values of the array
+ *
+ * If the command is executed successfully, the reply has the
+ * following format for scalar types:
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | 0x00 (\ref RESULT_OK)
+ *
+ * If an error was encountered, the reply has the following format:
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | the error code
+ *
+ * The following error codes may be returned:
+ *
+ * Code | Meaning
+ * ---- | -------
+ * \ref RESULT_UNKNOWN_DATAREF | the dataref with the given name was not found
+ * \ref RESULT_INVALID_TYPE | an unknown type code was given
+ * \ref RESULT_INVALID_LENGTH | the length given for an array is too large or not positive
+ * \ref RESULT_INVALID_OFFSET | the offset given for an array is negative
+ *
+ * \subsection command_get_multi The GET_MULTI command
+ *
+ * This command can be used to query the values of several datarefs in
+ * one call. It is encoded as follows:
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | 0x03 (\ref COMMAND_GET_MULTI)
+ * 32-bit unsigned integer | n=the number of datarefs to query
+ * n*\ref dataref_query_info | information about the datarefs to query.
+ *
+ * In case of success, the reply is the following:
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | 0x00 (\ref RESULT_OK)
+ * n*\ref dataref_value | the values of the datarefs
+ *
+ * If an error was encountered, the reply has the following format:
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | the error code
+ * 32-bit unsigned integer | if the error code is \ref RESULT_UNKNOWN_DATAREF : the 0-based index of the first dataref that was not found
+ *
+ * The following error codes may be returned:
+ *
+ * Code | Meaning
+ * ---- | -------
+ * \ref RESULT_UNKNOWN_DATAREF | the dataref with the given name was not found
+ * \ref RESULT_INVALID_TYPE | an unknown type code was given
+ * \ref RESULT_INVALID_LENGTH | the length given for an array is too large
+ * \ref RESULT_INVALID_OFFSET | the offset given for an array is negative
+ * \ref RESULT_INVALID_COUNT | the number of datarefs was either 0 or too large
+ *
+ * \subsection command_set_multi The SET_MULTI command
+ *
+ * This command can be used to set the values of several datarefs in
+ * one call. It is encoded as follows:
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | 0x04 (\ref COMMAND_SET_MULTI)
+ * 32-bit unsigned integer | n=the number of datarefs to set
+ * n*\ref dataref_update_info | information about the datarefs to set
+ *
+ * In case of success, the reply is the following:
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | 0x00 (\ref RESULT_OK)
+ *
+ * If an error was encountered, the reply has the following format:
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | the error code
+ * 32-bit unsigned integer | if the error code is \ref RESULT_UNKNOWN_DATAREF : the 0-based index of the first dataref that was not found
+ *
+ * The following error codes may be returned:
+ *
+ * Code | Meaning
+ * ---- | -------
+ * \ref RESULT_UNKNOWN_DATAREF | the dataref with the given name was not found
+ * \ref RESULT_INVALID_TYPE | an unknown type code was given
+ * \ref RESULT_INVALID_LENGTH | the length given for an array is too large or not positive
+ * \ref RESULT_INVALID_OFFSET | the offset given for an array is negative
+ * \ref RESULT_INVALID_COUNT | the number of datarefs was either 0 or too large
+ *
+ * \subsection command_register_get_multi The REGISTER_GET_MULTI command
+ *
+ * This command can be used to register a multi-dataref query. A
+ * multi-dataref query is a list of datarefs that are queried
+ * together. The query will be associated with an identifier that can
+ * be used later to refer to the query when actually querying the
+ * values or when unregistering it. The identifier is unique only for
+ * the client connection and among the multi-dataref queries.
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | 0x11 (\ref COMMAND_REGISTER_GET_MULTI)
+ * 32-bit unsigned integer | n=the number of datarefs to query
+ * n*\ref dataref_query_info | information about the datarefs to query.
+ *
+ * In case of success, the reply is the following:
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | 0x00 (\ref RESULT_OK)
+ * 32-bit unsigned integer | the identifier of the registered query
+ *
+ * If an error was encountered, the reply has the following format:
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | the error code
+ *
+ * The following error codes may be returned:
+ *
+ * Code | Meaning
+ * ---- | -------
+ * \ref RESULT_INVALID_TYPE | an unknown type code was given
+ * \ref RESULT_INVALID_LENGTH | the length given for an array is too large
+ * \ref RESULT_INVALID_OFFSET | the offset given for an array is negative
+ * \ref RESULT_INVALID_COUNT | the number of datarefs was either 0 or too large
+ *
+ * \subsection command_unregister_get_multi The UNREGISTER_GET_MULTI command
+ *
+ * This command can be used to unregister a previously registered
+ * multi-dataref query.
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | 0x12 (\ref COMMAND_UNREGISTER_GET_MULTI)
+ * 32-bit unsigned integer | the identifier of the query to unregister
+ *
+ * In case of success, the reply is the following:
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | 0x00 (\ref RESULT_OK)
+ *
+ * If an error was encountered, the reply has the following format:
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | the error code
+ *
+ * The following error codes may be returned:
+ *
+ * Code | Meaning
+ * ---- | -------
+ * \ref RESULT_INVALID_ID | an identifier was given that is not associated with any registered query
+ *
+ * \subsection command_execute_get_multi The EXECUTE_GET_MULTI command
+ *
+ * This command can be used to execute a previously registered
+ * multi-dataref query.
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | 0x13 (\ref COMMAND_EXECUTE_GET_MULTI)
+ * 32-bit unsigned integer | the identifier of the query to execute
+ *
+ * In case of success, the reply is the following:
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | 0x00 (\ref RESULT_OK)
+ * n*\ref dataref_value | the values of the datarefs, n is the number of them
+ *
+ * If an error was encountered, the reply has the following format:
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | the error code
+ * 32-bit unsigned integer | if the error code is \ref RESULT_UNKNOWN_DATAREF : the 0-based index of the first dataref that was not found
+ *
+ * The following error codes may be returned:
+ *
+ * Code | Meaning
+ * ---- | -------
+ * \ref RESULT_UNKNOWN_DATAREF | the dataref with the given name was not found
+ * \ref RESULT_INVALID_ID | an identifier was given that is not associated with any registered query
+ *
+ * \subsection command_register_set_multi The REGISTER_SET_MULTI command
+ *
+ * This command can be used to register a multi-dataref update. A
+ * multi-dataref update is a list of datarefs that are updated
+ * together with values supplied for each update. The update will be
+ * associated with an identifier that can be used later to refer to
+ * the update when actually updating the values or when unregistering
+ * it. The identifier is unique only for  the client connection and
+ * among the multi-dataref updates.
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | 0x21 (\ref COMMAND_REGISTER_SET_MULTI)
+ * 32-bit unsigned integer | n=the number of datarefs to query
+ * n*\ref dataref_query_info | information about the datarefs to update (this \a is \ref dataref_query_info, because the format is the same, since we don't supply any values)
+ *
+ * In case of success, the reply is the following:
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | 0x00 (\ref RESULT_OK)
+ * 32-bit unsigned integer | the identifier of the registered query
+ *
+ * If an error was encountered, the reply has the following format:
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | the error code
+ *
+ * The following error codes may be returned:
+ *
+ * Code | Meaning
+ * ---- | -------
+ * \ref RESULT_INVALID_TYPE | an unknown type code was given
+ * \ref RESULT_INVALID_LENGTH | the length given for an array is too large or not positive
+ * \ref RESULT_INVALID_OFFSET | the offset given for an array is negative
+ * \ref RESULT_INVALID_COUNT | the number of datarefs was either 0 or too large
+ *
+ * \subsection command_unregister_set_multi The UNREGISTER_GET_MULTI command
+ *
+ * This command can be used to unregister a previously registered
+ * multi-dataref update.
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | 0x22 (\ref COMMAND_UNREGISTER_SET_MULTI)
+ * 32-bit unsigned integer | the identifier of the update to unregister
+ *
+ * In case of success, the reply is the following:
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | 0x00 (\ref RESULT_OK)
+ *
+ * If an error was encountered, the reply has the following format:
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | the error code
+ *
+ * The following error codes may be returned:
+ *
+ * Code | Meaning
+ * ---- | -------
+ * \ref RESULT_INVALID_ID | an identifier was given that is not associated with any registered update
+ *
+ * \subsection command_execute_set_multi The EXECUTE_SET_MULTI command
+ *
+ * This command can be used to execute a previously registered
+ * multi-dataref update.
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | 0x23 (\ref COMMAND_EXECUTE_SET_MULTI)
+ * 32-bit unsigned integer | the identifier of the update to execute
+ * n*\ref dataref_value | the values
+ *
+ * In case of success, the reply is the following:
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | 0x00 (\ref RESULT_OK)
+ *
+ * If an error was encountered, the reply has the following format:
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | the error code
+ * 32-bit unsigned integer | if the error code is \ref RESULT_UNKNOWN_DATAREF : the 0-based index of the first dataref that was not found
+ *
+ * The following error codes may be returned:
+ *
+ * Code | Meaning
+ * ---- | -------
+ * \ref RESULT_UNKNOWN_DATAREF | the dataref with the given name was not found
+ * \ref RESULT_INVALID_ID | an identifier was given that is not associated with any registered query
+ *
+ * \subsection command_get_versions The GET_VERSIONS command
+ *
+ * This command can be used to query the versions of X-Plane, XPLM and
+ * XPLRA itself.
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | 0x31 (\ref COMMAND_GET_VERSIONS)
+ *
+ * The reply is encoded the following way (it shall never fail):
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | 0x00 (\ref RESULT_OK)
+ * 32-bit signed integer | the version of X-Plane. For 10.20r1 it is 10201.
+ * 32-bit signed integer | the version of XPLM. For 2.10 it is 210.
+ * 32-bit signed integer | the version of XPLRA. For 0.1 it is 10.
+ *
+ * \subsection command_reload_plugins The RELOAD_PLUGINS command
+ *
+ * This command can be used to reload the plugins in X-Plane. This is
+ * useful for debugging.
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | 0x32 (\ref COMMAND_RELOAD_PLUGINS)
+ *
+ * The reply is encoded the following way (it shall never fail):
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | 0x00 (\ref RESULT_OK)
+ *
+ * \subsection command_get_versions The GET_VERSIONS command
+ *
+ * This command can be used to query the versions of X-Plane, XPLM and
+ * XPLRA itself.
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | 0x31 (\ref COMMAND_GET_VERSIONS)
+ *
+ * The reply is encoded the following way (it shall never fail):
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | 0x00 (\ref RESULT_OK)
+ * 32-bit signed integer | the version of X-Plane. For 10.20r1 it is 10201.
+ * 32-bit signed integer | the version of XPLM. For 2.10 it is 210.
+ * 32-bit signed integer | the version of XPLRA. For 0.1 it is 10.
+ *
+ * \subsection command_show_message The SHOW_MESSAGE command
+ *
+ * This command can be used to show a message in a window to the
+ * user. The window is a single line window around the top 1/3rd of
+ * the screen. It can be moved and resized by mouse actions. If a
+ * message is being displayed when this command is issued, that
+ * message will be replaced by the new one.
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | 0x41 (\ref COMMAND_SHOW_MESSAGE)
+ * string | the message to show
+ * float | the duration of the message in seconds
+ *
+ * If successful, the reply is the following:
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | 0x00 (\ref RESULT_OK)
+ *
+ * If an error was encountered, the reply has the following format:
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | the error code
+ *
+ * The following error codes may be returned:
+ *
+ * Code | Meaning
+ * ---- | -------
+ * \ref RESULT_INVALID_DURATION | the duration is too large
+ *
+ * \subsection command_register_hotkeys The REGISTER_HOTKEYS command
+ *
+ * This command can be used to register a set of hotkeys to be
+ * monitored. If any other hotkeys have been registered by the current
+ * client previously, they are forgotten.
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | 0x51 (\ref COMMAND_REGISTER_HOTKEYS)
+ * 32-bit unsigned integer | n=the number of the hotkeys
+ * n * 16-bit unsigned integer | the codes of the hotkeys
+ *
+ * The lower-byte of a hotkey code is the same as the X-Plane virtual
+ * key code. The upper byte is a logical OR of zero or more modifiers:
+ *
+ * Value | Description | Constant name
+ * --: | --- | ---
+ * 0x0100 | Shift modifier | HOTKEY_MODIFIER_SHIFT
+ * 0x0200 | Control modifier | HOTKEY_MODIFIER_CONTROL
+ *
+ * If successful, the reply is the following:
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | 0x00 (\ref RESULT_OK)
+ *
+ * If an error was encountered, the reply has the following format:
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | the error code
+ *
+ * The following error codes may be returned:
+ *
+ * Code | Meaning
+ * ---- | -------
+ * \ref RESULT_INVALID_LENGTH | too many hotkeys were given
+ *
+ * \subsection command_query_hotkeys The QUERY_HOTKEYS command
+ *
+ * This command can be used to query which hotkeys have been pressed
+ * since the last query.
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | 0x52 (\ref COMMAND_QUERY_HOTKEYS)
+ *
+ * The reply is the following:
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | 0x00 (\ref RESULT_OK)
+ * 32-bit unsigned integer | n = the number of hotkeys registered
+ * n * 8-bit unsigned integer | each byte is 0 or 1 depending whether the corresponding hotkeys was pressed or not. The value at index i corresponds to the hotkey code at index i in the array passed with \ref command_register_hotkeys "COMMAND_REGISTER_HOTKEYS"
+ *
+ * \subsection command_unregister_hotkeys The UNREGISTER_HOTKEYS command
+ *
+ * This command can be used to unregister a previously registered set
+ * of hotkeys to be  monitored.
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | 0x53 (\ref COMMAND_UNREGISTER_HOTKEYS)
+ *
+ * The reply is the following:
+ *
+ * Type | Description
+ * ---- | ------
+ * byte | 0x00 (\ref RESULT_OK)
  */
