[#264] cxx bindings for attributes

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)

iceoryx2-ffi/cxx/CMakeLists.txt

@@ -36,6 +36,10 @@ target_include_directories(includes-only-cxx
 # object lib
 
 add_library(iceoryx2-cxx-object-lib OBJECT
+    src/attribute.cpp
+    src/attribute_set.cpp
+    src/attribute_specifier.cpp
+    src/attribute_verifier.cpp
     src/config.cpp
     src/event_id.cpp
     src/file_descriptor.cpp

iceoryx2-ffi/cxx/include/iox2/attribute.hpp

@@ -13,25 +13,39 @@
 #ifndef IOX2_ATTRIBUTE_HPP
 #define IOX2_ATTRIBUTE_HPP
 
-#include "iox/assertions_addendum.hpp"
 #include "iox/string.hpp"
 #include "iox2/internal/iceoryx2.hpp"
 
-#include <string>
-
 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<IOX2_ATTRIBUTE_KEY_LENGTH>;
     using Value = iox::string<IOX2_ATTRIBUTE_VALUE_LENGTH>;
+};
+
+/// 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:
+    friend class AttributeSetView;
+    explicit AttributeView(iox2_attribute_h_ref handle);
 
-    auto key() const -> Key {
-        IOX_TODO();
-    }
-    auto value() const -> Value {
-        IOX_TODO();
-    }
+    iox2_attribute_h_ref m_handle;
 };
 } // namespace iox2
+  //
+auto operator<<(std::ostream& stream, const iox2::AttributeView& value) -> std::ostream&;
 
 #endif

iceoryx2-ffi/cxx/include/iox2/attribute_set.hpp

@@ -13,26 +13,44 @@
 #ifndef IOX2_ATTRIBUTE_SET_HPP
 #define IOX2_ATTRIBUTE_SET_HPP
 
-#include "iox/assertions_addendum.hpp"
-#include "iox/vector.hpp"
+#include "iox/function.hpp"
 #include "iox2/attribute.hpp"
 #include "iox2/internal/iceoryx2.hpp"
 
 #include <iostream>
 
 namespace iox2 {
-class AttributeSet {
+/// 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:
-    auto get(const Attribute::Key& key) const -> iox::vector<Attribute::Value, IOX2_MAX_VALUES_PER_ATTRIBUTE_KEY> {
-        IOX_TODO();
-    }
-};
+    /// 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<CallbackProgression(const Attribute::Value&)>& callback) const;
 
-inline auto operator<<(std::ostream& stream, const AttributeSet& value) -> std::ostream& {
-    stream << "AttributeSet { }";
-    return stream;
-}
+  private:
+    template <ServiceType, typename, typename>
+    friend class PortFactoryPublishSubscribe;
+    template <ServiceType>
+    friend class PortFactoryEvent;
+    friend class AttributeVerifier;
+    friend class AttributeSpecifier;
 
+    explicit AttributeSetView(iox2_attribute_set_h_ref handle);
+
+    iox2_attribute_set_h_ref m_handle;
+};
 } // namespace iox2
 
+auto operator<<(std::ostream& stream, const iox2::AttributeSetView& value) -> std::ostream&;
+
 #endif

iceoryx2-ffi/cxx/include/iox2/attribute_specifier.hpp

@@ -14,17 +14,37 @@
 #define IOX2_ATTRIBUTE_SPECIFIER_HPP
 
 #include "attribute_set.hpp"
-#include "iox/assertions_addendum.hpp"
 
 namespace iox2 {
+
+/// Represents the set of [`Attribute`]s that are defined when the [`Service`]
+/// is created.
 class AttributeSpecifier {
   public:
-    auto define(const Attribute::Key& key, const Attribute::Value& value) -> AttributeSpecifier& {
-        IOX_TODO();
-    }
-    auto attributes() const -> AttributeSet& {
-        IOX_TODO();
-    }
+    /// Creates a new empty set of [`Attribute`]s
+    AttributeSpecifier();
+    AttributeSpecifier(const AttributeSpecifier&) = delete;
+    AttributeSpecifier(AttributeSpecifier&&) noexcept;
+    ~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:
+    template <ServiceType>
+    friend class ServiceBuilderEvent;
+    template <typename, typename, ServiceType>
+    friend class ServiceBuilderPublishSubscribe;
+
+    void drop();
+
+    iox2_attribute_specifier_h m_handle;
 };
 } // namespace iox2
 

iceoryx2-ffi/cxx/include/iox2/attribute_verifier.hpp

