Changeset 70:7882bccb87a0 in xplra


Ignore:
Timestamp:
04/13/13 12:54:56 (11 years ago)
Author:
István Váradi <ivaradi@…>
Branch:
default
Phase:
public
Message:

Added the description of the C API

Files:
4 edited

Legend:

Unmodified
Added
Removed

  • doc/overview.dox

    r69 r70  
    2525 * computer that runs X-Plane, but extending it with TCP/IP-based or
    2626 * network access would not be difficult. While client libraries are
    27  * provided for \ref cpplib "C, C++" and \ref pythonlib "Python",
     27 * provided for \ref cppapi "C, C++" and \ref pythonapi "Python",
    2828 * the communication protocol between clients and the plugin is open
    2929 * and is \ref proto "described" in  this documentation. So you can
    … …  
    699699 * byte | 0x00 (\ref RESULT_OK)
    700700 */
    701 /*! \page cpplib C/C++ Client Library
    702  *
    703  * The C++ client library's central class is \ref
     701/*! \page cppapi C/C++ Client API
     702 *
     703 * The C++ client API's central class is \ref
    704704 * hu::varadiistvan::xplra::XPlane. To communicate with the XPLRA
    705705 * plugin in X-Plane, create an instance of it. This, however, does
    … …  
    710710 *
    711711 * \c IOException is part of the exception hierarchy of the client
    712  * library. The hierarchy begins with \ref
     712 * API. The hierarchy begins with \ref
    713713 * hu::varadiistvan::xplra::Exception. The \c what function is
    714714 * implemented for all exception classes, so you can always get a
    … …  
    752752 * have more than one corresponding functions with different
    753753 * parameters for convenience.
     754 *
     755 * The \ref src/client/c/hu/varadiistvan/xplra/xplra.h "C API" is
     756 * a wrapper over the C++ one, so its logic is essentially the
     757 * same. To connect to X-Plane, call \ref xplra_connect. It returns a
     758 * non-negative handle, which can be used to refer to the connection
     759 * (i.e. the underlying \c XPlane object) in the other functions.
     760 *
     761 * In case of error, it, and most other functions of the C returns
     762 * -1. To check what the last error was, call \ref
     763 * xplra_get_last_error or \ref xplra_get_last_error_string.
     764 *
     765 * You can create multi-dataref buffers with C API as well with
     766 * \ref xplra_multi_create_getter and \ref
     767 * xplra_multi_create_setter. These return a buffer ID on success, and
     768 * you should use that buffer ID later on to manipulate the buffer.
    754769 */
    755 /*! \page pythonlib Python Client Library
     770/*! \page pythonapi Python Client API
    756771 *
    757772 */

  • src/client/c/hu/varadiistvan/xplra/xplra.cc

    r58 r70  
    13731373    if (connection==0) return -1;
    13741374
     1375    connection->disconnect();
     1376
     1377    return 0;
     1378}
     1379
     1380//------------------------------------------------------------------------------
     1381//------------------------------------------------------------------------------
     1382
     1383extern "C" int xplra_reconnect(int connectionID)
     1384{
     1385    Connection* connection = ConnectionSlot::getValue(connectionID);
     1386    if (connection==0) return -1;
     1387
     1388    try {
     1389        connection->connect();
     1390        return 0;
     1391    } catch(...) {
     1392        return -1;
     1393    }
     1394}
     1395
     1396//------------------------------------------------------------------------------
     1397//------------------------------------------------------------------------------
     1398
     1399extern "C" int xplra_destroy(int connectionID)
     1400{
     1401    Connection* connection = ConnectionSlot::getValue(connectionID);
     1402    if (connection==0) return -1;
     1403
    13751404    ConnectionSlot::clearValue(connectionID);
    1376     connection->disconnect();
    13771405    delete connection;
    13781406

  • src/client/c/hu/varadiistvan/xplra/xplra.h

    r58 r70  
    3232/*----------------------------------------------------------------------------*/
    3333
     34/** @file */
     35
     36/*----------------------------------------------------------------------------*/
     37
    3438#include <stdlib.h>
    3539#include <inttypes.h>
    … …  
    107111/*----------------------------------------------------------------------------*/
    108112
     113/**
     114 * This ID is returned by multi-dataref buffer functions when the
     115 * buffer is not found, this the dataref cannot be assigned an ID
     116 */
    109117#define INVALID_DATAREF_ID ((size_t)-1)
    110118
    … …  
    193201 * @param length the length of the destination buffer
    194202 * @param offset the offset from which to query the array
     203 * @param connectionID the ID of the connection to use
     204 * @param name the name of the dataref
    195205 *
    196206 * @return the actual number of elements returned in case of success,
    … …  
    209219 * less than or equal to the input value.
    210220 * @param offset the offset from which to query the array
     221 * @param connectionID the ID of the connection to use
     222 * @param name the name of the dataref
    211223 *
    212224 * @return the new array on success, 0 on error
    … …  
    223235 * @param length the length of the destination buffer
    224236 * @param offset the offset from which to query the array
     237 * @param connectionID the ID of the connection to use
     238 * @param name the name of the dataref
    225239 *
    226240 * @return the actual number of elements returned in case of success,
    … …  
    239253 * less than or equal to the input value.
    240254 * @param offset the offset from which to query the array
     255 * @param connectionID the ID of the connection to use
     256 * @param name the name of the dataref
    241257 *
    242258 * @return the new array on success, 0 on error
    … …  
    253269 * @param length the length of the destination buffer
    254270 * @param offset the offset from which to query the array
     271 * @param connectionID the ID of the connection to use
     272 * @param name the name of the dataref
    255273 *
    256274 * @return the actual number of elements returned in case of success,
    … …  
    269287 * less than or equal to the input value.
    270288 * @param offset the offset from which to query the array
     289 * @param connectionID the ID of the connection to use
     290 * @param name the name of the dataref
    271291 *
    272292 * @return the new array on success, 0 on error
    … …  
    497517 *
    498518 * @param dest pointer to the variable that will receive the value
     519 * @param bufferID the ID of the buffer to use
     520 * @param datarefID the ID of the dataref whose value is to be retrieved
    499521 *
    500522 * @return 0 on success, -1 on error.
    … …  
    535557 *
    536558 * @param dest pointer to the variable that will receive the value
     559 * @param bufferID the ID of the buffer to use
     560 * @param datarefID the ID of the dataref whose value is to be retrieved
    537561 *
    538562 * @return 0 on success, -1 on error.
    … …  
    573597 *
    574598 * @param dest pointer to the variable that will receive the value
     599 * @param bufferID the ID of the buffer to use
     600 * @param datarefID the ID of the dataref whose value is to be retrieved
    575601 *
    576602 * @return 0 on success, -1 on error.
    … …  
    601627 * Set the contents of the float array dataref with the given ID.
    602628 *
     629 * @param bufferID the ID of the buffer to use
     630 * @param datarefID the ID of the dataref whose value is to be set
     631 * @param value the array to set
    603632 * @param length the amount of data. If 0, it is assumed to be the
    604633 * length of the data in the buffer minus the offset.
    … …  
    616645 * Get the contents of the float array with the given ID.
    617646 *
     647 * @param value the destination buffer
    618648 * @param length the amount of data. If 0, it is assumed to be the
    619649 * length of the data in the buffer minus the offset.
    620650 * @param offset the offset within the buffer to get the data from
     651 * @param bufferID the ID of the buffer to use
     652 * @param datarefID the ID of the dataref whose value is to be retrieved
    621653 *
    622654 * @return the number of data items retrieved, or -1 on error.
    … …  
    631663 * Get a pointer to the float array with the given ID.
    632664 *
     665 * @param bufferID the ID of the buffer to use
     666 * @param datarefID the ID of the dataref whose value is to be retrieved
    633667 * @param offset the offset within the buffer.
    634668 *
    … …  
    643677 * Set the contents of the integer array dataref with the given ID.
    644678 *
     679 * @param bufferID the ID of the buffer to use
     680 * @param datarefID the ID of the dataref whose value is to be set
     681 * @param value the array to set
    645682 * @param length the amount of data. If 0, it is assumed to be the
    646683 * length of the data in the buffer minus the offset.
    … …  
    658695 * Get the contents of the integer array with the given ID.
    659696 *
     697 * @param value the destination buffer
    660698 * @param length the amount of data. If 0, it is assumed to be the
    661699 * length of the data in the buffer minus the offset.
    662700 * @param offset the offset within the buffer to get the data from
     701 * @param bufferID the ID of the buffer to use
     702 * @param datarefID the ID of the dataref whose value is to be retrieved
    663703 *
    664704 * @return the number of data items retrieved, or -1 on error.
    … …  
    673713 * Get a pointer to the integer array with the given ID.
    674714 *
     715 * @param bufferID the ID of the buffer to use
     716 * @param datarefID the ID of the dataref whose value is to be retrieved
    675717 * @param offset the offset within the buffer.
    676718 *
    … …  
    685727 * Set the contents of the byte array dataref with the given ID.
    686728 *
     729 * @param bufferID the ID of the buffer to use
     730 * @param datarefID the ID of the dataref whose value is to be set
     731 * @param value the array to set
    687732 * @param length the amount of data. If 0, it is assumed to be the
    688733 * length of the data in the buffer minus the offset.
    … …  
    700745 * Get the contents of the byte array with the given ID.
    701746 *
     747 * @param value the destination buffer
    702748 * @param length the amount of data. If 0, it is assumed to be the
    703749 * length of the data in the buffer minus the offset.
    704750 * @param offset the offset within the buffer to get the data from
     751 * @param bufferID the ID of the buffer to use
     752 * @param datarefID the ID of the dataref whose value is to be retrieved
    705753 *
    706754 * @return the number of data items retrieved, or -1 on error.
    … …  
    715763 * Get a pointer to the byte array with the given ID.
    716764 *
     765 * @param bufferID the ID of the buffer to use
     766 * @param datarefID the ID of the dataref whose value is to be retrieved
    717767 * @param offset the offset within the buffer.
    718768 *
    … …  
    752802 * @param connectionID the ID of the connection for which the buffer
    753803 * has been created.
     804 * @param bufferID the ID of the buffer to destroy
    754805 *
    755806 * @return 0 on success, -1 on error.
    … …  
    793844
    794845/**
     846 * Disconnect the connection with the given ID.
     847 *
     848 * @return 0 on success, -1 on error.
     849 */
     850int xplra_disconnect(int connectionID);
     851
     852/*----------------------------------------------------------------------------*/
     853
     854/**
     855 * Reconnect the connection with the given ID. If it is already
     856 * connected, nothing happens.
     857 *
     858 * @return 0 on success, -1 on error.
     859 */
     860int xplra_reconnect(int connectionID);
     861
     862/*----------------------------------------------------------------------------*/
     863
     864/**
    795865 * Destroy the connection with the given ID.
    796866 *
    797867 * @return 0 on success, -1 on error.
    798868 */
    799 int xplra_disconnect(int connectionID);
     869int xplra_destroy(int connectionID);
    800870
    801871/*----------------------------------------------------------------------------*/

  • src/client/python/xplra.py

    r66 r70  
    1010## @package xplra
    1111#
    12 # Python client module and C/C++ client library for the X-Plane Remote
    13 # Access plugin
     12# Python client module for the X-Plane Remote Access plugin
    1413
    1514#-------------------------------------------------------------------------------
Note: See TracChangeset for help on using the changeset viewer.