..
    #
    # This file is a part of the CaosDB Project.
    #
    # Copyright (C) 2021 Timm Fitschen <t.fitschen@indiscale.com>
    # Copyright (C) 2021 IndiScale GmbH <info@indiscale.com>
    #
    # This program is free software: you can redistribute it and/or modify
    # it under the terms of the GNU Affero General Public License as
    # published by the Free Software Foundation, either version 3 of the
    # License, or (at your option) any later version.
    #
    # This program is distributed in the hope that it will be useful,
    # but WITHOUT ANY WARRANTY; without even the implied warranty of
    # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    # GNU Affero General Public License for more details.
    #
    # You should have received a copy of the GNU Affero General Public License
    # along with this program. If not, see <https://www.gnu.org/licenses/>.
    #

.. _capi_root:

=======
 C API
=======

.. warning::

   The C API is intended for developers of other libraries.  Special carre needs to be taken for
   correct memory management.

.. note::

   When working with libcaosdb's C API keep the following in mind:

   Delete all objects (transactions, entities, properties, parents, ...) that you created using a
   call to ``caosdb_..._create_...`` or released using ``caosdb_..._release_...`` and only those.

   Specifically, any objects set by a ``caosdb_..._get_...`` function are managed by another owning
   object (e.g., a connection object is managed by the connection manager) and thus should not be
   deleted manually.

   The underlying reason is that all C++ objects are realized in the
   Extern C interface as mutable structs containing a void pointer to
   the actuall C++ object which is not filled when initializing the
   struct but after calling a create function instead. If the C++
   object wasn't created using a create function, e.g., the parent
   object when getting a parent of an entity, it is owned by another
   object and deleted together with that object.

.. toctree::
    :glob:

    _*
    _*/*