From 17e70467834f080d8fe732de84378a5fd806f4d4 Mon Sep 17 00:00:00 2001
From: DenisBiryukov91 <155981813+DenisBiryukov91@users.noreply.github.com>
Date: Thu, 19 Dec 2024 15:51:46 +0100
Subject: [PATCH] add missing (advanced)subscriber methods (#871)

---
 docs/api.rst               |  3 +++
 include/zenoh_commons.h    | 28 ++++++++++++++++++++++++++--
 src/advanced_subscriber.rs | 26 ++++++++++++++++++++++++--
 src/subscriber.rs          | 10 +++++++++-
 4 files changed, 62 insertions(+), 5 deletions(-)

diff --git a/docs/api.rst b/docs/api.rst
index 45abfd99d..ed3724c53 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -570,6 +570,7 @@ Functions
 .. doxygenfunction:: z_undeclare_subscriber
 .. doxygenfunction:: z_declare_background_subscriber
 .. doxygenfunction:: z_subscriber_keyexpr
+.. doxygenfunction:: z_subscriber_id
 
 .. doxygenfunction:: z_subscriber_drop
 
@@ -993,6 +994,8 @@ Functions
 .. doxygenfunction:: ze_declare_advanced_subscriber
 .. doxygenfunction:: ze_declare_background_advanced_subscriber
 .. doxygenfunction:: ze_undeclare_advanced_subscriber
+.. doxygenfunction:: ze_advanced_subscriber_keyexpr
+.. doxygenfunction:: ze_advanced_subscriber_id
 
 .. doxygenfunction:: ze_advanced_subscriber_detect_publishers
 .. doxygenfunction:: ze_advanced_subscriber_detect_publishers_background
diff --git a/include/zenoh_commons.h b/include/zenoh_commons.h
index 61927748b..b148abf66 100644
--- a/include/zenoh_commons.h
+++ b/include/zenoh_commons.h
@@ -1091,7 +1091,7 @@ typedef struct ze_advanced_publisher_put_options_t {
 #endif
 /**
  * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
- * @brief A struct that represent missed samples.
+ * @brief A struct that represents missed samples.
  */
 #if defined(Z_FEATURE_UNSTABLE_API)
 typedef struct ze_miss_t {
@@ -4750,6 +4750,14 @@ ZENOHC_API const struct z_loaned_string_t *z_string_loan(const struct z_owned_st
  * This is equivalent to calling `z_undeclare_subscriber()` and discarding its return value.
  */
 ZENOHC_API void z_subscriber_drop(struct z_moved_subscriber_t *this_);
+/**
+ * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
+ * @brief Returns the ID of the subscriber.
+ */
+#if defined(Z_FEATURE_UNSTABLE_API)
+ZENOHC_API
+struct z_entity_global_id_t z_subscriber_id(const struct z_loaned_subscriber_t *subscriber);
+#endif
 /**
  * Returns the key expression of the subscriber.
  */
@@ -5655,7 +5663,7 @@ z_result_t ze_advanced_subscriber_declare_sample_miss_listener(const struct ze_l
 #endif
 /**
  * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
- * @brief Declares a subscriber on liveliness tokens for matching publishers detection. Only advanced publishers. enabling publisher detection can be detected.
+ * @brief Declares a liveliness token listener for matching publishers detection. Only advanced publishers, enabling publisher detection can be detected.
  *
  * @param subscriber: The advanced subscriber instance.
  * @param liveliness_subscriber: An uninitialized memory location where liveliness subscriber will be constructed.
@@ -5703,6 +5711,22 @@ void ze_advanced_subscriber_drop(struct ze_moved_advanced_subscriber_t *this_);
 ZENOHC_API
 void ze_advanced_subscriber_history_options_default(struct ze_advanced_subscriber_history_options_t *this_);
 #endif
+/**
+ * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
+ * @brief Returns the ID of the advanced subscriber.
+ */
+#if (defined(Z_FEATURE_UNSTABLE_API) && defined(Z_FEATURE_UNSTABLE_API))
+ZENOHC_API
+struct z_entity_global_id_t ze_advanced_subscriber_id(const struct ze_loaned_advanced_subscriber_t *subscriber);
+#endif
+/**
+ * @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
+ * Returns the key expression of the advanced subscriber.
+ */
+#if defined(Z_FEATURE_UNSTABLE_API)
+ZENOHC_API
+const struct z_loaned_keyexpr_t *ze_advanced_subscriber_keyexpr(const struct ze_loaned_advanced_subscriber_t *subscriber);
+#endif
 /**
  * Borrows subscriber.
  */
diff --git a/src/advanced_subscriber.rs b/src/advanced_subscriber.rs
index afb7d1bf5..2ab18225d 100644
--- a/src/advanced_subscriber.rs
+++ b/src/advanced_subscriber.rs
@@ -318,7 +318,7 @@ pub extern "C" fn ze_undeclare_advanced_subscriber(
 }
 
 /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
-/// @brief A struct that represent missed samples.
+/// @brief A struct that represents missed samples.
 #[repr(C)]
 pub struct ze_miss_t {
     /// The source of missed samples.
@@ -465,7 +465,7 @@ fn _advanced_subscriber_detect_publishers_inner(
 }
 
 /// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
-/// @brief Declares a subscriber on liveliness tokens for matching publishers detection. Only advanced publishers. enabling publisher detection can be detected.
+/// @brief Declares a liveliness token listener for matching publishers detection. Only advanced publishers, enabling publisher detection can be detected.
 ///
 /// @param subscriber: The advanced subscriber instance.
 /// @param liveliness_subscriber: An uninitialized memory location where liveliness subscriber will be constructed.
@@ -518,3 +518,25 @@ pub extern "C" fn ze_advanced_subscriber_detect_publishers_background(
         }
     }
 }
+
+/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
+/// Returns the key expression of the advanced subscriber.
+#[no_mangle]
+pub extern "C" fn ze_advanced_subscriber_keyexpr(
+    subscriber: &ze_loaned_advanced_subscriber_t,
+) -> &z_loaned_keyexpr_t {
+    subscriber
+        .as_rust_type_ref()
+        .key_expr()
+        .as_loaned_c_type_ref()
+}
+
+#[cfg(feature = "unstable")]
+/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
+/// @brief Returns the ID of the advanced subscriber.
+#[no_mangle]
+pub extern "C" fn ze_advanced_subscriber_id(
+    subscriber: &ze_loaned_advanced_subscriber_t,
+) -> z_entity_global_id_t {
+    subscriber.as_rust_type_ref().id().into_c_type()
+}
diff --git a/src/subscriber.rs b/src/subscriber.rs
index 542d78069..026b9f6b9 100644
--- a/src/subscriber.rs
+++ b/src/subscriber.rs
@@ -29,7 +29,7 @@ use crate::{
     z_closure_sample_call, z_closure_sample_loan, z_loaned_session_t, z_moved_closure_sample_t,
 };
 #[cfg(feature = "unstable")]
-use crate::{zc_locality_default, zc_locality_t};
+use crate::{transmute::IntoCType, z_entity_global_id_t, zc_locality_default, zc_locality_t};
 
 decl_c_type!(
     owned(z_owned_subscriber_t, option Subscriber<()>),
@@ -205,3 +205,11 @@ pub extern "C" fn z_undeclare_subscriber(this_: &mut z_moved_subscriber_t) -> re
     }
     result::Z_OK
 }
+
+#[cfg(feature = "unstable")]
+/// @warning This API has been marked as unstable: it works as advertised, but it may be changed in a future release.
+/// @brief Returns the ID of the subscriber.
+#[no_mangle]
+pub extern "C" fn z_subscriber_id(subscriber: &z_loaned_subscriber_t) -> z_entity_global_id_t {
+    subscriber.as_rust_type_ref().id().into_c_type()
+}