@@ -13,33 +13,50 @@
 #ifndef IOX2_ATTRIBUTE_VERIFIER_HPP
 #define IOX2_ATTRIBUTE_VERIFIER_HPP
 
-#include "iox/assertions_addendum.hpp"
 #include "iox/expected.hpp"
 #include "iox/vector.hpp"
 #include "iox2/attribute.hpp"
 #include "iox2/attribute_set.hpp"
 #include "iox2/internal/iceoryx2.hpp"
 
 namespace iox2 {
+/// Represents the set of [`Attribute`]s that are required when the [`Service`]
+/// is opened.
 class AttributeVerifier {
   public:
-    AttributeVerifier() = default;
-    auto require(const Attribute::Key& key, const Attribute::Value& value) -> AttributeVerifier& {
-        IOX_TODO();
-    }
-    auto require_key(const Attribute::Key& key) -> AttributeVerifier& {
-        IOX_TODO();
-    }
-    auto attributes() const -> const AttributeSet& {
-        IOX_TODO();
-    }
-    auto keys() const -> iox::vector<Attribute::Key, IOX2_MAX_ATTRIBUTES_PER_SERVICE> {
-        IOX_TODO();
-    }
-
-    auto verify_requirements(const AttributeSet& rhs) const -> iox::expected<void, Attribute::Key> {
-        IOX_TODO();
-    }
+    /// Creates a new empty set of [`Attribute`]s
+    AttributeVerifier();
+    AttributeVerifier(const AttributeVerifier&) = delete;
+    AttributeVerifier(AttributeVerifier&&) noexcept;
+    ~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<Attribute::Key, IOX2_MAX_ATTRIBUTES_PER_SERVICE>;
+
+    /// Verifies if the [`AttributeSet`] contains all required keys and key-value pairs.
+    auto verify_requirements(const AttributeSetView& rhs) const -> iox::expected<void, Attribute::Key>;
+
+  private:
+    template <ServiceType>
+    friend class ServiceBuilderEvent;
+    template <typename, typename, ServiceType>
+    friend class ServiceBuilderPublishSubscribe;
+
+    void drop();
+
+    iox2_attribute_verifier_h m_handle;
 };
 } // namespace iox2
 

iceoryx2-ffi/cxx/include/iox2/port_factory_event.hpp

