Minimal c interface

Summary

See https://gitlab.indiscale.com/caosdb/customers/lfpb/management/-/issues/404

• Minimal C Interface
• Configuration via json files
• Renaming of many classes and functions (In order to comply with best-practices as formulated by https://google.github.io/styleguide/cppguide.html)

Integration tests are in caosdb-cppinttest!1 (merged)

Focus

• Please take a look at the c-interface functions:
  • I the naming consistent?
  • I see one problem regarding the destructors: When a client uses caosdb_connection_connection_manager_get_default_connection to get the default connection, the destructor caosdb_connection_delete_connection should not be called, because the connection object is actually owned by the ConnectionManager. Maybe, we should prevent the deletion of the wrapped connection somehow, when the connection is owned by the ConnectionManager?
• ConfigurationManager and ConnectionManager:
  • These two singletons are tightly coupled. When the ConfigurationManager is being reset, also the ConnectionManager resets. Is this a good behavior?
• There is currently no error/exception handling in the c-interface. I will add this in https://gitlab.indiscale.com/caosdb/customers/lfpb/management/-/issues/390

Test Environment

Please try and setup a client (e.g. the ccaosdbcli) with a json configuration file.

Check List for the Author

Please, prepare your MR for a review. Be sure to write a summary and a focus and create gitlab comments for the reviewer. They should guide the reviewer through the changes, explain your changes and also point out open questions. For further good practices have a look at our review guidelines

• All automated tests pass
• Reference related Issues
• Up-to-date CHANGELOG.md
• Annotations in code (Gitlab comments)
  • Intent of new code
  • Problems with old code
  • Why this implementation?

Check List for the Reviewer

• I understand the intent of this MR
• All automated tests pass
• Up-to-date CHANGELOG.md
• The test environment setup works and the intended behavior is reproducible in the test environment
• In-code documentation and comments are up-to-date.
• Check: Are there spezifications? Are they satisfied?

For further good practices have a look at our review guidelines.

include/ccaosdb.h

+#ifdef __cplusplus
+extern "C" {
+#else
+#include <stdbool.h>
+#endif
+
+/**
+ * Return the constant caosdb::LIBCAOSDB_VERSION_MAJOR.
+ */
+const int caosdb_constants_LIBCAOSDB_VERSION_MAJOR();
+/**
+ * Return the constant caosdb::LIBCAOSDB_VERSION_MINOR
+ */
+const int caosdb_constants_LIBCAOSDB_VERSION_MINOR();
+/**
+ * Return the constant caosdb::LIBCAOSDB_VERSION_PATCH.
+ */
+const int caosdb_constants_LIBCAOSDB_VERSION_PATCH();
+/**
+ * Return the constant caosdb::COMPATIBLE_SERVER_VERSION_MAJOR.
+ */
+const int caosdb_constants_COMPATIBLE_SERVER_VERSION_MAJOR();
+/**
+ * Return the constant caosdb::COMPATIBLE_SERVER_VERSION_MINOR.
+ */
+const int caosdb_constants_COMPATIBLE_SERVER_VERSION_MINOR();
+/**
+ * Return the constant caosdb::COMPATIBLE_SERVER_VERSION_PATCH.
+ */
+const int caosdb_constants_COMPATIBLE_SERVER_VERSION_PATCH();
+/**
+ * Return the constant caosdb::COMPATIBLE_SERVER_VERSION_PRE_RELEASE.
+ */
+const char *caosdb_constants_COMPATIBLE_SERVER_VERSION_PRE_RELEASE();
+
+/**
+ * A wrapper of the C++ Connection class.
+ *
+ * We use a wrapper for future extensibility and in order to have a minimal
+ * capability for type checking in C even though the C++ class
+ * Connection is opaque in C.
+ */
+typedef struct {
+  void *wrapped_connection;
+} caosdb_connection_connection;
+
+/**
+ * A wrapper of the C++ ConnectionConfiguration class.
+ *
+ * We use a wrapper for future extensibility and in order to have a minimal
+ * capability for type checking in C even though the C++ class
+ * Connection is opaque in C.
+ */
+typedef struct {
+  void *wrapped_connection_configuration;
+} caosdb_connection_connection_configuration;
+
+/**
+ * A wrapper of the C++ VersionInfo class.
+ *
+ * We use a wrapper for future extensibility and in order to have a minimal
+ * capability for type checking in C even though the C++ class
+ * Connection is opaque in C.
+ */
+typedef struct {
+  int major;
+  int minor;
+  int patch;
+  const char *pre_release;
+  const char *build;
+} caosdb_info_version_info;
+
+typedef struct {
+  void *wrapped_certificate_provider;
+} caosdb_connection_certificate_provider;
+
+typedef struct {
+  void *wrapped_authenticator;
+} caosdb_authentication_authenticator;
+
+/**
+ * Return the environment variable of the given name.
+ *
+ * If the environment variable is not set, return the fall_back instead.
+ */
+const char *caosdb_utility_get_env_var(const char *name, const char *fall_back);
+
+/**
+ * Create a pem-file certificate provider.
+ *
+ * Use the destructor function
+ * `caosdb_connection_delete_certificate_provider` to free the wrapped
+ * provider.
+ *
+ * EXPERT USE ONLY.  Memory management with this function is a bit tricky.
+ * Only use it when you know what you are doing.
+ */
+int caosdb_connection_create_pem_file_certificate_provider(
+  caosdb_connection_certificate_provider *out, const char *path);
+
+/**
+ * Destructor function for a certificate provider.
+ *
+ * EXPERT USE ONLY.  Only use it when you know what you are doing.
+ */
+int caosdb_connection_delete_certificate_provider(
+  caosdb_connection_certificate_provider *provider);
+
+/**
+ * Create a tls-secured connection configuration.
+ *
+ * The configuration is needed to instantiate a connection.
+ *
+ * Use the destructor function
+ * `caosdb_connection_delete_connection_configuration` to free the wrapped
+ * configuration.
+ *
+ * EXPERT USE ONLY.  Memory management with this function is a bit tricky.
+ * Only use it when you know what you are doing.
+ */
+int caosdb_connection_create_tls_connection_configuration(
+  caosdb_connection_connection_configuration *out, const char *host,
+  const int port, caosdb_authentication_authenticator *authenticator,
+  caosdb_connection_certificate_provider *provider);
+
+/**
+ * Create a tls-secured connection configuration.
+ *
+ * The configuration is needed to instantiate a connection.
+ *
+ * Use `caosdb_connection_create_tls_connection_configuration` for a
+ * tls-secured connection which also supports authentication.
+ *
+ * Use the destructor function
+ * `caosdb_connection_delete_connection_configuration` to free the wrapped
+ * configuration.
+ *
+ * EXPERT USE ONLY.  Memory management with this function is a bit tricky.
+ * Only use it when you know what you are doing.
+ */
+int caosdb_connection_create_insecure_connection_configuration(
+  caosdb_connection_connection_configuration *out, const char *host,
+  const int port);
+
+/**
+ * Destructor function for the caosdb_connection_connection_configuration
+ * struct.
+ *
+ * EXPERT USE ONLY.  Only use it when you know what you are doing.
+ */
+int caosdb_connection_delete_connection_configuration(
+  caosdb_connection_connection_configuration *configuration);
+
+/**
+ * Add a public certificate of a trusted certificate authority to an
+ * existing, tls-enabled connection configuration.
+ *
+ * @param cacert path to a pem-file.
+ */
+int caosdb_connection_configuration_add_cacert(
+  caosdb_connection_connection_configuration *configuration,
+  const char *cacert);
+
+/**
+ * Create a plain password authenticator.
+ *
+ * Use the destructor function
+ * `caosdb_authentication_delete_authenticator` to free the wrapped
+ * authenticator.
+ *
+ * EXPERT USE ONLY.  Memory management with this function is a bit tricky.
+ * Only use it when you know what you are doing.
+ */
+int caosdb_authentication_create_plain_password_authenticator(
+  caosdb_authentication_authenticator *out, const char *username,
+  const char *password);
+
+/**
+ * Destructor function for the caosdb_authentication_authenticator struct.
+ *
+ * EXPERT USE ONLY.  Only use it when you know what you are doing.
+ */
+int caosdb_authentication_delete_authenticator(
+  caosdb_authentication_authenticator *authenticator);
+
+/**
+ * Create a connection instance.
+ *
+ * The connection is needed to create transactions and to initiate any other
+ * interaction with a CaosDB server.
+ *
+ * Use the destructor function
+ * `caosdb_connection_delete_connection` to free the wrapped
+ * connection.
+ *
+ * EXPERT USE ONLY.  Memory management with this function is a bit tricky.
+ * Only use it when you know what you are doing.
+ */
+int caosdb_connection_create_connection(
+  caosdb_connection_connection *out,
+  const caosdb_connection_connection_configuration *configuration);
+
+/**
+ * Destructor function for the caosdb_connection_connection struct.
+ *
+ * EXPERT USE ONLY.  Only use it when you know what you are doing.
+ */
+int caosdb_connection_delete_connection(
+  caosdb_connection_connection *connection);
+
+/**
+ * Request the version of the server.
+ */
+int caosdb_connection_get_version_info(
+  caosdb_info_version_info *out,
+  const caosdb_connection_connection *connection);
+
+/**
+ * Get the default connection from the ConnectionManager.
+ *
+ * The default connection is to be specified in a configuration file.
+ */
+int caosdb_connection_connection_manager_get_default_connection(
+  caosdb_connection_connection *out);
+
+/**
+ * Get a named connection from the ConnectionManager.
+ *
+ * The named connection is to be specified in a configuration file.
+ */
+int caosdb_connection_connection_manager_get_connection(
+  caosdb_connection_connection *out, const char *name);
+
+#ifdef __cplusplus
+}
+#endif