From cbe219cbf3f3b96abcea001cc06a4c089582a2d2 Mon Sep 17 00:00:00 2001 From: Christian Eltzschig Date: Mon, 16 Dec 2024 13:22:17 +0100 Subject: [PATCH] [#264] Add documentation --- doc/release-notes/iceoryx2-unreleased.md | 1 + iceoryx2-ffi/cxx/include/iox2/attribute.hpp | 10 ++++ .../cxx/include/iox2/attribute_set.hpp | 10 ++++ .../cxx/include/iox2/attribute_specifier.hpp | 7 +++ .../cxx/include/iox2/attribute_verifier.hpp | 12 ++++ iceoryx2-ffi/ffi/src/api/attribute.rs | 25 +++++++- iceoryx2-ffi/ffi/src/api/attribute_set.rs | 19 ++++++ .../ffi/src/api/attribute_specifier.rs | 26 ++++++++ .../ffi/src/api/attribute_verifier.rs | 59 +++++++++++++++++- .../ffi/src/api/port_factory_event.rs | 6 ++ .../ffi/src/api/port_factory_pub_sub.rs | 6 ++ .../ffi/src/api/service_builder_event.rs | 58 ++++++++++++++++++ .../ffi/src/api/service_builder_pub_sub.rs | 60 ++++++++++++++++++- 13 files changed, 295 insertions(+), 4 deletions(-) diff --git a/doc/release-notes/iceoryx2-unreleased.md b/doc/release-notes/iceoryx2-unreleased.md index f0836d2b..cfb430ba 100644 --- a/doc/release-notes/iceoryx2-unreleased.md +++ b/doc/release-notes/iceoryx2-unreleased.md @@ -11,6 +11,7 @@ conflicts when merging. --> +* C++ bindings for attributes [#264](https://github.com/eclipse-iceoryx/iceoryx2/issues/264) * Add Event-Multiplexer `WaitSet` [#390](https://github.com/eclipse-iceoryx/iceoryx2/issues/390) * Add `PeriodicTimer` into POSIX building blocks [#425](https://github.com/eclipse-iceoryx/iceoryx2/issues/425) * Developer permissions for resources [#460](https://github.com/eclipse-iceoryx/iceoryx2/issues/460) diff --git a/iceoryx2-ffi/cxx/include/iox2/attribute.hpp b/iceoryx2-ffi/cxx/include/iox2/attribute.hpp index 9f68fdaf..4fe5a108 100644 --- a/iceoryx2-ffi/cxx/include/iox2/attribute.hpp +++ b/iceoryx2-ffi/cxx/include/iox2/attribute.hpp @@ -17,15 +17,25 @@ #include "iox2/internal/iceoryx2.hpp" namespace iox2 { +/// Represents a single service attribute (key-value) pair that can be defined when the service +/// is being created. class Attribute { public: using Key = iox::string; using Value = iox::string; }; +/// Represents a single view service attribute (key-value) pair that can be defined when the service +/// is being created. +/// +/// @attention The parent from which the view was extracted MUST live longer than the +/// [`AttributeView`]. class AttributeView { public: + /// Acquires the service attribute key auto key() const -> Attribute::Key; + + /// Acquires the service attribute value auto value() const -> Attribute::Value; private: diff --git a/iceoryx2-ffi/cxx/include/iox2/attribute_set.hpp b/iceoryx2-ffi/cxx/include/iox2/attribute_set.hpp index 02bf0a7d..c451523f 100644 --- a/iceoryx2-ffi/cxx/include/iox2/attribute_set.hpp +++ b/iceoryx2-ffi/cxx/include/iox2/attribute_set.hpp @@ -20,10 +20,20 @@ #include namespace iox2 { +/// Represents all service attributes. They can be set when the service is created. +/// +/// @attention The parent from which the view was extracted MUST live longer than the +/// [`AttributeSetView`]. class AttributeSetView { public: + /// Returns the number of [`Attribute`]s stored inside the [`AttributeSet`]. auto len() const -> uint64_t; + + /// Returns a [`AttributeView`] at a specific index. The number of indices is returned via + /// [`AttributeSetView::len()`]. auto at(uint64_t index) const -> AttributeView; + + /// Returns all values to a specific key void get_key_values(const Attribute::Key& key, const iox::function& callback) const; diff --git a/iceoryx2-ffi/cxx/include/iox2/attribute_specifier.hpp b/iceoryx2-ffi/cxx/include/iox2/attribute_specifier.hpp index 5e57d173..679bee47 100644 --- a/iceoryx2-ffi/cxx/include/iox2/attribute_specifier.hpp +++ b/iceoryx2-ffi/cxx/include/iox2/attribute_specifier.hpp @@ -16,8 +16,12 @@ #include "attribute_set.hpp" namespace iox2 { + +/// Represents the set of [`Attribute`]s that are defined when the [`Service`] +/// is created. class AttributeSpecifier { public: + /// Creates a new empty set of [`Attribute`]s AttributeSpecifier(); AttributeSpecifier(const AttributeSpecifier&) = delete; AttributeSpecifier(AttributeSpecifier&&) noexcept; @@ -26,7 +30,10 @@ class AttributeSpecifier { auto operator=(const AttributeSpecifier&) -> AttributeSpecifier& = delete; auto operator=(AttributeSpecifier&&) noexcept -> AttributeSpecifier&; + /// Defines a value for a specific key. A key is allowed to have multiple values. auto define(const Attribute::Key& key, const Attribute::Value& value) -> AttributeSpecifier&&; + + /// Returns the underlying [`AttributeSetView`] auto attributes() const -> AttributeSetView; private: diff --git a/iceoryx2-ffi/cxx/include/iox2/attribute_verifier.hpp b/iceoryx2-ffi/cxx/include/iox2/attribute_verifier.hpp index d77b74f0..dcb0cd1b 100644 --- a/iceoryx2-ffi/cxx/include/iox2/attribute_verifier.hpp +++ b/iceoryx2-ffi/cxx/include/iox2/attribute_verifier.hpp @@ -20,8 +20,11 @@ #include "iox2/internal/iceoryx2.hpp" namespace iox2 { +/// Represents the set of [`Attribute`]s that are required when the [`Service`] +/// is opened. class AttributeVerifier { public: + /// Creates a new empty set of [`Attribute`]s AttributeVerifier(); AttributeVerifier(const AttributeVerifier&) = delete; AttributeVerifier(AttributeVerifier&&) noexcept; @@ -30,10 +33,19 @@ class AttributeVerifier { auto operator=(const AttributeVerifier&) -> AttributeVerifier& = delete; auto operator=(AttributeVerifier&&) noexcept -> AttributeVerifier&; + /// Requires a value for a specific key. A key is allowed to have multiple values. auto require(const Attribute::Key& key, const Attribute::Value& value) -> AttributeVerifier&&; + + /// Requires that a specific key is defined. auto require_key(const Attribute::Key& key) -> AttributeVerifier&&; + + /// Returns the underlying required [`AttributeSet`] auto attributes() const -> AttributeSetView; + + /// Returns the underlying required keys auto keys() const -> iox::vector; + + /// Verifies if the [`AttributeSet`] contains all required keys and key-value pairs. auto verify_requirements(const AttributeSetView& rhs) const -> iox::expected; private: diff --git a/iceoryx2-ffi/ffi/src/api/attribute.rs b/iceoryx2-ffi/ffi/src/api/attribute.rs index 5093274a..4e1b92fd 100644 --- a/iceoryx2-ffi/ffi/src/api/attribute.rs +++ b/iceoryx2-ffi/ffi/src/api/attribute.rs @@ -33,6 +33,11 @@ pub type iox2_attribute_h_ref = *const iox2_attribute_h_t; // BEGIN C API const ZERO_TERMINATOR_LEN: usize = 1; +/// Returns the length of the attributes key. +/// +/// # Safety +/// +/// * The `handle` must be a valid handle. #[no_mangle] pub unsafe extern "C" fn iox2_attribute_key_len(handle: iox2_attribute_h_ref) -> usize { debug_assert!(!handle.is_null()); @@ -41,6 +46,13 @@ pub unsafe extern "C" fn iox2_attribute_key_len(handle: iox2_attribute_h_ref) -> attribute.key().len() + ZERO_TERMINATOR_LEN } +/// Copies the keys value into the provided buffer. +/// +/// # Safety +/// +/// * `handle` - A valid [`iox2_attribute_h_ref`], +/// * `buffer` - Must be non-null and pointing to a valid memory location, +/// * `buffer_len` - Must be the length of the provided `buffer`. #[no_mangle] pub unsafe extern "C" fn iox2_attribute_key( handle: iox2_attribute_h_ref, @@ -63,6 +75,11 @@ pub unsafe extern "C" fn iox2_attribute_key( } } +/// Returns the length of the attributes value. +/// +/// # Safety +/// +/// * The `handle` must be a valid handle. #[no_mangle] pub unsafe extern "C" fn iox2_attribute_value_len(handle: iox2_attribute_h_ref) -> usize { debug_assert!(!handle.is_null()); @@ -71,6 +88,13 @@ pub unsafe extern "C" fn iox2_attribute_value_len(handle: iox2_attribute_h_ref) attribute.value().len() + ZERO_TERMINATOR_LEN } +/// Copies the values value into the provided buffer. +/// +/// # Safety +/// +/// * `handle` - A valid [`iox2_attribute_h_ref`], +/// * `buffer` - Must be non-null and pointing to a valid memory location, +/// * `buffer_len` - Must be the length of the provided `buffer`. #[no_mangle] pub unsafe extern "C" fn iox2_attribute_value( handle: iox2_attribute_h_ref, @@ -92,5 +116,4 @@ pub unsafe extern "C" fn iox2_attribute_value( 0 } } - // END C API diff --git a/iceoryx2-ffi/ffi/src/api/attribute_set.rs b/iceoryx2-ffi/ffi/src/api/attribute_set.rs index 311e0af0..68346e02 100644 --- a/iceoryx2-ffi/ffi/src/api/attribute_set.rs +++ b/iceoryx2-ffi/ffi/src/api/attribute_set.rs @@ -36,6 +36,12 @@ pub type iox2_attribute_set_get_callback = // END type definition // BEGIN C API + +/// Returns the length of the attribute set. +/// +/// # Safety +/// +/// * The `handle` must be a valid handle. #[no_mangle] pub unsafe extern "C" fn iox2_attribute_set_len(handle: iox2_attribute_set_h_ref) -> usize { debug_assert!(!handle.is_null()); @@ -44,6 +50,12 @@ pub unsafe extern "C" fn iox2_attribute_set_len(handle: iox2_attribute_set_h_ref attribute_set.iter().len() } +/// Returns a [`iox2_attribute_h_ref`] to the attribute stored at the provided index. +/// +/// # Safety +/// +/// * The `handle` must be a valid handle. +/// * The `index` < [`iox2_attribute_set_len()`]. #[no_mangle] pub unsafe extern "C" fn iox2_attribute_set_at( handle: iox2_attribute_set_h_ref, @@ -56,6 +68,13 @@ pub unsafe extern "C" fn iox2_attribute_set_at( (&attribute_set[index] as *const Attribute).cast() } +/// Calls the provided callback for every value that is owned by the provided key. +/// +/// # Safety +/// +/// * The `handle` must be a valid handle. +/// * The `key` must be a valid null-terminated string. +/// * The `callback` must point to a function with the required signature. #[no_mangle] pub unsafe extern "C" fn iox2_attribute_set_get_key_values( handle: iox2_attribute_set_h_ref, diff --git a/iceoryx2-ffi/ffi/src/api/attribute_specifier.rs b/iceoryx2-ffi/ffi/src/api/attribute_specifier.rs index 5cffecde..113ac72d 100644 --- a/iceoryx2-ffi/ffi/src/api/attribute_specifier.rs +++ b/iceoryx2-ffi/ffi/src/api/attribute_specifier.rs @@ -102,6 +102,13 @@ impl HandleToType for iox2_attribute_specifier_h_ref { // BEGIN C API +/// Creates a new [`iox2_attribute_specifier_h`]. It must be cleaned up with +/// [`iox2_attribute_specifier_drop()`]. +/// If the `struct_ptr` is null, then the function will allocate memory. +/// +/// # Safety +/// +/// * The `handle_ptr` must point to an uninitialized [`iox2_attribute_specifier_h`]. #[no_mangle] pub unsafe extern "C" fn iox2_attribute_specifier_new( struct_ptr: *mut iox2_attribute_specifier_t, @@ -128,6 +135,12 @@ pub unsafe extern "C" fn iox2_attribute_specifier_new( IOX2_OK } +/// Deletes a [`iox2_attribute_specifier_h`]. It must be created with +/// [`iox2_attribute_specifier_new()`]. +/// +/// # Safety +/// +/// * The `handle` must point to an initialized [`iox2_attribute_specifier_h`]. #[no_mangle] pub unsafe extern "C" fn iox2_attribute_specifier_drop(handle: iox2_attribute_specifier_h) { debug_assert!(!handle.is_null()); @@ -138,6 +151,13 @@ pub unsafe extern "C" fn iox2_attribute_specifier_drop(handle: iox2_attribute_sp (attribute_specifier.deleter)(attribute_specifier); } +/// Defines a attribute (key / value pair). +/// +/// # Safety +/// +/// * The `handle` must point to an initialized [`iox2_attribute_specifier_h`]. +/// * The `key` must point to a valid null-terminated string. +/// * The `value` must point to a valid null-terminated string. #[no_mangle] pub unsafe extern "C" fn iox2_attribute_specifier_define( handle: iox2_attribute_specifier_h_ref, @@ -160,6 +180,12 @@ pub unsafe extern "C" fn iox2_attribute_specifier_define( )); } +/// Returnes a [`iox2_attribute_set_h_ref`] to the underlying attribute set. +/// +/// # Safety +/// +/// * The `handle` must point to an initialized [`iox2_attribute_specifier_h`]. +/// * The `handle` must live at least as long as the returned [`iox2_attribute_set_h_ref`]. #[no_mangle] pub unsafe extern "C" fn iox2_attribute_specifier_attributes( handle: iox2_attribute_specifier_h_ref, diff --git a/iceoryx2-ffi/ffi/src/api/attribute_verifier.rs b/iceoryx2-ffi/ffi/src/api/attribute_verifier.rs index 8ad49d34..d0fb81bf 100644 --- a/iceoryx2-ffi/ffi/src/api/attribute_verifier.rs +++ b/iceoryx2-ffi/ffi/src/api/attribute_verifier.rs @@ -102,6 +102,13 @@ impl HandleToType for iox2_attribute_verifier_h_ref { // BEGIN C API +/// Creates a new [`iox2_attribute_verifier_h`]. It must be cleaned up with +/// [`iox2_attribute_verifier_drop()`]. +/// If the `struct_ptr` is null, then the function will allocate memory. +/// +/// # Safety +/// +/// * The `handle_ptr` must point to an uninitialized [`iox2_attribute_verifier_h`]. #[no_mangle] pub unsafe extern "C" fn iox2_attribute_verifier_new( struct_ptr: *mut iox2_attribute_verifier_t, @@ -128,6 +135,12 @@ pub unsafe extern "C" fn iox2_attribute_verifier_new( IOX2_OK } +/// Deletes a [`iox2_attribute_verifier_h`]. It must be created with +/// [`iox2_attribute_verifier_new()`]. +/// +/// # Safety +/// +/// * The `handle` must point to an initialized [`iox2_attribute_verifier_h`]. #[no_mangle] pub unsafe extern "C" fn iox2_attribute_verifier_drop(handle: iox2_attribute_verifier_h) { debug_assert!(!handle.is_null()); @@ -138,6 +151,13 @@ pub unsafe extern "C" fn iox2_attribute_verifier_drop(handle: iox2_attribute_ver (attribute_verifier.deleter)(attribute_verifier); } +/// Defines a attribute (key / value pair) that is required. +/// +/// # Safety +/// +/// * The `handle` must point to an initialized [`iox2_attribute_verifier_h`]. +/// * The `key` must point to a valid null-terminated string. +/// * The `value` must point to a valid null-terminated string. #[no_mangle] pub unsafe extern "C" fn iox2_attribute_verifier_require( handle: iox2_attribute_verifier_h_ref, @@ -160,6 +180,12 @@ pub unsafe extern "C" fn iox2_attribute_verifier_require( )); } +/// Defines a key that must be present. +/// +/// # Safety +/// +/// * The `handle` must point to an initialized [`iox2_attribute_verifier_h`]. +/// * The `key` must point to a valid null-terminated string. #[no_mangle] pub unsafe extern "C" fn iox2_attribute_verifier_require_key( handle: iox2_attribute_verifier_h_ref, @@ -179,6 +205,12 @@ pub unsafe extern "C" fn iox2_attribute_verifier_require_key( )); } +/// Returnes a [`iox2_attribute_set_h_ref`] to the underlying attribute set. +/// +/// # Safety +/// +/// * The `handle` must point to an initialized [`iox2_attribute_verifier_h`]. +/// * The `handle` must live at least as long as the returned [`iox2_attribute_set_h_ref`]. #[no_mangle] pub unsafe extern "C" fn iox2_attribute_verifier_attributes( handle: iox2_attribute_verifier_h_ref, @@ -189,6 +221,14 @@ pub unsafe extern "C" fn iox2_attribute_verifier_attributes( (attribute_verifier_struct.value.as_ref().0.attributes() as *const AttributeSet).cast() } +/// Verifies if the [`iox2_attribute_set_h_ref`] contains all required keys and key-value pairs. +/// +/// # Safety +/// +/// * The `handle` must point to an initialized [`iox2_attribute_verifier_h`]. +/// * The `rhs` must be valid. +/// * `incompatible_key_buffer` must be either null or point to a valid memory location of size +/// `incompatible_key_buffer_len` #[no_mangle] pub unsafe extern "C" fn iox2_attribute_verifier_verify_requirements( handle: iox2_attribute_verifier_h_ref, @@ -219,6 +259,11 @@ pub unsafe extern "C" fn iox2_attribute_verifier_verify_requirements( } } +/// Returns the number of required keys. +/// +/// # Safety +/// +/// * The `handle` must point to an initialized [`iox2_attribute_verifier_h`]. #[no_mangle] pub unsafe extern "C" fn iox2_attribute_verifier_number_of_keys( handle: iox2_attribute_verifier_h_ref, @@ -229,6 +274,12 @@ pub unsafe extern "C" fn iox2_attribute_verifier_number_of_keys( attribute_verifier.keys().len() } +/// Returns the length of a required key at a specific key index. +/// +/// # Safety +/// +/// * The `handle` must point to an initialized [`iox2_attribute_verifier_h`]. +/// * `key_index` < [`iox2_attribute_verifier_number_of_keys()`] #[no_mangle] pub unsafe extern "C" fn iox2_attribute_verifier_key_len( handle: iox2_attribute_verifier_h_ref, @@ -242,6 +293,13 @@ pub unsafe extern "C" fn iox2_attribute_verifier_key_len( attribute_verifier.keys()[key_index].len() } +/// Copies the key value at a specific key index into the provided buffer. +/// +/// # Safety +/// +/// * The `handle` must point to an initialized [`iox2_attribute_verifier_h`]. +/// * `key_index` < [`iox2_attribute_verifier_number_of_keys()`] +/// * `key_value_buffer` must point to a valid memory location of size `key_value_buffer_len`. #[no_mangle] pub unsafe extern "C" fn iox2_attribute_verifier_key( handle: iox2_attribute_verifier_h_ref, @@ -270,5 +328,4 @@ pub unsafe extern "C" fn iox2_attribute_verifier_key( 0 } } - // END C API diff --git a/iceoryx2-ffi/ffi/src/api/port_factory_event.rs b/iceoryx2-ffi/ffi/src/api/port_factory_event.rs index f8ca8e2f..f8bc66d2 100644 --- a/iceoryx2-ffi/ffi/src/api/port_factory_event.rs +++ b/iceoryx2-ffi/ffi/src/api/port_factory_event.rs @@ -269,6 +269,12 @@ pub unsafe extern "C" fn iox2_port_factory_event_listener_builder( (*listener_builder_struct_ptr).as_handle() } +/// Returnes the services attributes. +/// +/// # Safety +/// +/// * The `port_factory_handle` is invalid after the return of this function and leads to undefined behavior if used in another function call! +/// * The `port_factory_handle` must live longer than the returned `iox2_attribute_set_h_ref`. #[no_mangle] pub unsafe extern "C" fn iox2_port_factory_event_attributes( port_factory_handle: iox2_port_factory_event_h_ref, diff --git a/iceoryx2-ffi/ffi/src/api/port_factory_pub_sub.rs b/iceoryx2-ffi/ffi/src/api/port_factory_pub_sub.rs index 44f7b5ce..001859e9 100644 --- a/iceoryx2-ffi/ffi/src/api/port_factory_pub_sub.rs +++ b/iceoryx2-ffi/ffi/src/api/port_factory_pub_sub.rs @@ -226,6 +226,12 @@ pub unsafe extern "C" fn iox2_port_factory_pub_sub_subscriber_builder( (*subscriber_builder_struct_ptr).as_handle() } +/// Returnes the services attributes. +/// +/// # Safety +/// +/// * The `port_factory_handle` is invalid after the return of this function and leads to undefined behavior if used in another function call! +/// * The `port_factory_handle` must live longer than the returned `iox2_attribute_set_h_ref`. #[no_mangle] pub unsafe extern "C" fn iox2_port_factory_pub_sub_attributes( port_factory_handle: iox2_port_factory_pub_sub_h_ref, diff --git a/iceoryx2-ffi/ffi/src/api/service_builder_event.rs b/iceoryx2-ffi/ffi/src/api/service_builder_event.rs index d1253490..9ad6e103 100644 --- a/iceoryx2-ffi/ffi/src/api/service_builder_event.rs +++ b/iceoryx2-ffi/ffi/src/api/service_builder_event.rs @@ -298,6 +298,26 @@ pub unsafe extern "C" fn iox2_service_builder_event_open_or_create( ) } +/// Opens an event service or creates the service if it does not exist and returns a port factory to create notifiers and listeners. +/// If the service does not exist, the provided arguments are stored inside the services, if the +/// service already exists, the provided attributes are considered as requirements. +/// +/// # Arguments +/// +/// * `service_builder_handle` - Must be a valid [`iox2_service_builder_event_h`] +/// obtained by [`iox2_service_builder_event`](crate::iox2_service_builder_event) +/// * `port_factory_struct_ptr` - Must be either a NULL pointer or a pointer to a valid +/// [`iox2_port_factory_event_t`]). If it is a NULL pointer, the storage will be allocated on the heap. +/// * `port_factory_handle_ptr` - An uninitialized or dangling [`iox2_port_factory_event_h`] handle which will be initialized by this function call. +/// +/// Returns IOX2_OK on success, an [`iox2_event_open_or_create_error_e`] otherwise. +/// +/// # Safety +/// +/// * The `service_builder_handle` is invalid after the return of this function and leads to undefined behavior if used in another function call! +/// * The corresponding [`iox2_service_builder_t`](crate::iox2_service_builder_t) can be re-used with +/// a call to [`iox2_node_service_builder`](crate::iox2_node_service_builder)! +/// * The `attribute_verifier_handle` must be valid. #[no_mangle] pub unsafe extern "C" fn iox2_service_builder_event_open_or_create_with_attributes( service_builder_handle: iox2_service_builder_event_h, @@ -349,6 +369,25 @@ pub unsafe extern "C" fn iox2_service_builder_event_open( ) } +/// Opens an event service and returns a port factory to create notifiers and listeners. +/// The provided attributes are considered as requirements. +/// +/// # Arguments +/// +/// * `service_builder_handle` - Must be a valid [`iox2_service_builder_event_h`] +/// obtained by [`iox2_service_builder_event`](crate::iox2_service_builder_event) +/// * `port_factory_struct_ptr` - Must be either a NULL pointer or a pointer to a valid +/// [`iox2_port_factory_event_t`]). If it is a NULL pointer, the storage will be allocated on the heap. +/// * `port_factory_handle_ptr` - An uninitialized or dangling [`iox2_port_factory_event_h`] handle which will be initialized by this function call. +/// +/// Returns IOX2_OK on success, an [`iox2_event_open_or_create_error_e`] otherwise. +/// +/// # Safety +/// +/// * The `service_builder_handle` is invalid after the return of this function and leads to undefined behavior if used in another function call! +/// * The corresponding [`iox2_service_builder_t`](crate::iox2_service_builder_t) can be re-used with +/// a call to [`iox2_node_service_builder`](crate::iox2_node_service_builder)! +/// * The `attribute_verifier_handle` must be valid. #[no_mangle] pub unsafe extern "C" fn iox2_service_builder_event_open_with_attributes( service_builder_handle: iox2_service_builder_event_h, @@ -400,6 +439,25 @@ pub unsafe extern "C" fn iox2_service_builder_event_create( ) } +/// Creates a service if it does not exist and returns a port factory to create notifiers and listeners. +/// The provided arguments are stored inside the services. +/// +/// # Arguments +/// +/// * `service_builder_handle` - Must be a valid [`iox2_service_builder_event_h`] +/// obtained by [`iox2_service_builder_event`](crate::iox2_service_builder_event) +/// * `port_factory_struct_ptr` - Must be either a NULL pointer or a pointer to a valid +/// [`iox2_port_factory_event_t`]). If it is a NULL pointer, the storage will be allocated on the heap. +/// * `port_factory_handle_ptr` - An uninitialized or dangling [`iox2_port_factory_event_h`] handle which will be initialized by this function call. +/// +/// Returns IOX2_OK on success, an [`iox2_event_open_or_create_error_e`] otherwise. +/// +/// # Safety +/// +/// * The `service_builder_handle` is invalid after the return of this function and leads to undefined behavior if used in another function call! +/// * The corresponding [`iox2_service_builder_t`](crate::iox2_service_builder_t) can be re-used with +/// a call to [`iox2_node_service_builder`](crate::iox2_node_service_builder)! +/// * The `attribute_verifier_handle` must be valid. #[no_mangle] pub unsafe extern "C" fn iox2_service_builder_event_create_with_attributes( service_builder_handle: iox2_service_builder_event_h, diff --git a/iceoryx2-ffi/ffi/src/api/service_builder_pub_sub.rs b/iceoryx2-ffi/ffi/src/api/service_builder_pub_sub.rs index 6ea7d539..cfabeae2 100644 --- a/iceoryx2-ffi/ffi/src/api/service_builder_pub_sub.rs +++ b/iceoryx2-ffi/ffi/src/api/service_builder_pub_sub.rs @@ -744,8 +744,6 @@ pub unsafe extern "C" fn iox2_service_builder_pub_sub_set_enable_safe_overflow( } } -// TODO [#210] add all the other setter methods - /// Opens a publish-subscribe service or creates the service if it does not exist and returns a port factory to create publishers and subscribers. /// /// # Arguments @@ -778,6 +776,26 @@ pub unsafe extern "C" fn iox2_service_builder_pub_sub_open_or_create( ) } +/// Opens a publish-subscribe service or creates the service if it does not exist and returns a port factory to create publishers and subscribers. +/// If the service does not exist, the provided arguments are stored inside the services, if the +/// service already exists, the provided attributes are considered as requirements. +/// +/// # Arguments +/// +/// * `service_builder_handle` - Must be a valid [`iox2_service_builder_pub_sub_h`] +/// obtained by [`iox2_service_builder_pub_sub`](crate::iox2_service_builder_pub_sub) +/// * `port_factory_struct_ptr` - Must be either a NULL pointer or a pointer to a valid +/// [`iox2_port_factory_pub_sub_t`]. If it is a NULL pointer, the storage will be allocated on the heap. +/// * `port_factory_handle_ptr` - An uninitialized or dangling [`iox2_port_factory_pub_sub_h`] handle which will be initialized by this function call. +/// +/// Returns IOX2_OK on success, an [`iox2_pub_sub_open_or_create_error_e`] otherwise. +/// +/// # Safety +/// +/// * The `service_builder_handle` is invalid after the return of this function and leads to undefined behavior if used in another function call! +/// * The corresponding [`iox2_service_builder_t`](crate::iox2_service_builder_t) can be re-used with +/// a call to [`iox2_node_service_builder`](crate::iox2_node_service_builder)! +/// * The `attribute_verifier_handle` must be valid. #[no_mangle] pub unsafe extern "C" fn iox2_service_builder_pub_sub_open_or_create_with_attributes( service_builder_handle: iox2_service_builder_pub_sub_h, @@ -829,6 +847,25 @@ pub unsafe extern "C" fn iox2_service_builder_pub_sub_open( ) } +/// Opens a publish-subscribe service and returns a port factory to create publishers and subscribers. +/// The provided attributes are considered as requirements. +/// +/// # Arguments +/// +/// * `service_builder_handle` - Must be a valid [`iox2_service_builder_pub_sub_h`] +/// obtained by [`iox2_service_builder_pub_sub`](crate::iox2_service_builder_pub_sub) +/// * `port_factory_struct_ptr` - Must be either a NULL pointer or a pointer to a valid +/// [`iox2_port_factory_pub_sub_t`]. If it is a NULL pointer, the storage will be allocated on the heap. +/// * `port_factory_handle_ptr` - An uninitialized or dangling [`iox2_port_factory_pub_sub_h`] handle which will be initialized by this function call. +/// +/// Returns IOX2_OK on success, an [`iox2_pub_sub_open_or_create_error_e`] otherwise. Note, only the errors annotated with `O_` are relevant. +/// +/// # Safety +/// +/// * The `service_builder_handle` is invalid after the return of this function and leads to undefined behavior if used in another function call! +/// * The corresponding [`iox2_service_builder_t`](crate::iox2_service_builder_t) can be re-used with +/// a call to [`iox2_node_service_builder`](crate::iox2_node_service_builder)! +/// * The `attribute_verifier_handle` must be valid. #[no_mangle] pub unsafe extern "C" fn iox2_service_builder_pub_sub_open_with_attributes( service_builder_handle: iox2_service_builder_pub_sub_h, @@ -880,6 +917,25 @@ pub unsafe extern "C" fn iox2_service_builder_pub_sub_create( ) } +/// Creates a publish-subscribe service and returns a port factory to create publishers and subscribers. +/// The provided arguments are stored inside the services. +/// +/// # Arguments +/// +/// * `service_builder_handle` - Must be a valid [`iox2_service_builder_pub_sub_h`] +/// obtained by [`iox2_service_builder_pub_sub`](crate::iox2_service_builder_pub_sub) +/// * `port_factory_struct_ptr` - Must be either a NULL pointer or a pointer to a valid +/// [`iox2_port_factory_pub_sub_t`]. If it is a NULL pointer, the storage will be allocated on the heap. +/// * `port_factory_handle_ptr` - An uninitialized or dangling [`iox2_port_factory_pub_sub_h`] handle which will be initialized by this function call. +/// +/// Returns IOX2_OK on success, an [`iox2_pub_sub_open_or_create_error_e`] otherwise. Note, only the errors annotated with `C_` are relevant. +/// +/// # Safety +/// +/// * The `service_builder_handle` is invalid after the return of this function and leads to undefined behavior if used in another function call! +/// * The corresponding [`iox2_service_builder_t`](crate::iox2_service_builder_t) can be re-used with +/// a call to [`iox2_node_service_builder`](crate::iox2_node_service_builder)! +/// * The `attribute_verifier_handle` must be valid. #[no_mangle] pub unsafe extern "C" fn iox2_service_builder_pub_sub_create_with_attributes( service_builder_handle: iox2_service_builder_pub_sub_h,