ENH: Add retrieval and queries to Extern C interface

Summary

See https://gitlab.indiscale.com/caosdb/customers/lfpb/management/-/issues/411. Extends the Extern C interface by retrieving single and multiple entities and executing queries.

Focus

There is a lot of repetitive new code for create, delete, set, and get functions in ccaosdb.cpp. Some aspects of the c++ objects of Entities, Parents, and Propeties had to be changed in order to comply with the C interface, mainly because of memory management.

The most important new parts is that entities, transactions, properties and parents can now be created and deleted via the C interface, and that their properties can be set and gotten.

Test Environment

In principle, unit tests should be sufficient. Check whether you are content with the extent of the tests. Queries and retrievals are checked in the integration tests.

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 specifications? Are they satisfied?

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

include/caosdb/file_transmission/download_request_handler.h

+/*
+ * 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/>.
+ *
+ *********************************************************************************
+ *
+ * This is derived work which is heavily based on
+ * https://github.com/NeiRo21/grpcpp-bidi-streaming, Commit
+ * cd9cb78e5d6d72806c2ec4c703e5e856b223dc96, Aug 10, 2020
+ *
+ * The orginal work is licensed as
+ *
+ * > MIT License
+ * >
+ * > Copyright (c) 2019 NeiRo21
+ * >
+ * > Permission is hereby granted, free of charge, to any person obtaining a
+ * > copy of this software and associated documentation files (the "Software"),
+ * > to deal in the Software without restriction, including without limitation
+ * > the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ * > and/or sell copies of the Software, and to permit persons to whom the
+ * > Software is furnished to do so, subject to the following conditions:
+ * >
+ * > The above copyright notice and this permission notice shall be included in
+ * > all copies or substantial portions of the Software.
+ * >
+ * > THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * > IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * > FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * > AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * > LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * > FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ * > DEALINGS IN THE SOFTWARE.
+ */
+#ifndef CAOSDB_FILE_TRANSMISSION_DOWNLOAD_REQUEST_HANDLER_H
+#define CAOSDB_FILE_TRANSMISSION_DOWNLOAD_REQUEST_HANDLER_H
+
+#include "caosdb/entity.h"                        // for FileDescriptor
+#include "caosdb/entity/v1alpha1/main.grpc.pb.h"  // for FileTransmissionS...
+#include "caosdb/entity/v1alpha1/main.pb.h"       // for FileDownloadResponse
+#include "caosdb/file_transmission/file_writer.h" // for FileWriter
+#include "caosdb/handler_interface.h"             // for HandlerTag, Handl...
+#include <grpcpp/impl/codegen/async_stream.h>     // for ClientAsyncReader
+#include <grpcpp/impl/codegen/client_context.h>   // for ClientContext
+#include <grpcpp/impl/codegen/completion_queue.h> // for CompletionQueue
+#include <grpcpp/impl/codegen/status.h>           // for Status
+#include <memory>                                 // for unique_ptr
+
+namespace caosdb::transaction {
+using caosdb::entity::FileDescriptor;
+using caosdb::entity::v1alpha1::FileDownloadRequest;
+using caosdb::entity::v1alpha1::FileDownloadResponse;
+using caosdb::entity::v1alpha1::FileTransmissionService;
+using caosdb::transaction::HandlerInterface;
+using caosdb::transaction::HandlerTag;
+
+class DownloadRequestHandler final : public HandlerInterface {
+public:
+  DownloadRequestHandler(HandlerTag tag, FileTransmissionService::Stub *stub,
+                         grpc::CompletionQueue *cq,
+                         FileDescriptor file_descriptor);
+
+  ~DownloadRequestHandler() override = default;
+
+  DownloadRequestHandler(const DownloadRequestHandler &) = delete;
+  DownloadRequestHandler &operator=(const DownloadRequestHandler &) = delete;
+  DownloadRequestHandler(DownloadRequestHandler &&) = delete;
+  DownloadRequestHandler &operator=(DownloadRequestHandler &&) = delete;
+
+  void Start() override { OnNext(true); }
+
+  bool OnNext(bool ok) override;
+
+  void Cancel() override;
+
+protected:
+  enum class CallState { NewCall, SendingRequest, ReceivingFile, CallComplete };
+
+  void handleNewCallState();
+  void handleSendingRequestState();
+  void handleReceivingFileState();
+  void handleCallCompleteState();
+
+  HandlerTag tag_;
+
+  FileTransmissionService::Stub *stub_;
+  grpc::CompletionQueue *cq_;
+  grpc::ClientContext ctx_;
+
+  std::unique_ptr<grpc::ClientAsyncReader<FileDownloadResponse>> rpc_;
+
+  FileDownloadRequest *request_;
+  FileDownloadResponse *response_;
+  grpc::Status status_;
+
+  CallState state_;
+
+  std::unique_ptr<FileWriter> fileWriter_;
+
+  FileDescriptor file_descriptor_;
+
+  unsigned long long bytesReceived_;
+};
+
+} // namespace caosdb::transaction
+
+#endif