Changeset 69:89a39d7aed5a in xplra

Timestamp:

04/13/13 05:49:44 (12 years ago)

Author:

István Váradi <ivaradi@…>

Branch:

default

Phase:

public

Message:

The overview documentation of the C++ client library is done

File:

• doc/overview.dox (modified) (2 diffs)

doc/overview.dox

@@ -25 +25 @@
  * computer that runs X-Plane, but extending it with TCP/IP-based or
  * network access would not be difficult. While client libraries are
- * provided for C, C++ and Python, the communication protocol between
- * clients and the plugin is open and is \ref proto "described" in
- * this documentation. So you can write your own client, if you wish.
+ * provided for \ref cpplib "C, C++" and \ref pythonlib "Python",
+ * the communication protocol between clients and the plugin is open
+ * and is \ref proto "described" in  this documentation. So you can
+ * write your own client library, if you wish.
  */
 /*! \page proto Protocol
@@ -698 +699 @@
  * byte | 0x00 (\ref RESULT_OK)
  */
+/*! \page cpplib C/C++ Client Library
+ *
+ * The C++ client library's central class is \ref
+ * hu::varadiistvan::xplra::XPlane. To communicate with the XPLRA
+ * plugin in X-Plane, create an instance of it. This, however, does
+ * not establish the connection yet. To actually connect, call the
+ * \ref hu::varadiistvan::xplra::XPlane::connect "connect" member
+ * function. If the connection is established, it returns otherwise it
+ * throws a \ref hu::varadiistvan::xplra::IOException.
+ *
+ * \c IOException is part of the exception hierarchy of the client
+ * library. The hierarchy begins with \ref
+ * hu::varadiistvan::xplra::Exception. The \c what function is
+ * implemented for all exception classes, so you can always get a
+ * string representation of the problem for logging or to display
+ * it. \c IOException further makes available an error code, which is
+ * the standard operating system-specific fault code of the I/O error
+ * that occured.
+ *
+ * \ref hu::varadiistvan::xplra::ProtocolException is thrown for
+ * errors returned by the plugin usually due to some incorrect
+ * parameter. See also the \ref proto description for the meaning
+ * and applicability of these error codes.
+ *
+ * The \c XPlane object can be reused in the sense, that after you
+ * have made a connection, you can disconnect and then connect
+ * again. This may be useful, if X-Plane crashes for some reason, and
+ * you can then reconnect if the user has restarted it.
+ *
+ * The \ref hu::varadiistvan::xplra::XPlane::createMultiGetter
+ * "createMultiGetter" function can be used to create a multi-dataref
+ * query object. It returns an instance of
+ * \ref hu::varadiistvan::xplra::MultiGetter "MultiGetter", which can
+ * be used to store a number of datarefs and then execute a
+ * multi-dataref query for those datarefs. Before execution, the query
+ * can be \ref hu::varadiistvan::xplra::MultiBuffer::registerInXPlane
+ * "registered" in the plugin, so that the client does not have to send
+ * all the dataref information whenever the query is executed.
+ *
+ * The \c XPlane object knows about any multi-dataref query objects.
+ * Therefore if you register such a multi-dataref query, and then the
+ * connection breaks, and then you reconnect, the query will-be
+ * re-registered too, i.e. you don't have to do it yourself.
+ *
+ * Similarly, the \ref hu::varadiistvan::xplra::XPlane::createMultiSetter
+ * "createMultiSetter" function can be used to create a multi-dataref
+ * update object. They are handled the same way by \c XPlane as the
+ * query objects when it comes to registration and re-registration.
+ *
+ * The other functions of \c XPlane are mostly self-explanatory: they
+ * perform the operations defined by the protocol. Several operations
+ * have more than one corresponding functions with different
+ * parameters for convenience.
+ */
+/*! \page pythonlib Python Client Library
+ *
+ */