Adding subscriptions client header

include/up-cpp/client/usubscription/SubscriptionClient.h

@@ -0,0 +1,97 @@
+// SPDX-FileCopyrightText: 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 License Version 2.0 which is available at
+// https://www.apache.org/licenses/LICENSE-2.0
+//
+// SPDX-License-Identifier: Apache-2.0
+
+#ifndef UP_CPP_CLIENT_SubscriptionClient_H
+#define UP_CPP_CLIENT_SubscriptionClient_H
+
+#include <up-cpp/communication/Subscriber.h>
+#include <uprotocol/v1/umessage.pb.h>
+
+#include <optional>
+#include <uprotocol/core/usubscription/v3/usubscription.proto>
+#include <utility>
+
+namespace uprotocol::client::usubscription {
+/// @brief Interface for uEntities to create subscriptions.
+///
+/// Like all L3 client APIs, the SubscriptionClient is a wrapper on top of the
+/// L2 Communication APIs and USubscription service.
+struct SubscriptionClient {
+	using SubscriptionClientOrStatus =
+	    utils::Expected<std::unique_ptr<SubscriptionClient>, v1::UStatus>;
+	using ListenCallback = transport::UTransport::ListenCallback;
+	using ListenHandle = transport::UTransport::ListenHandle;
+	using SubscriptionResponse = core::usubscription::v3::SubscriptionResponse;
+
+	/// @brief Create a subscription
+	///
+	/// @param topic Topic to subscribe to.
+	/// @param callback Function that is called when a message is received.
+	/// @param ttl Time to live for the subscription.
+	/// @param sample_period_ms Sample period of messages for remote only
+	/// subscriptions.
+	/// @param subscription_details Additional details about the
+	/// subscription.
+	/// @param subscriber_details Additional details about the subscriber.
+	[[nodiscard]] SubscriptionClientOrStatus create(
+	    std::shared_ptr<transport::UTransport> transport, const v1::UUri& topic,
+	    ListenCallback&& callback,
+	    std::optional<std::chrono::milliseconds>&& ttl = {},
+	    std::optional<uint32_t>&& sample_period_ms = {},
+	    std::optional<google::protobuf::Any>&& subscription_details = {},
+	    std::optional<google::protobuf::Any> subscriber_details = {});
+
+	/// @brief get subscription response
+	///
+	/// @returns SubscriptionResponse provided by uSubscription service
+	SubscriptionResponse getSubscriptionResponse() const {
+		return subscription_response_;
+	}
+
+	/// @brief Destructor
+	///
+	/// Calls unsubscribe() to uSubscription service to close the subscription.
+	~SubscriptionClient() { unsubscribe(); }
+
+protected:
+	/// @brief Constructor
+	///
+	/// @param transport Transport to register with.
+	/// @param subscriber_details Additional details about the subscriber.
+	SubscriptionClient(
+	    std::shared_ptr<transport::UTransport> transport,
+	    const v1::UUri& subscription_topic,
+	    std::optional<google::protobuf::Any> subscriber_details = {});
+
+private:
+	std::shared_ptr<transport::UTransport> transport_;
+	ListenHandle subscription_;
+	SubscriptionResponse subscription_response_;
+	const v1::UUri subscription_topic_;
+	std::optional<google::protobuf::Any> subscriber_details_;
+
+	// Allow the protected constructor for this class to be used in make_unique
+	// inside of create()
+	friend std::unique_ptr<SubscriptionClient>
+	std::make_unique<SubscriptionClient, std::shared_ptr<transport::UTransport>,
+	                 const v1::UUri, std::optional<google::protobuf::Any>>(
+	    std::shared_ptr<uprotocol::transport::UTransport>&&, const v1::UUri&&,
+	    std::optional<google::protobuf::Any>&&);
+
+	/// @brief Unsubscribe from the topic
+	///
+	/// call uSubscription service to close the subscription.
+	void unsubscribe();
+};
+
+}  // namespace uprotocol::client::usubscription
+
+#endif  // UP_CPP_CLIENT_SubscriptionClient_H