From 0268ed5910a27a11dc4a5da2acee7b09b6615131 Mon Sep 17 00:00:00 2001 From: Julian Oes <julian@oes.ch> Date: Sun, 26 Jan 2025 09:26:29 +1100 Subject: [PATCH] mavsdk_server: document and fixup C API This adds docstrings to the D API and changes the return value of mavsdk_server_run as you would expect a C API, wich 0 being successful. --- .../start_stop_server/start_stop_server.cpp | 7 ++- src/mavsdk_server/src/mavsdk_server_api.cpp | 6 +-- src/mavsdk_server/src/mavsdk_server_api.h | 47 +++++++++++++++++++ src/mavsdk_server/src/mavsdk_server_bin.cpp | 6 +-- 4 files changed, 59 insertions(+), 7 deletions(-) diff --git a/examples/start_stop_server/start_stop_server.cpp b/examples/start_stop_server/start_stop_server.cpp index ce692625fc..d11d2776f5 100644 --- a/examples/start_stop_server/start_stop_server.cpp +++ b/examples/start_stop_server/start_stop_server.cpp @@ -34,7 +34,12 @@ int main(int argc, char* argv[]) mavsdk_server_init(&mavsdk_server); // This returns when a system has been discovered. - mavsdk_server_run(mavsdk_server, argv[1], 50051); + int ret = mavsdk_server_run(mavsdk_server, argv[1], 50051); + if (ret != 0) { + std::cout << "mavsdk_server_run failed: " << ret << std::endl; + mavsdk_server_destroy(mavsdk_server); + return ret; + } while (!_should_stop.load()) { std::this_thread::sleep_for(std::chrono::seconds(1)); diff --git a/src/mavsdk_server/src/mavsdk_server_api.cpp b/src/mavsdk_server/src/mavsdk_server_api.cpp index 5cd3ba9ce2..f86d5d71b2 100644 --- a/src/mavsdk_server/src/mavsdk_server_api.cpp +++ b/src/mavsdk_server/src/mavsdk_server_api.cpp @@ -12,16 +12,16 @@ int mavsdk_server_run( { if (!mavsdk_server->connect(std::string(system_address))) { // Connection was cancelled - return false; + return 1; } auto grpc_port = mavsdk_server->startGrpcServer(mavsdk_server_port); if (grpc_port == 0) { // Server failed to start - return false; + return 2; } - return true; + return 0; } int mavsdk_server_run_with_mavlink_ids( diff --git a/src/mavsdk_server/src/mavsdk_server_api.h b/src/mavsdk_server/src/mavsdk_server_api.h index 11c2c75aa3..2a98175bd6 100644 --- a/src/mavsdk_server/src/mavsdk_server_api.h +++ b/src/mavsdk_server/src/mavsdk_server_api.h @@ -18,11 +18,37 @@ extern "C" { struct MavsdkServer; +/* + * Allocate and initialize MavsdkServer struct. + * + * @param mavsdk_server Pointer to pointer to MavsdkServer. + */ DLLExport void mavsdk_server_init(struct MavsdkServer** mavsdk_server); +/* + * Run MavsdkServer. + * + * @param mavsdk_server Pointer to initialized MavsdkServer + * @param system_address Connection string for MAVLink as used by add_any_connection + * @param mavsdk_server_port gRPC server port + * @return 0 if successful + */ DLLExport int mavsdk_server_run( struct MavsdkServer* mavsdk_server, const char* system_address, const int mavsdk_server_port); +/* + * Run MavsdkServer. + * + * Note: This function immediately returns. To wait until the server exits, + * use mavsdk_server_attach. + * + * @param mavsdk_server Pointer to initialized MavsdkServer + * @param system_address Connection string for MAVLink as used by add_any_connection + * @param mavsdk_server_port gRPC server port + * @param system_id MAVLink system ID for MAVSDK + * @param component_id MAVLink component ID for MAVSDK + * @return 0 if successful + */ DLLExport int mavsdk_server_run_with_mavlink_ids( struct MavsdkServer* mavsdk_server, const char* system_address, @@ -30,12 +56,33 @@ DLLExport int mavsdk_server_run_with_mavlink_ids( const uint8_t system_id, const uint8_t component_id); +/* + * Get gRPC port. + * + * @param mavsdk_server Pointer to initialized MavsdkServer + * @return gRPC port used + */ DLLExport int mavsdk_server_get_port(struct MavsdkServer* mavsdk_server); +/* + * Attach to MavsdkServer. This only returns once the server is stopped. + * + * @param mavsdk_server Pointer to initialized MavsdkServer + */ DLLExport void mavsdk_server_attach(struct MavsdkServer* mavsdk_server); +/* + * Stop MavsdkServer. + * + * @param mavsdk_server Pointer to initialized MavsdkServer + */ DLLExport void mavsdk_server_stop(struct MavsdkServer* mavsdk_server); +/* + * Clean up MavsdkServer object. Counter part to mavsdk_server_init. + * + * @param mavsdk_server Pointer to initialized MavsdkServer + */ DLLExport void mavsdk_server_destroy(struct MavsdkServer* mavsdk_server); #ifdef __cplusplus diff --git a/src/mavsdk_server/src/mavsdk_server_bin.cpp b/src/mavsdk_server/src/mavsdk_server_bin.cpp index 29bb74728c..8bb42e264e 100644 --- a/src/mavsdk_server/src/mavsdk_server_bin.cpp +++ b/src/mavsdk_server/src/mavsdk_server_bin.cpp @@ -88,17 +88,17 @@ int main(int argc, char** argv) MavsdkServer* mavsdk_server; mavsdk_server_init(&mavsdk_server); - const auto is_started = mavsdk_server_run_with_mavlink_ids( + const int ret = mavsdk_server_run_with_mavlink_ids( mavsdk_server, connection_url.c_str(), mavsdk_server_port, static_cast<uint8_t>(mavsdk_sysid), static_cast<uint8_t>(mavsdk_compid)); - if (!is_started) { + if (ret != 0) { std::cout << "Failed to start, exiting...\n"; mavsdk_server_destroy(mavsdk_server); - return 1; + return ret; } mavsdk_server_attach(mavsdk_server);