[14] | 1 | /* Copyright (c) 2013 by István Váradi
|
---|
| 2 | *
|
---|
| 3 | * This file is part of XPLRA, a remote-access plugin for X-Plane
|
---|
| 4 | *
|
---|
| 5 | * Redistribution and use in source and binary forms, with or without
|
---|
| 6 | * modification, are permitted provided that the following conditions are met:
|
---|
| 7 | *
|
---|
| 8 | * 1. Redistributions of source code must retain the above copyright notice, this
|
---|
| 9 | * list of conditions and the following disclaimer.
|
---|
| 10 | * 2. Redistributions in binary form must reproduce the above copyright notice,
|
---|
| 11 | * this list of conditions and the following disclaimer in the documentation
|
---|
| 12 | * and/or other materials provided with the distribution.
|
---|
| 13 | *
|
---|
| 14 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
|
---|
| 15 | * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
|
---|
| 16 | * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
---|
| 17 | * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
|
---|
| 18 | * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
---|
| 19 | * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
---|
| 20 | * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
|
---|
| 21 | * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
---|
| 22 | * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
---|
| 23 | * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
---|
| 24 | *
|
---|
| 25 | * The views and conclusions contained in the software and documentation are those
|
---|
| 26 | * of the authors and should not be interpreted as representing official policies,
|
---|
| 27 | * either expressed or implied, of the FreeBSD Project.
|
---|
| 28 | */
|
---|
| 29 |
|
---|
| 30 | #ifndef HU_VARADIISTVAN_XPLRA_XPLRA_H
|
---|
| 31 | #define HU_VARADIISTVAN_XPLRA_XPLRA_H
|
---|
| 32 | /*----------------------------------------------------------------------------*/
|
---|
| 33 |
|
---|
[24] | 34 | #include <stdlib.h>
|
---|
| 35 | #include <inttypes.h>
|
---|
| 36 |
|
---|
| 37 | /*----------------------------------------------------------------------------*/
|
---|
| 38 |
|
---|
[14] | 39 | #ifdef __cplusplus
|
---|
| 40 | extern "C" {
|
---|
| 41 | #endif
|
---|
| 42 |
|
---|
| 43 | /*----------------------------------------------------------------------------*/
|
---|
| 44 |
|
---|
[23] | 45 | /** No error occured */
|
---|
| 46 | #define ERROR_NONE 0
|
---|
| 47 |
|
---|
| 48 | /**
|
---|
| 49 | * An I/O error has occured. The subcode is the errno value on Linux, or the
|
---|
| 50 | * Windows error code.
|
---|
| 51 | */
|
---|
| 52 | #define ERROR_IO 1
|
---|
| 53 |
|
---|
| 54 | /**
|
---|
| 55 | * A protocol error has occured. The subcode is one of the
|
---|
| 56 | * ERROR_PROTOCOL_XXX values.
|
---|
| 57 | */
|
---|
| 58 | #define ERROR_PROTOCOL 2
|
---|
| 59 |
|
---|
| 60 | /** Invalid command was passed to the plugin */
|
---|
| 61 | #define ERROR_PROTOCOL_INVALID_COMMAND = 1
|
---|
| 62 |
|
---|
| 63 | /** An unknown dataref was specified */
|
---|
| 64 | #define ERROR_PROTOCOL_UNKNOWN_DATAREF = 2
|
---|
| 65 |
|
---|
| 66 | /** An invalid type was specified */
|
---|
| 67 | #define ERROR_PROTOCOL_INVALID_TYPE = 3
|
---|
| 68 |
|
---|
| 69 | /** An invalid length was specified */
|
---|
| 70 | #define ERROR_PROTOCOL_INVALID_LENGTH = 4
|
---|
| 71 |
|
---|
| 72 | /** An invalid offset was specified */
|
---|
| 73 | #define ERROR_PROTOCOL_INVALID_OFFSET = 5
|
---|
| 74 |
|
---|
| 75 | /** An invalid count was specified */
|
---|
| 76 | #define ERROR_PROTOCOL_INVALID_COUNT = 6
|
---|
| 77 |
|
---|
| 78 | /** An invalid ID was specified */
|
---|
| 79 | #define ERROR_PROTOCOL_INVALID_ID = 7
|
---|
| 80 |
|
---|
| 81 | /** Other protocol error */
|
---|
| 82 | #define ERROR_PROTOCOL_OTHER = 8
|
---|
| 83 |
|
---|
| 84 | /** A function requiring a connection is called without a connection */
|
---|
| 85 | #define ERROR_NOT_CONNECTED 3
|
---|
| 86 |
|
---|
| 87 | /** A type-specific function was called for a dataref of a different type */
|
---|
| 88 | #define ERROR_TYPE_MISMATCH 4
|
---|
| 89 |
|
---|
| 90 | /** An invalid ID was passed to a function */
|
---|
| 91 | #define ERROR_INVALID_ID 5
|
---|
| 92 |
|
---|
| 93 | /** Some other error */
|
---|
| 94 | #define ERROR_OTHER 255
|
---|
| 95 |
|
---|
| 96 | /*----------------------------------------------------------------------------*/
|
---|
| 97 |
|
---|
| 98 | /**
|
---|
| 99 | * Get the last error code with the subcode.
|
---|
| 100 | *
|
---|
| 101 | * @return the last error code, or -1 if the given connection ID is invalid.
|
---|
| 102 | */
|
---|
| 103 | int xplra_get_last_error(int connectionID, unsigned long* subCode);
|
---|
| 104 |
|
---|
| 105 | /**
|
---|
| 106 | * Get a string representation of the last error.
|
---|
| 107 | *
|
---|
| 108 | * @return the string representation of the last error, or 0 if there
|
---|
| 109 | * was no last error, or the connection ID is invalid.
|
---|
| 110 | */
|
---|
| 111 | const char* xplra_get_last_error_string(int connectionID);
|
---|
| 112 |
|
---|
| 113 | /**
|
---|
| 114 | * Clear the last error.
|
---|
| 115 | */
|
---|
| 116 | void xplra_clear_last_error(int connectionID);
|
---|
| 117 |
|
---|
| 118 | /*----------------------------------------------------------------------------*/
|
---|
| 119 |
|
---|
| 120 | /**
|
---|
| 121 | * Connect to the simulator.
|
---|
| 122 | *
|
---|
| 123 | * @return an ID for the created connection, or -1 on error.
|
---|
| 124 | */
|
---|
[14] | 125 | int xplra_connect();
|
---|
| 126 |
|
---|
| 127 | /*----------------------------------------------------------------------------*/
|
---|
| 128 |
|
---|
[23] | 129 | /**
|
---|
| 130 | * Get an integer value from the simulator.
|
---|
| 131 | *
|
---|
| 132 | * @return 0 on success, -1 on error
|
---|
| 133 | */
|
---|
| 134 | int xplra_get_int(int* value, int connectionID, const char* name);
|
---|
| 135 |
|
---|
| 136 | /*----------------------------------------------------------------------------*/
|
---|
| 137 |
|
---|
| 138 | /**
|
---|
| 139 | * Get a float value from the simulator.
|
---|
| 140 | *
|
---|
| 141 | * @return 0 on success, -1 on error
|
---|
| 142 | */
|
---|
| 143 | int xplra_get_float(float* value, int connectionID, const char* name);
|
---|
| 144 |
|
---|
| 145 | /*----------------------------------------------------------------------------*/
|
---|
| 146 |
|
---|
| 147 | /**
|
---|
| 148 | * Get a double value from the simulator.
|
---|
| 149 | *
|
---|
| 150 | * @return 0 on success, -1 on error
|
---|
| 151 | */
|
---|
| 152 | int xplra_get_double(double* value, int connectionID, const char* name);
|
---|
| 153 |
|
---|
| 154 | /*----------------------------------------------------------------------------*/
|
---|
| 155 |
|
---|
| 156 | /**
|
---|
[24] | 157 | * Get an array of floats into a buffer.
|
---|
| 158 | *
|
---|
| 159 | * @param dest the array into which to get the data
|
---|
| 160 | * @param length the length of the destination buffer
|
---|
| 161 | * @param offset the offset from which to query the array
|
---|
| 162 | *
|
---|
| 163 | * @return the actual number of elements returned in case of success,
|
---|
| 164 | * -1 on error
|
---|
| 165 | */
|
---|
| 166 | ssize_t xplra_get_float_array(float* dest, size_t length, size_t offset,
|
---|
| 167 | int connectionID, const char* name);
|
---|
| 168 |
|
---|
| 169 | /*----------------------------------------------------------------------------*/
|
---|
| 170 |
|
---|
| 171 | /**
|
---|
| 172 | * Get an array of floats into a newly allocated buffer.
|
---|
| 173 | *
|
---|
| 174 | * @param length pointer to a variable containing the length to
|
---|
| 175 | * query. On return it will be set to the actual length, which can be
|
---|
| 176 | * less than or equal to the input value.
|
---|
| 177 | * @param offset the offset from which to query the array
|
---|
| 178 | *
|
---|
| 179 | * @return the new array on success, 0 on error
|
---|
| 180 | */
|
---|
| 181 | float* xplra_get_float_array_new(size_t* length, size_t offset,
|
---|
| 182 | int connectionID, const char* name);
|
---|
| 183 |
|
---|
| 184 | /*----------------------------------------------------------------------------*/
|
---|
| 185 |
|
---|
| 186 | /**
|
---|
| 187 | * Get an array of integers into a buffer.
|
---|
| 188 | *
|
---|
| 189 | * @param dest the array into which to get the data
|
---|
| 190 | * @param length the length of the destination buffer
|
---|
| 191 | * @param offset the offset from which to query the array
|
---|
| 192 | *
|
---|
| 193 | * @return the actual number of elements returned in case of success,
|
---|
| 194 | * -1 on error
|
---|
| 195 | */
|
---|
| 196 | ssize_t xplra_get_int_array(int32_t* dest, size_t length, size_t offset,
|
---|
| 197 | int connectionID, const char* name);
|
---|
| 198 |
|
---|
| 199 | /*----------------------------------------------------------------------------*/
|
---|
| 200 |
|
---|
| 201 | /**
|
---|
| 202 | * Get an array of integers into a newly allocated buffer.
|
---|
| 203 | *
|
---|
| 204 | * @param length pointer to a variable containing the length to
|
---|
| 205 | * query. On return it will be set to the actual length, which can be
|
---|
| 206 | * less than or equal to the input value.
|
---|
| 207 | * @param offset the offset from which to query the array
|
---|
| 208 | *
|
---|
| 209 | * @return the new array on success, 0 on error
|
---|
| 210 | */
|
---|
| 211 | int32_t* xplra_get_int_array_new(size_t* length, size_t offset,
|
---|
| 212 | int connectionID, const char* name);
|
---|
| 213 |
|
---|
| 214 | /*----------------------------------------------------------------------------*/
|
---|
| 215 |
|
---|
| 216 | /**
|
---|
| 217 | * Get an array of bytes into a buffer.
|
---|
| 218 | *
|
---|
| 219 | * @param dest the array into which to get the data
|
---|
| 220 | * @param length the length of the destination buffer
|
---|
| 221 | * @param offset the offset from which to query the array
|
---|
| 222 | *
|
---|
| 223 | * @return the actual number of elements returned in case of success,
|
---|
| 224 | * -1 on error
|
---|
| 225 | */
|
---|
| 226 | ssize_t xplra_get_byte_array(void* dest, size_t length, size_t offset,
|
---|
| 227 | int connectionID, const char* name);
|
---|
| 228 |
|
---|
| 229 | /*----------------------------------------------------------------------------*/
|
---|
| 230 |
|
---|
| 231 | /**
|
---|
| 232 | * Get an array of bytes into a newly allocated buffer.
|
---|
| 233 | *
|
---|
| 234 | * @param length pointer to a variable containing the length to
|
---|
| 235 | * query. On return it will be set to the actual length, which can be
|
---|
| 236 | * less than or equal to the input value.
|
---|
| 237 | * @param offset the offset from which to query the array
|
---|
| 238 | *
|
---|
| 239 | * @return the new array on success, 0 on error
|
---|
| 240 | */
|
---|
| 241 | uint8_t* xplra_get_byte_array_new(size_t* length, size_t offset,
|
---|
| 242 | int connectionID, const char* name);
|
---|
| 243 |
|
---|
| 244 | /*----------------------------------------------------------------------------*/
|
---|
| 245 |
|
---|
| 246 | /**
|
---|
[25] | 247 | * Set the integer dataref with the given name to the given value.
|
---|
| 248 | *
|
---|
| 249 | * @return 0 on success, -1 on error.
|
---|
| 250 | */
|
---|
| 251 | int xplra_set_int(int connectionID, const char* name, int value);
|
---|
| 252 |
|
---|
| 253 | /*----------------------------------------------------------------------------*/
|
---|
| 254 |
|
---|
| 255 | /**
|
---|
| 256 | * Set the float dataref with the given name to the given value.
|
---|
| 257 | *
|
---|
| 258 | * @return 0 on success, -1 on error.
|
---|
| 259 | */
|
---|
| 260 | int xplra_set_float(int connectionID, const char* name, float value);
|
---|
| 261 |
|
---|
| 262 | /*----------------------------------------------------------------------------*/
|
---|
| 263 |
|
---|
| 264 | /**
|
---|
| 265 | * Set the double dataref with the given name to the given value.
|
---|
| 266 | *
|
---|
| 267 | * @return 0 on success, -1 on error.
|
---|
| 268 | */
|
---|
| 269 | int xplra_set_double(int connectionID, const char* name, double value);
|
---|
| 270 |
|
---|
| 271 | /*----------------------------------------------------------------------------*/
|
---|
| 272 |
|
---|
| 273 | /**
|
---|
| 274 | * Set the array of float values with the given name from the given
|
---|
| 275 | * buffer.
|
---|
| 276 | *
|
---|
| 277 | * @return 0 on success, -1 on error.
|
---|
| 278 | */
|
---|
| 279 | int xplra_set_float_array(int connectionID, const char* name,
|
---|
| 280 | const float* values, size_t length, size_t offset);
|
---|
| 281 |
|
---|
| 282 | /*----------------------------------------------------------------------------*/
|
---|
| 283 |
|
---|
| 284 | /**
|
---|
| 285 | * Set the array of integer values with the given name from the given
|
---|
| 286 | * buffer.
|
---|
| 287 | *
|
---|
| 288 | * @return 0 on success, -1 on error.
|
---|
| 289 | */
|
---|
| 290 | int xplra_set_int_array(int connectionID, const char* name,
|
---|
| 291 | const int32_t* values, size_t length, size_t offset);
|
---|
| 292 |
|
---|
| 293 | /*----------------------------------------------------------------------------*/
|
---|
| 294 |
|
---|
| 295 | /**
|
---|
| 296 | * Set the array of byte values with the given name from the given
|
---|
| 297 | * buffer.
|
---|
| 298 | *
|
---|
| 299 | * @return 0 on success, -1 on error.
|
---|
| 300 | */
|
---|
| 301 | int xplra_set_byte_array(int connectionID, const char* name,
|
---|
| 302 | const void* values, size_t length, size_t offset);
|
---|
| 303 |
|
---|
| 304 | /*----------------------------------------------------------------------------*/
|
---|
| 305 |
|
---|
| 306 | /**
|
---|
| 307 | * Set the array of byte values with the given name from the given
|
---|
| 308 | * string. The string will be padded with 0 if it has a length less
|
---|
| 309 | * than the given length.
|
---|
| 310 | *
|
---|
| 311 | * @return 0 on success, -1 on error.
|
---|
| 312 | */
|
---|
| 313 | int xplra_set_string(int connectionID, const char* name,
|
---|
| 314 | const char* value, size_t length, size_t offset);
|
---|
| 315 |
|
---|
| 316 | /*----------------------------------------------------------------------------*/
|
---|
| 317 |
|
---|
| 318 | /**
|
---|
[23] | 319 | * Destroy the connection with the given ID.
|
---|
| 320 | *
|
---|
| 321 | * @return 0 on success, -1 on error.
|
---|
| 322 | */
|
---|
| 323 | int xplra_disconnect(int connectionID);
|
---|
| 324 |
|
---|
| 325 | /*----------------------------------------------------------------------------*/
|
---|
| 326 |
|
---|
[14] | 327 | #ifdef __cplusplus
|
---|
| 328 | } // extern "C"
|
---|
| 329 | #endif
|
---|
| 330 |
|
---|
| 331 | /*----------------------------------------------------------------------------*/
|
---|
| 332 | #endif // HU_VARADIISTVAN_XPLRA_XPLRA_H
|
---|