source: xplra/src/client/c/hu/varadiistvan/xplra/xplra.h@ 58:f0fa93354e15

/* 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 <stdlib.h>
#include <inttypes.h>

/*----------------------------------------------------------------------------*/

#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.
 *
 * @return 0 on success, -1 on error
 */
int xplra_multi_unregister(int bufferID);

/*----------------------------------------------------------------------------*/

/**
 * Unregister the buffer with the given ID from X-Plane safely,
 * i.e. the registration ID will be cleared anyway to support re-registration.
 *
 * @return -1 if the buffer ID is invalid, 0 if the unregistration
 * call failed, 1 if it was successful.
 */
int xplra_multi_unregister_safely(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