source: xplra/src/client/c/hu/varadiistvan/xplra/xplra.h@ 25:77da156bca86

/* 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

/** 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