/* Copyright (c) 2013 by István Váradi * * This file is part of XPLRA, a remote-access plugin for X-Plane * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions are met: * * 1. Redistributions of source code must retain the above copyright notice, this * list of conditions and the following disclaimer. * 2. Redistributions in binary form must reproduce the above copyright notice, * this list of conditions and the following disclaimer in the documentation * and/or other materials provided with the distribution. * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. * * The views and conclusions contained in the software and documentation are those * of the authors and should not be interpreted as representing official policies, * either expressed or implied, of the FreeBSD Project. */ #ifndef HU_VARADIISTVAN_XPLRA_XPLRA_H #define HU_VARADIISTVAN_XPLRA_XPLRA_H /*----------------------------------------------------------------------------*/ #include #include /*----------------------------------------------------------------------------*/ #ifdef __cplusplus extern "C" { #endif /*----------------------------------------------------------------------------*/ /** No error occured */ #define ERROR_NONE 0 /** * An I/O error has occured. The subcode is the errno value on Linux, or the * Windows error code. */ #define ERROR_IO 1 /** * A protocol error has occured. The subcode is one of the * ERROR_PROTOCOL_XXX values. */ #define ERROR_PROTOCOL 2 /** Invalid command was passed to the plugin */ #define ERROR_PROTOCOL_INVALID_COMMAND = 1 /** An unknown dataref was specified */ #define ERROR_PROTOCOL_UNKNOWN_DATAREF = 2 /** An invalid type was specified */ #define ERROR_PROTOCOL_INVALID_TYPE = 3 /** An invalid length was specified */ #define ERROR_PROTOCOL_INVALID_LENGTH = 4 /** An invalid offset was specified */ #define ERROR_PROTOCOL_INVALID_OFFSET = 5 /** An invalid count was specified */ #define ERROR_PROTOCOL_INVALID_COUNT = 6 /** An invalid ID was specified */ #define ERROR_PROTOCOL_INVALID_ID = 7 /** An invalid duration was specified */ #define ERROR_PROTOCOL_INVALID_DURATION = 8 /** Other protocol error */ #define ERROR_PROTOCOL_OTHER = 255 /** A function requiring a connection is called without a connection */ #define ERROR_NOT_CONNECTED 3 /** A type-specific function was called for a dataref of a different type */ #define ERROR_TYPE_MISMATCH 4 /** An invalid ID was passed to a function */ #define ERROR_INVALID_ID 5 /** Some other error */ #define ERROR_OTHER 255 /*----------------------------------------------------------------------------*/ /** Hotkey modifier: Shift */ #define HOTKEY_MODIFIER_SHIFT 0x01 /** Hotkey modifier: Control */ #define HOTKEY_MODIFIER_CONTROL 0x02 /*----------------------------------------------------------------------------*/ #define INVALID_DATAREF_ID ((size_t)-1) /*----------------------------------------------------------------------------*/ /** * Get the last error code with the subcode. * * @return the last error code, or -1 if the given connection ID is invalid. */ int xplra_get_last_error(int connectionID, unsigned long* subCode); /** * Get a string representation of the last error. * * @return the string representation of the last error, or 0 if there * was no last error, or the connection ID is invalid. */ const char* xplra_get_last_error_string(int connectionID); /** * Clear the last error. */ void xplra_clear_last_error(int connectionID); /*----------------------------------------------------------------------------*/ /** * Connect to the simulator. * * @return an ID for the created connection, or -1 on error. */ int xplra_connect(); /*----------------------------------------------------------------------------*/ /** * Get the versions of X-Plane, the XPLM library and XPLRA */ int xplra_get_versions(int connectionID, int* xplaneVersion, int* xplmVersion, int* xplraVersion); /*----------------------------------------------------------------------------*/ /** * Reload the plugins in X-Plane. After this the connection fails. */ int xplra_reload_plugins(int connectionID); /*----------------------------------------------------------------------------*/ /* Single dataref support */ /*----------------------------------------------------------------------------*/ /** * Get an integer value from the simulator. * * @return 0 on success, -1 on error */ int xplra_get_int(int* value, int connectionID, const char* name); /*----------------------------------------------------------------------------*/ /** * Get a float value from the simulator. * * @return 0 on success, -1 on error */ int xplra_get_float(float* value, int connectionID, const char* name); /*----------------------------------------------------------------------------*/ /** * Get a double value from the simulator. * * @return 0 on success, -1 on error */ int xplra_get_double(double* value, int connectionID, const char* name); /*----------------------------------------------------------------------------*/ /** * Get an array of floats into a buffer. * * @param dest the array into which to get the data * @param length the length of the destination buffer * @param offset the offset from which to query the array * * @return the actual number of elements returned in case of success, * -1 on error */ ssize_t xplra_get_float_array(float* dest, size_t length, size_t offset, int connectionID, const char* name); /*----------------------------------------------------------------------------*/ /** * Get an array of floats into a newly allocated buffer. * * @param length pointer to a variable containing the length to * query. On return it will be set to the actual length, which can be * less than or equal to the input value. * @param offset the offset from which to query the array * * @return the new array on success, 0 on error */ float* xplra_get_float_array_new(size_t* length, size_t offset, int connectionID, const char* name); /*----------------------------------------------------------------------------*/ /** * Get an array of integers into a buffer. * * @param dest the array into which to get the data * @param length the length of the destination buffer * @param offset the offset from which to query the array * * @return the actual number of elements returned in case of success, * -1 on error */ ssize_t xplra_get_int_array(int32_t* dest, size_t length, size_t offset, int connectionID, const char* name); /*----------------------------------------------------------------------------*/ /** * Get an array of integers into a newly allocated buffer. * * @param length pointer to a variable containing the length to * query. On return it will be set to the actual length, which can be * less than or equal to the input value. * @param offset the offset from which to query the array * * @return the new array on success, 0 on error */ int32_t* xplra_get_int_array_new(size_t* length, size_t offset, int connectionID, const char* name); /*----------------------------------------------------------------------------*/ /** * Get an array of bytes into a buffer. * * @param dest the array into which to get the data * @param length the length of the destination buffer * @param offset the offset from which to query the array * * @return the actual number of elements returned in case of success, * -1 on error */ ssize_t xplra_get_byte_array(void* dest, size_t length, size_t offset, int connectionID, const char* name); /*----------------------------------------------------------------------------*/ /** * Get an array of bytes into a newly allocated buffer. * * @param length pointer to a variable containing the length to * query. On return it will be set to the actual length, which can be * less than or equal to the input value. * @param offset the offset from which to query the array * * @return the new array on success, 0 on error */ uint8_t* xplra_get_byte_array_new(size_t* length, size_t offset, int connectionID, const char* name); /*----------------------------------------------------------------------------*/ /** * Set the integer dataref with the given name to the given value. * * @return 0 on success, -1 on error. */ int xplra_set_int(int connectionID, const char* name, int value); /*----------------------------------------------------------------------------*/ /** * Set the float dataref with the given name to the given value. * * @return 0 on success, -1 on error. */ int xplra_set_float(int connectionID, const char* name, float value); /*----------------------------------------------------------------------------*/ /** * Set the double dataref with the given name to the given value. * * @return 0 on success, -1 on error. */ int xplra_set_double(int connectionID, const char* name, double value); /*----------------------------------------------------------------------------*/ /** * Set the array of float values with the given name from the given * buffer. * * @return 0 on success, -1 on error. */ int xplra_set_float_array(int connectionID, const char* name, const float* values, size_t length, size_t offset); /*----------------------------------------------------------------------------*/ /** * Set the array of integer values with the given name from the given * buffer. * * @return 0 on success, -1 on error. */ int xplra_set_int_array(int connectionID, const char* name, const int32_t* values, size_t length, size_t offset); /*----------------------------------------------------------------------------*/ /** * Set the array of byte values with the given name from the given * buffer. * * @return 0 on success, -1 on error. */ int xplra_set_byte_array(int connectionID, const char* name, const void* values, size_t length, size_t offset); /*----------------------------------------------------------------------------*/ /** * Set the array of byte values with the given name from the given * string. The string will be padded with 0 if it has a length less * than the given length. * * @return 0 on success, -1 on error. */ int xplra_set_string(int connectionID, const char* name, const char* value, size_t length, size_t offset); /*----------------------------------------------------------------------------*/ /* Multi-dataref support */ /*----------------------------------------------------------------------------*/ /** * Create a multi-dataref getter for the given connection. * * @return the ID of the new getter, or -1 on error */ int xplra_multi_create_getter(int connectionID); /*----------------------------------------------------------------------------*/ /** * Create a multi-dataref setter for the given connection. * * @return the ID of the new setter, or -1 on error */ int xplra_multi_create_setter(int connectionID); /*----------------------------------------------------------------------------*/ /** * Add an integer dataref to a multi-dataref buffer. * * @return the ID of the dataref that can be used later. If the buffer * ID is invalid, INVALID_DATAREF_ID is returned. */ size_t xplra_multi_add_int(int bufferID, const char* name); /*----------------------------------------------------------------------------*/ /** * Add a float dataref to a multi-dataref buffer. * * @return the ID of the dataref that can be used later. If the buffer * ID is invalid, INVALID_DATAREF_ID is returned. */ size_t xplra_multi_add_float(int bufferID, const char* name); /*----------------------------------------------------------------------------*/ /** * Add a double dataref to a multi-dataref buffer. * * @return the ID of the dataref that can be used later. If the buffer * ID is invalid, INVALID_DATAREF_ID is returned. */ size_t xplra_multi_add_double(int bufferID, const char* name); /*----------------------------------------------------------------------------*/ /** * Add a float array dataref to a multi-dataref buffer. * * @return the ID of the dataref that can be used later. If the buffer * ID is invalid, INVALID_DATAREF_ID is returned. */ size_t xplra_multi_add_float_array(int bufferID, const char* name, size_t length, size_t offset); /*----------------------------------------------------------------------------*/ /** * Add an integer array dataref to a multi-dataref buffer. * * @return the ID of the dataref that can be used later. If the buffer * ID is invalid, INVALID_DATAREF_ID is returned. */ size_t xplra_multi_add_int_array(int bufferID, const char* name, size_t length, size_t offset); /*----------------------------------------------------------------------------*/ /** * Add a byte array dataref to a multi-dataref buffer. * * @return the ID of the dataref that can be used later. If the buffer * ID is invalid, INVALID_DATAREF_ID is returned. */ size_t xplra_multi_add_byte_array(int bufferID, const char* name, size_t length, size_t offset); /*----------------------------------------------------------------------------*/ /** * Finalize the given buffer, if not finalized yet. * * @return -1 on error (if the buffer ID is invalid), 0 if there is no * data in the buffer, 1 if there is data in it. */ int xplra_multi_finalize(int bufferID); /*----------------------------------------------------------------------------*/ /** * Register the buffer with the given ID in X-Plane. If needed, it * will be finalized too. * * @return 0 on success, -1 on error */ int xplra_multi_register(int bufferID); /*----------------------------------------------------------------------------*/ /** * Unregister the buffer with the given ID from X-Plane. If needed, it * will be finalized too. * * @return 0 on success, -1 on error */ int xplra_multi_unregister(int bufferID); /*----------------------------------------------------------------------------*/ /** * Execute the buffer with the given ID. If the buffer is not * finalized, it will be finalized. If it is not finalized, but * registered, the registration will be cleared, and it will be * re-registered after finalizing. * * @return 0 on success, -1 on error */ int xplra_multi_execute(int bufferID); /*----------------------------------------------------------------------------*/ /** * Set the value of an integer dataref with the given ID. * * @return 0 on success, -1 on error. */ int xplra_multi_set_int(int bufferID, size_t datarefID, int value); /*----------------------------------------------------------------------------*/ /** * Get the value of an integer dataref with the given ID. * * @param dest pointer to the variable that will receive the value * * @return 0 on success, -1 on error. */ int xplra_multi_get_int(int* dest, int bufferID, size_t datarefID); /*----------------------------------------------------------------------------*/ /** * Get a const pointer to the integer dataref with the given ID * * @return the pointer or success, 0 on error. */ const int32_t* xplra_multi_get_int_const_ptr(int bufferID, size_t datarefID); /*----------------------------------------------------------------------------*/ /** * Get a pointer to the integer dataref with the given ID * * @return the pointer or success, 0 on error. */ int32_t* xplra_multi_get_int_ptr(int bufferID, size_t datarefID); /*----------------------------------------------------------------------------*/ /** * Set the value of a float dataref with the given ID. * * @return 0 on success, -1 on error. */ int xplra_multi_set_float(int bufferID, size_t datarefID, float value); /*----------------------------------------------------------------------------*/ /** * Get the value of a float dataref with the given ID. * * @param dest pointer to the variable that will receive the value * * @return 0 on success, -1 on error. */ int xplra_multi_get_float(float* dest, int bufferID, size_t datarefID); /*----------------------------------------------------------------------------*/ /** * Get a const pointer to the float dataref with the given ID * * @return the pointer or success, 0 on error. */ const float* xplra_multi_get_float_const_ptr(int bufferID, size_t datarefID); /*----------------------------------------------------------------------------*/ /** * Get a pointer to the float dataref with the given ID * * @return the pointer or success, 0 on error. */ float* xplra_multi_get_float_ptr(int bufferID, size_t datarefID); /*----------------------------------------------------------------------------*/ /** * Set the value of a double dataref with the given ID. * * @return 0 on success, -1 on error. */ int xplra_multi_set_double(int bufferID, size_t datarefID, double value); /*----------------------------------------------------------------------------*/ /** * Get the value of a double dataref with the given ID. * * @param dest pointer to the variable that will receive the value * * @return 0 on success, -1 on error. */ int xplra_multi_get_double(double* dest, int bufferID, size_t datarefID); /*----------------------------------------------------------------------------*/ /** * Get a const pointer to the double dataref with the given ID * * @return the pointer or success, 0 on error. */ const double* xplra_multi_get_double_const_ptr(int bufferID, size_t datarefID); /*----------------------------------------------------------------------------*/ /** * Get a pointer to the double dataref with the given ID * * @return the pointer or success, 0 on error. */ double* xplra_multi_get_double_ptr(int bufferID, size_t datarefID); /*----------------------------------------------------------------------------*/ /** * Set the contents of the float array dataref with the given ID. * * @param length the amount of data. If 0, it is assumed to be the * length of the data in the buffer minus the offset. * @param offset the offset within the buffer to set the data from * * @return the number of data items set, or -1 on error. */ ssize_t xplra_multi_set_float_array(int bufferID, size_t datarefID, const float* value, size_t length, size_t offset); /*----------------------------------------------------------------------------*/ /** * Get the contents of the float array with the given ID. * * @param length the amount of data. If 0, it is assumed to be the * length of the data in the buffer minus the offset. * @param offset the offset within the buffer to get the data from * * @return the number of data items retrieved, or -1 on error. */ ssize_t xplra_multi_get_float_array(float* value, size_t length, size_t offset, int bufferID, size_t datarefID); /*----------------------------------------------------------------------------*/ /** * Get a pointer to the float array with the given ID. * * @param offset the offset within the buffer. * * @return the pointer on success, 0 on error. */ const float* xplra_multi_get_float_array_ptr(int bufferID, size_t datarefID, size_t offset); /*----------------------------------------------------------------------------*/ /** * Set the contents of the integer array dataref with the given ID. * * @param length the amount of data. If 0, it is assumed to be the * length of the data in the buffer minus the offset. * @param offset the offset within the buffer to set the data from * * @return the number of data items set, or -1 on error. */ ssize_t xplra_multi_set_int_array(int bufferID, size_t datarefID, const int32_t* value, size_t length, size_t offset); /*----------------------------------------------------------------------------*/ /** * Get the contents of the integer array with the given ID. * * @param length the amount of data. If 0, it is assumed to be the * length of the data in the buffer minus the offset. * @param offset the offset within the buffer to get the data from * * @return the number of data items retrieved, or -1 on error. */ ssize_t xplra_multi_get_int_array(int32_t* value, size_t length, size_t offset, int bufferID, size_t datarefID); /*----------------------------------------------------------------------------*/ /** * Get a pointer to the integer array with the given ID. * * @param offset the offset within the buffer. * * @return the pointer on success, 0 on error. */ const int32_t* xplra_multi_get_int_array_ptr(int bufferID, size_t datarefID, size_t offset); /*----------------------------------------------------------------------------*/ /** * Set the contents of the byte array dataref with the given ID. * * @param length the amount of data. If 0, it is assumed to be the * length of the data in the buffer minus the offset. * @param offset the offset within the buffer to set the data from * * @return the number of data items set, or -1 on error. */ ssize_t xplra_multi_set_byte_array(int bufferID, size_t datarefID, const void* value, size_t length, size_t offset); /*----------------------------------------------------------------------------*/ /** * Get the contents of the byte array with the given ID. * * @param length the amount of data. If 0, it is assumed to be the * length of the data in the buffer minus the offset. * @param offset the offset within the buffer to get the data from * * @return the number of data items retrieved, or -1 on error. */ ssize_t xplra_multi_get_byte_array(void* value, size_t length, size_t offset, int bufferID, size_t datarefID); /*----------------------------------------------------------------------------*/ /** * Get a pointer to the byte array with the given ID. * * @param offset the offset within the buffer. * * @return the pointer on success, 0 on error. */ const uint8_t* xplra_multi_get_byte_array_ptr(int bufferID, size_t datarefID, size_t offset); /*----------------------------------------------------------------------------*/ /** * Set the value of the byte array with the given ID from the given * string. If the string is shorter than the array, the rest will be * filled with 0s. * * @return the number of bytes set, or -1 on error */ ssize_t xplra_multi_set_string(int bufferID, size_t datarefID, const char* value, size_t offset); /*----------------------------------------------------------------------------*/ /** * Get a pointer as a string pointer to the byte array with the given * ID. * * @return the pointer on success, 0 on error. */ const char* xplra_multi_get_string_ptr(int bufferID, size_t datarefID, size_t offset); /*----------------------------------------------------------------------------*/ /** * Destroy a multi-dataref buffer for the given connection. * * @param connectionID the ID of the connection for which the buffer * has been created. * * @return 0 on success, -1 on error. */ int xplra_multi_destroy_buffer(int connectionID, int bufferID); /*----------------------------------------------------------------------------*/ /*----------------------------------------------------------------------------*/ /** * Show a message in the simulator window for the given duration. */ int xplra_show_message(int connectionID, const char* message, float duration); /*----------------------------------------------------------------------------*/ /*----------------------------------------------------------------------------*/ /** * Register the given hotkey codes for listening. If there is an * existing set of hotkeys registered, those will be overwritten. */ int xplra_register_hotkeys(int connectionID, const uint16_t* codes, size_t length); /*----------------------------------------------------------------------------*/ /** * Query the registered hotkeys whether they were pressed. */ int xplra_query_hotkeys(int connectionID, uint8_t* states, size_t length); /*----------------------------------------------------------------------------*/ /** * Unregister the hotkeys. */ int xplra_unregister_hotkeys(int connectionID); /*----------------------------------------------------------------------------*/ /*----------------------------------------------------------------------------*/ /** * Destroy the connection with the given ID. * * @return 0 on success, -1 on error. */ int xplra_disconnect(int connectionID); /*----------------------------------------------------------------------------*/ #ifdef __cplusplus } // extern "C" #endif /*----------------------------------------------------------------------------*/ #endif // HU_VARADIISTVAN_XPLRA_XPLRA_H