Rpc client u subscription

include/up-cpp/client/usubscription/v3/RequestBuilder.h

@@ -18,12 +18,10 @@
 
 namespace uprotocol::core::usubscription::v3 {
 
-/**
- * @struct USubscriptionOptions
- * @brief Additional details for uSubscription service.
- *
- * Each member represents an optional parameter for the uSubscription service.
- */
+/// @struct USubscriptionOptions
+/// @brief Additional details for uSubscription service.
+///
+/// Each member represents an optional parameter for the uSubscription service.
 struct USubscriptionOptions {
 	/// Permission level of the subscription request
 	std::optional<uint32_t> permission_level;
@@ -39,84 +37,75 @@ struct USubscriptionOptions {
 	std::optional<google::protobuf::Any> subscription_details;
 };
 
-/**
- * @brief Builds different requests using specified options.
- *
- * This struct facilitates the construction of requests based on
- * `USubscriptionOptions`, providing methods to build different requests.
- */
+/// @brief Builds different requests using specified options.
+///
+/// This struct facilitates the construction of requests based on
+/// `USubscriptionOptions`, providing methods to build different requests.
 struct RequestBuilder {
-	/**
-	 * @brief Constructs a RequestBuilder with the given subscription options.
-	 *
-	 * @param options Subscription options to configure the requests. Defaults
-	 * to empty options.
-	 */
+	/// @brief Constructs a RequestBuilder with the given subscription options.
+	///
+	/// @param options Subscription options to configure the requests. Defaults
+	/// to empty options.
 	explicit RequestBuilder(USubscriptionOptions options = {})
 	    : options_(std::move(options)) {}
 
-	/**
-	 * @brief Builds a subscription request for a given topic.
-	 *
-	 * @param topic The `v1::UUri` representing the topic for the subscription.
-	 *
-	 * @return A `SubscriptionRequest` configured for the specified topic.
-	 */
+	/// @brief Sets the permission level for the requests build by the builder
+	///
+	/// @param permission_level to be set
+	/// @return returns a reference to the builder struct to allow chaining
+	RequestBuilder& setPremissionLevel(uint32_t permission_level);
+
+	/// @brief Builds a subscription request for a given topic.
+	///
+	/// @param topic The `v1::UUri` representing the topic for the subscription.
+	///
+	/// @return A `SubscriptionRequest` configured for the specified topic.
 	SubscriptionRequest buildSubscriptionRequest(const v1::UUri& topic) const;
 
-	/**
-	 * @brief Builds an unsubscription request for a given topic.
-	 *
-	 * @param topic The `v1::UUri` representing the topic to unsubscribe from.
-	 *
-	 * @return An `UnsubscribeRequest` configured for the specified topic.
-	 */
-	static UnsubscribeRequest buildUnsubscribeRequest(const v1::UUri& topic);
+	/// @brief Builds an unsubscription request for a given topic.
+	///
+	/// @param topic The `v1::UUri` representing the topic to unsubscribe from.
+	///
+	/// @return An `UnsubscribeRequest` configured for the specified topic.
+	UnsubscribeRequest buildUnsubscribeRequest(const v1::UUri& topic) const;
 
-	/**
-	 * @brief Build fetch subscritions request for a given topic.
-	 *
-	 * @param topic The `v1::UUri` representing the topic to fetch.
-	 *
-	 * @return An `FetchSubscriptionsRequest` configured for the specified
-	 * topic.
-	 */
-	static FetchSubscriptionsRequest buildFetchSubscriptionsRequest(
-	    const v1::UUri& topic);
+	/// @brief Build fetch subscritions request for a given topic.
+	///
+	/// @param topic The `v1::UUri` representing the topic to fetch.
+	///
+	/// @return An `FetchSubscriptionsRequest` configured for the specified
+	/// topic.
+	FetchSubscriptionsRequest buildFetchSubscriptionsRequest(
+	    const v1::UUri& topic) const;
 
-	/**
-	 * @brief Build fetch subscritions request for a given subscriber.
-	 *
-	 * @param subscriber The `SubscriberInfo` representing the subscriber to
-	 * fetch.
-	 *
-	 * @return An `FetchSubscriptionsRequest` configured for the specified
-	 * subscriber.
-	 */
-	static FetchSubscriptionsRequest buildFetchSubscriptionsRequest(
-	    const SubscriberInfo& subscriber);
+	/// @brief Build fetch subscritions request for a given subscriber.
+	///
+	/// @param subscriber The `SubscriberInfo` representing the subscriber to
+	/// fetch.
+	///
+	/// @return An `FetchSubscriptionsRequest` configured for the specified
+	/// subscriber.
+	FetchSubscriptionsRequest buildFetchSubscriptionsRequest(
+	    const SubscriberInfo& subscriber) const;
 
-	/**
-	 * @brief Build fetch subscribers request for a given topic.
-	 *
-	 * @param topic The `v1::UUri` representing the topic to fetch.
-	 *
-	 * @return An `FetchSubscribersRequest` configured for the specified topic.
-	 */
-	static FetchSubscribersRequest buildFetchSubscribersRequest(
-	    const v1::UUri& topic);
+	/// @brief Build fetch subscribers request for a given topic.
+	///
+	/// @param topic The `v1::UUri` representing the topic to fetch.
+	///
+	/// @return An `FetchSubscribersRequest` configured for the specified topic.
+	FetchSubscribersRequest buildFetchSubscribersRequest(
+	    const v1::UUri& topic) const;
 
-	/**
-	 * @brief Build notifications request for a given topic. Subscription change
-	 *notifications MUST use topic SubscriptionsChange with resource id 0x8000,
-	 *as per the protobuf definition.
-	 *
-	 * @param topic The `v1::UUri` representing the topic to (un)register
-	 *for/from.
-	 *
-	 * @return An `NotificationsRequest` configured for the specified topic.
-	 */
-	static NotificationsRequest buildNotificationsRequest(const v1::UUri& topic);
+	/// @brief Build notifications request for a given topic. Subscription
+	/// change
+	/// notifications MUST use topic SubscriptionsChange with resource id
+	/// 0x8000, as per the protobuf definition.
+	///
+	/// @param topic The `v1::UUri` representing the topic to (un)register
+	/// for/from.
+	///
+	/// @return An `NotificationsRequest` configured for the specified topic.
+	NotificationsRequest buildNotificationsRequest(const v1::UUri& topic) const;
 
 private:
 	USubscriptionOptions options_;  ///< Options used to configure the requests.

include/up-cpp/client/usubscription/v3/RpcClientUSubscription.h

@@ -46,10 +46,7 @@ namespace uprotocol::core::usubscription::v3 {
 using v3::SubscriptionRequest;
 using v3::UnsubscribeRequest;
 
-/// @brief Interface for uEntities to create subscriptions.
-///
-/// Like all L3 client APIs, the RpcClientUSubscription is a wrapper on top of
-/// the L2 Communication APIs and USubscription service.
+/// @brief Client which implements the USubscription interface
 struct RpcClientUSubscription : USubscription {
 	using RpcClientUSubscriptionOrStatus =
 	    utils::Expected<std::unique_ptr<RpcClientUSubscription>, v1::UStatus>;
@@ -59,54 +56,69 @@ struct RpcClientUSubscription : USubscription {
 	template <typename Response>
 	Response invokeResponse(communication::RpcClient rpc_client);
 
-	/// @brief Subscribe to the topic
+	/// @brief Subscribes from a given topic
 	///
+	/// @param subscription_request The request object containing the topic to
+	/// subscribe to
+	/// @return Returns a SubscriptionResponse on success and a UStatus else
 	utils::Expected<SubscriptionResponse, v1::UStatus> subscribe(
 	    const SubscriptionRequest& subscription_request) override;
 
-	/// @brief Unsubscribe from the topic
+	/// @brief Unsubscribes from a given topic
 	///
+	/// @param unsubscribe_request The request object containing the topic to
+	/// unsubscribe from
+	/// @return Returns an UnsubscribeResponse on success and a UStatus else
 	utils::Expected<UnsubscribeResponse, v1::UStatus> unsubscribe(
 	    const UnsubscribeRequest& unsubscribe_request) override;
 
-	/// @brief Fetch all subscriptions either by topic or subscriber
+	/// @brief Fetches the list of topics the client is subscribed to
 	///
+	/// @param fetch_subscriptions_request The request object
+	/// @return Returns a FetchSubscriptionsResponse on success and a UStatus
+	/// else
 	utils::Expected<FetchSubscriptionsResponse, v1::UStatus>
 	fetch_subscriptions(
 	    const FetchSubscriptionsRequest& fetch_subscriptions_request) override;
 
-	/// @brief Fetch all subscribers
+	/// @brief Fetches the list of subscribers for a given topic
 	///
+	/// @param fetch_subscribers_request The request object containing the topic
+	/// for which the subscribers are to be fetched
+	/// @return Returns a FetchSubscribersResponse on success and a UStatus else
 	utils::Expected<FetchSubscribersResponse, v1::UStatus> fetch_subscribers(
 	    const FetchSubscribersRequest& fetch_subscribers_request) override;
 
-	/// @brief Register for notifications
+	/// @brief Registers to receive notifications
 	///
+	/// @param register_notifications_request The request object containing
+	///	       the details to register for notifications
+	/// @return Returns a NotificationResponse on success and a UStatus else
 	utils::Expected<NotificationsResponse, v1::UStatus>
 	register_for_notifications(
 	    const NotificationsRequest& register_notifications_request) override;
 
-	/// @brief Unregister for notifications
+	/// @brief Unregisters from receiving notifications.
 	///
+	/// @param unregister_notifications_request The request object containing
+	///        the details needed to stop receiving notifications.
+	/// @return Returns a NotificationResponse on success and a UStatus else
 	utils::Expected<NotificationsResponse, v1::UStatus>
 	unregister_for_notifications(
 	    const NotificationsRequest& unregister_notifications_request) override;
 
 	/// @brief Constructor
 	///
-	/// @param transport Transport to register with.
+	/// @param transport Transport used to send messages
 	explicit RpcClientUSubscription(
 	    std::shared_ptr<transport::UTransport> transport)
 	    : transport_(std::move(transport)) {}
 
-	/// @brief Destructor
 	~RpcClientUSubscription() override = default;
 
 private:
-	// Transport
 	std::shared_ptr<transport::UTransport> transport_;
 
-	// URI info about the uSubscription service
 	USubscriptionUUriBuilder uuri_builder_;
 };
 

include/up-cpp/client/usubscription/v3/USubscription.h

@@ -19,28 +19,59 @@
 
 namespace uprotocol::core::usubscription::v3 {
 
+/// @brief Interface for uEntities to create subscriptions.
+///
+/// Like all L3 client APIs, the RpcClientUSubscription is a wrapper on top of
+/// the L2 Communication APIs and USubscription service.
 struct USubscription {
 	template <typename R>
 	using ResponseOrStatus = utils::Expected<R, v1::UStatus>;
 
 	virtual ~USubscription() = default;
 
+	/// @brief sends a subscription request to a USubscription backend and a
+	/// response on success or else a status code
+	///
+	/// @param subscription_request containing a topic to subscribe to
+	/// @return SubscriptionReponse on success and UStatus else
 	virtual ResponseOrStatus<SubscriptionResponse> subscribe(
 	    const SubscriptionRequest& subscription_request) = 0;
 
+	/// @brief sends an unsubscribe request to a USubscription backend and a
+	/// response on success or else a status code
+	///
+	/// @param unsubscribe_request containing a topic to unsubscribe
+	/// @return UnsubscribeResponse on success and UStatus else
 	virtual ResponseOrStatus<UnsubscribeResponse> unsubscribe(
 	    const UnsubscribeRequest& unsubscribe_request) = 0;
 
+	/// @brief fetches all topics the client is subscribed to from the backend
+	///
+	/// @param fetch_subscriptions_request
+	/// @return FetchSubscriptionsResponse on success and UStatus else
 	virtual ResponseOrStatus<FetchSubscriptionsResponse> fetch_subscriptions(
 	    const FetchSubscriptionsRequest& fetch_subscriptions_request) = 0;
 
+	/// @brief registers for notifications to a USubscription backend
+	///
+	/// @param register_notifications_request
+	/// @return NotificationResponse on success and UStatus else
 	virtual ResponseOrStatus<NotificationsResponse> register_for_notifications(
 	    const NotificationsRequest& register_notifications_request) = 0;
 
+	/// @brief unregisters for notifications to a USubscription backend
+	///
+	/// @param unregister_notifications_request
+	/// @return NotificationResponse on success and UStatus else
 	virtual ResponseOrStatus<NotificationsResponse>
 	unregister_for_notifications(
 	    const NotificationsRequest& unregister_notifications_request) = 0;
 
+	/// @brief fetches all subscribers for a given topic from the backend
+	///
+	/// @param fetch_subscriptions_request containing the topic for which the
+	/// subscribers are fetched
+	/// @return FetchSubscriptionsResponse on success and UStatus else
 	virtual ResponseOrStatus<FetchSubscribersResponse> fetch_subscribers(
 	    const FetchSubscribersRequest& fetch_subscribers_request) = 0;
 };

include/up-cpp/communication/RpcClient.h

@@ -177,28 +177,28 @@ struct RpcClient {
 			return ResponseOrStatus<T>(
 			    UnexpectedStatus(payload_or_status.error()));
 		}
-		datamodel::builder::Payload payload(payload_or_status.value());
 
-		auto message_or_status = this->invokeMethod(std::move(payload)).get();
+		datamodel::builder::Payload tmp_payload(payload_or_status.value());
+
+		auto message_or_status =
+		    this->invokeMethod(std::move(tmp_payload)).get();
 
 		if (!message_or_status.has_value()) {
 			return ResponseOrStatus<T>(
 			    UnexpectedStatus(message_or_status.error()));
 		}
-		
+
 		auto response_or_status = utils::ProtoConverter::extractFromProtobuf<T>(
 		    message_or_status.value());
 
 		if (!response_or_status.has_value()) {
 			spdlog::error(
 			    "invokeProtoMethod: Error when extracting response from "
 			    "protobuf.");
-			return ResponseOrStatus<T>(
-			    UnexpectedStatus(response_or_status.error()));
+			return response_or_status;
 		}
-		T response_message = response_or_status.value();
 
-		return ResponseOrStatus<T>(std::move(response_message));
+		return ResponseOrStatus<T>(response_or_status.value());
 	}
 
 	/// @brief Default move constructor (defined in RpcClient.cpp)