@@ -47,7 +47,7 @@ class PortFactoryEvent {
     auto service_id() const -> const ServiceId&;
 
     /// Returns the attributes defined in the [`Service`]
-    auto attributes() const -> const AttributeSet&;
+    auto attributes() const -> AttributeSetView;
 
     /// Returns the StaticConfig of the [`Service`].
     /// Contains all settings that never change during the lifetime of the service.

iceoryx2-ffi/cxx/include/iox2/port_factory_publish_subscribe.hpp

@@ -51,7 +51,7 @@ class PortFactoryPublishSubscribe {
     auto service_id() const -> const ServiceId&;
 
     /// Returns the attributes defined in the [`Service`]
-    auto attributes() const -> const AttributeSet&;
+    auto attributes() const -> AttributeSetView;
 
     /// Returns the StaticConfig of the [`Service`].
     /// Contains all settings that never change during the lifetime of the service.
@@ -132,8 +132,8 @@ inline auto PortFactoryPublishSubscribe<S, Payload, UserHeader>::service_id() co
 }
 
 template <ServiceType S, typename Payload, typename UserHeader>
-inline auto PortFactoryPublishSubscribe<S, Payload, UserHeader>::attributes() const -> const AttributeSet& {
-    IOX_TODO();
+inline auto PortFactoryPublishSubscribe<S, Payload, UserHeader>::attributes() const -> AttributeSetView {
+    return AttributeSetView(iox2_port_factory_pub_sub_attributes(&m_handle));
 }
 
 template <ServiceType S, typename Payload, typename UserHeader>

iceoryx2-ffi/cxx/include/iox2/service_builder_publish_subscribe.hpp

@@ -236,7 +236,16 @@ inline auto ServiceBuilderPublishSubscribe<Payload, UserHeader, S>::open_or_crea
         required_attributes) && -> iox::expected<PortFactoryPublishSubscribe<S, Payload, UserHeader>,
                                                  PublishSubscribeOpenOrCreateError> {
     set_parameters();
-    IOX_TODO();
+
+    iox2_port_factory_pub_sub_h port_factory_handle {};
+    auto result = iox2_service_builder_pub_sub_open_or_create_with_attributes(
+        m_handle, &required_attributes.m_handle, nullptr, &port_factory_handle);
+
+    if (result == IOX2_OK) {
+        return iox::ok(PortFactoryPublishSubscribe<S, Payload, UserHeader>(port_factory_handle));
+    }
+
+    return iox::err(iox::into<PublishSubscribeOpenOrCreateError>(result));
 }
 
 template <typename Payload, typename UserHeader, ServiceType S>
@@ -245,15 +254,33 @@ inline auto ServiceBuilderPublishSubscribe<Payload, UserHeader, S>::open_with_at
         required_attributes) && -> iox::expected<PortFactoryPublishSubscribe<S, Payload, UserHeader>,
                                                  PublishSubscribeOpenError> {
     set_parameters();
-    IOX_TODO();
+
+    iox2_port_factory_pub_sub_h port_factory_handle {};
+    auto result = iox2_service_builder_pub_sub_open_with_attributes(
+        m_handle, &required_attributes.m_handle, nullptr, &port_factory_handle);
+
+    if (result == IOX2_OK) {
+        return iox::ok(PortFactoryPublishSubscribe<S, Payload, UserHeader>(port_factory_handle));
+    }
+
+    return iox::err(iox::into<PublishSubscribeOpenError>(result));
 }
 
 template <typename Payload, typename UserHeader, ServiceType S>
 inline auto ServiceBuilderPublishSubscribe<Payload, UserHeader, S>::create_with_attributes(
     const AttributeSpecifier& attributes) && -> iox::expected<PortFactoryPublishSubscribe<S, Payload, UserHeader>,
                                                               PublishSubscribeCreateError> {
     set_parameters();
-    IOX_TODO();
+
+    iox2_port_factory_pub_sub_h port_factory_handle {};
+    auto result = iox2_service_builder_pub_sub_create_with_attributes(
+        m_handle, &attributes.m_handle, nullptr, &port_factory_handle);
+
+    if (result == IOX2_OK) {
+        return iox::ok(PortFactoryPublishSubscribe<S, Payload, UserHeader>(port_factory_handle));
+    }
+
+    return iox::err(iox::into<PublishSubscribeCreateError>(result));
 }
 } // namespace iox2
 

iceoryx2-ffi/cxx/include/iox2/static_config.hpp

@@ -21,7 +21,7 @@ namespace iox2 {
 class StaticConfig {
   public:
     /// Returns the attributes of the [`Service`]
-    auto attributes() const -> const AttributeSet&;
+    auto attributes() const -> AttributeSetView;
 
     /// Returns the id of the [`Service`]
     auto id() const -> const char*;

iceoryx2-ffi/cxx/src/attribute.cpp

@@ -0,0 +1,39 @@
+// Copyright (c) 2024 Contributors to the Eclipse Foundation
+//
+// See the NOTICE file(s) distributed with this work for additional
+// information regarding copyright ownership.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Apache Software License 2.0 which is available at
+// https://www.apache.org/licenses/LICENSE-2.0, or the MIT license
+// which is available at https://opensource.org/licenses/MIT.
+//
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+
+#include "iox2/attribute.hpp"
+
+namespace iox2 {
+auto AttributeView::key() const -> Attribute::Key {
+    // NOLINTNEXTLINE(hicpp-avoid-c-arrays, cppcoreguidelines-avoid-c-arrays, modernize-avoid-c-arrays) used as an uninitialized buffer
+    char buffer[Attribute::Key::capacity()];
+    iox2_attribute_key(m_handle, &buffer[0], Attribute::Key::capacity());
+    return { iox::TruncateToCapacity, &buffer[0] };
+}
+
+auto AttributeView::value() const -> Attribute::Value {
+    // NOLINTNEXTLINE(hicpp-avoid-c-arrays, cppcoreguidelines-avoid-c-arrays, modernize-avoid-c-arrays) used as an uninitialized buffer
+    char buffer[Attribute::Key::capacity()];
+    iox2_attribute_value(m_handle, &buffer[0], Attribute::Value::capacity());
+
+    return { iox::TruncateToCapacity, &buffer[0] };
+}
+
+AttributeView::AttributeView(iox2_attribute_h_ref handle)
+    : m_handle { handle } {
+}
+} // namespace iox2
+
+auto operator<<(std::ostream& stream, const iox2::AttributeView& value) -> std::ostream& {
+    stream << "Attribute { key = \"" << value.key().c_str() << "\", value = \"" << value.value().c_str() << "\" }";
+    return stream;
+}