ccaosdb.h

#ifdef __cplusplus
extern "C" {
#endif

/**
 * Return the constant caosdb::LIBCAOSDB_VERSION_MAJOR.
 */
int caosdb_constants_LIBCAOSDB_VERSION_MAJOR();
/**
 * Return the constant caosdb::LIBCAOSDB_VERSION_MINOR
 */
int caosdb_constants_LIBCAOSDB_VERSION_MINOR();
/**
 * Return the constant caosdb::LIBCAOSDB_VERSION_PATCH.
 */
int caosdb_constants_LIBCAOSDB_VERSION_PATCH();
/**
 * Return the constant caosdb::COMPATIBLE_SERVER_VERSION_MAJOR.
 */
int caosdb_constants_COMPATIBLE_SERVER_VERSION_MAJOR();
/**
 * Return the constant caosdb::COMPATIBLE_SERVER_VERSION_MINOR.
 */
int caosdb_constants_COMPATIBLE_SERVER_VERSION_MINOR();
/**
 * Return the constant caosdb::COMPATIBLE_SERVER_VERSION_PATCH.
 */
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 fallback instead.
 */
const char *caosdb_utility_get_env_var(const char *name, const char *fallback);

/**
 * Return a description of the status code.
 */
const char *caosdb_get_status_description(int code);

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

/****************************************************************************
 * ENTITY STUFF AND TRANSACTIONS
 ****************************************************************************/

// TODO(fspreck) implementations needed, and probably these declarations are
// not sufficient yet.
typedef struct {
  void *wrapped_transaction;
} caosdb_transaction_transaction;

int caosdb_connection_connection_create_transaction(
  caosdb_connection_connection *connection,
  caosdb_transaction_transaction *out);
int caosdb_transaction_transaction_retrieve_by_id(
  caosdb_transaction_transaction *transaction, const char *id);
int caosdb_transaction_transaction_retrieve_by_ids(
  caosdb_transaction_transaction *transaction, const char *ids[]);
int caosdb_transaction_transaction_query(
  caosdb_transaction_transaction *transaction, const char *query);
int caosdb_transaction_transaction_execute(
  caosdb_transaction_transaction *transaction);
// TODO(fspreck) execute_asynchronously may be added as a separate
// function once we actually support asynchronous execution.

typedef struct {
  void *wrapped_result_set;
} caosdb_transaction_result_set;

int caosdb_transaction_transaction_get_result_set(
  caosdb_transaction_transaction *transaction,
  caosdb_transaction_result_set *out);

int caosdb_transaction_transaction_get_count_result(
  caosdb_transaction_transaction *transaction, long *out);

typedef struct {
  void *wrapped_entity;
  char **id;
  char **role;
  char **name;
  char **description;
  char **datatype;
  char **unit;
  char **value;
  char **version_id;
} caosdb_entity_entity;

int caosdb_transaction_result_set_get_entity(
  caosdb_transaction_result_set *result_set, caosdb_entity_entity *entity,
  int index);

typedef struct {
  void *wrapped_property;
  char **id;
  char **name;
  char **description;
  char **datatype;
  char **unit;
  char **value;
} caosdb_entity_property;
typedef struct {
  void *wrapped_parent;
  char **id;
  char **name;
  char **description;
} caosdb_entity_parent;
typedef struct {
  void *wrapped_message;
  int *code;
  char **description;
} caosdb_entity_message;

// GETTERS FOR COMPLEX OBJECTS
int caosdb_entity_entity_get_errors_size(caosdb_entity_entity *entity,
                                         int *out);
int caosdb_entity_entity_get_error(caosdb_entity_entity *entity,
                                   caosdb_entity_message *out, int index);
int caosdb_entity_entity_get_warnings_size(caosdb_entity_entity *entity,
                                           int *out);
int caosdb_entity_entity_get_warning(caosdb_entity_entity *entity,
                                     caosdb_entity_message *out, int index);
int caosdb_entity_entity_get_infos_size(caosdb_entity_entity *entity, int *out);
int caosdb_entity_entity_get_info(caosdb_entity_entity *entity,
                                  caosdb_entity_message *out, int index);
int caosdb_entity_entity_get_properties_size(caosdb_entity_entity *entity,
                                             int *out);
int caosdb_entity_entity_get_property(caosdb_entity_entity *entity,
                                      caosdb_entity_property *out, int index);
int caosdb_entity_entity_get_parents_size(caosdb_entity_entity *entity,
                                          int *out);
int caosdb_entity_entity_get_parent(caosdb_entity_entity *entity,
                                    caosdb_entity_parent *out, int index);

// CONSTRUCTORS AND DESTRUCTORS
int caosdb_entity_create_entity(caosdb_entity_entity *out);
int caosdb_entity_delete_entity(caosdb_entity_entity *out);
int caosdb_entity_create_property(caosdb_entity_property *out);
int caosdb_entity_delete_property(caosdb_entity_property *out);
int caosdb_entity_create_parent(caosdb_entity_parent *out);
int caosdb_entity_delete_parent(caosdb_entity_parent *out);

// SETTERS FOR COMPLEX OBJECTS
int caosdb_entity_entity_append_parent(caosdb_entity_entity *entity,
                                       caosdb_entity_parent *parent);
int caosdb_entity_entity_append_property(caosdb_entity_entity *entity,
                                         caosdb_entity_property *property);

#ifdef __cplusplus
}
#endif