/*! \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 \ref cppapi "C, C++" and \ref pythonapi "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 library, if you wish. */ /*! \page proto Protocol * * On Linux a Unix stream socket is created with the name * \c /tmp/xplra-\, where \c \ 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 Types of protocol data elements * * 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 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. 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 * 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: * * 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) */ /*! \page cppapi C/C++ Client API * * The C++ client API's central class is \ref * hu::varadiistvan::xplra::XPlane. To communicate with the XPLRA * plugin in X-Plane, create an instance of it. This, however, does * not establish the connection yet. To actually connect, call the * \ref hu::varadiistvan::xplra::XPlane::connect "connect" member * function. If the connection is established, it returns otherwise it * throws a \ref hu::varadiistvan::xplra::IOException. * * \c IOException is part of the exception hierarchy of the client * API. The hierarchy begins with \ref * hu::varadiistvan::xplra::Exception. The \c what function is * implemented for all exception classes, so you can always get a * string representation of the problem for logging or to display * it. \c IOException further makes available an error code, which is * the standard operating system-specific fault code of the I/O error * that occured. * * \ref hu::varadiistvan::xplra::ProtocolException is thrown for * errors returned by the plugin usually due to some incorrect * parameter. See also the \ref proto description for the meaning * and applicability of these error codes. * * The \c XPlane object can be reused in the sense, that after you * have made a connection, you can disconnect and then connect * again. This may be useful, if X-Plane crashes for some reason, and * you can then reconnect if the user has restarted it. * * The \ref hu::varadiistvan::xplra::XPlane::createMultiGetter * "createMultiGetter" function can be used to create a multi-dataref * query object. It returns an instance of * \ref hu::varadiistvan::xplra::MultiGetter "MultiGetter", which can * be used to store a number of datarefs and then execute a * multi-dataref query for those datarefs. Before execution, the query * can be \ref hu::varadiistvan::xplra::MultiBuffer::registerInXPlane * "registered" in the plugin, so that the client does not have to send * all the dataref information whenever the query is executed. * * The \c XPlane object knows about any multi-dataref query objects. * Therefore if you register such a multi-dataref query, and then the * connection breaks, and then you reconnect, the query will-be * re-registered too, i.e. you don't have to do it yourself. * * Similarly, the \ref hu::varadiistvan::xplra::XPlane::createMultiSetter * "createMultiSetter" function can be used to create a multi-dataref * update object. They are handled the same way by \c XPlane as the * query objects when it comes to registration and re-registration. * * The other functions of \c XPlane are mostly self-explanatory: they * perform the operations defined by the protocol. Several operations * have more than one corresponding functions with different * parameters for convenience. * * The \ref src/client/c/hu/varadiistvan/xplra/xplra.h "C API" is * a wrapper over the C++ one, so its logic is essentially the * same. To connect to X-Plane, call \ref xplra_connect. It returns a * non-negative handle, which can be used to refer to the connection * (i.e. the underlying \c XPlane object) in the other functions. * * In case of error, it, and most other functions of the C returns * -1. To check what the last error was, call \ref * xplra_get_last_error or \ref xplra_get_last_error_string. * * You can create multi-dataref buffers with C API as well with * \ref xplra_multi_create_getter and \ref * xplra_multi_create_setter. These return a buffer ID on success, and * you should use that buffer ID later on to manipulate the buffer. */ /*! \page pythonapi Python Client API * */