/* 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 /** Other protocol error */ #define ERROR_PROTOCOL_OTHER = 8 /** 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 /*----------------------------------------------------------------------------*/ /** * 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 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); /*----------------------------------------------------------------------------*/ /** * 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