up_rust/communication/
notification.rs

1/********************************************************************************
2 * Copyright (c) 2024 Contributors to the Eclipse Foundation
3 *
4 * See the NOTICE file(s) distributed with this work for additional
5 * information regarding copyright ownership.
6 *
7 * This program and the accompanying materials are made available under the
8 * terms of the Apache License Version 2.0 which is available at
9 * https://www.apache.org/licenses/LICENSE-2.0
10 *
11 * SPDX-License-Identifier: Apache-2.0
12 ********************************************************************************/
13
14use std::{error::Error, fmt::Display, sync::Arc};
15
16use async_trait::async_trait;
17
18use crate::communication::RegistrationError;
19use crate::{UListener, UStatus, UUri};
20
21use super::{CallOptions, UPayload};
22
23/// An error indicating a problem with sending a notification to another uEntity.
24// [impl->req~up-language-comm-api~1]
25#[derive(Debug)]
26pub enum NotificationError {
27    /// Indicates that the given message cannot be sent because it is not a [valid Notification message](crate::NotificationValidator).
28    InvalidArgument(String),
29    /// Indicates an unspecific error that occurred at the Transport Layer while trying to send a notification.
30    NotifyError(UStatus),
31}
32
33impl Display for NotificationError {
34    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
35        match self {
36            NotificationError::InvalidArgument(s) => f.write_str(s.as_str()),
37            NotificationError::NotifyError(s) => {
38                f.write_fmt(format_args!("failed to send notification: {}", s))
39            }
40        }
41    }
42}
43
44impl Error for NotificationError {}
45
46/// A client for sending Notification messages to a uEntity.
47///
48/// Please refer to the
49/// [Communication Layer API Specifications](https://github.com/eclipse-uprotocol/up-spec/blob/main/up-l2/api.adoc).
50// [impl->req~up-language-comm-api~1]
51#[cfg_attr(any(test, feature = "test-util"), mockall::automock)]
52#[async_trait]
53pub trait Notifier: Send + Sync {
54    /// Sends a notification to a uEntity.
55    ///
56    /// # Arguments
57    ///
58    /// * `resource_id` - The (local) resource identifier repesenting the origin of the notification.
59    /// * `destination` - A URI representing the uEntity that the notification should be sent to.
60    /// * `call_options` - Options to include in the notification message.
61    /// * `payload` - The payload to include in the notification message.
62    ///
63    /// # Errors
64    ///
65    /// Returns an error if the given message is not a valid
66    /// [uProtocol Notification message](`crate::NotificationValidator`).
67    async fn notify(
68        &self,
69        resource_id: u16,
70        destination: &UUri,
71        call_options: CallOptions,
72        payload: Option<UPayload>,
73    ) -> Result<(), NotificationError>;
74
75    /// Starts listening to a notification topic.
76    ///
77    /// More than one handler can be registered for the same topic.
78    /// The same handler can be registered for multiple topics.
79    ///
80    /// # Arguments
81    ///
82    /// * `topic` - The topic to listen to. The topic must not contain any wildcards.
83    /// * `listener` - The handler to invoke for each notification that has been sent on the topic.
84    ///
85    /// # Errors
86    ///
87    /// Returns an error if the listener cannot be registered.
88    async fn start_listening(
89        &self,
90        topic: &UUri,
91        listener: Arc<dyn UListener>,
92    ) -> Result<(), RegistrationError>;
93
94    /// Unregisters a previously [registered handler](`Self::start_listening`) for listening to notifications.
95    ///
96    /// # Arguments
97    ///
98    /// * `topic` - The topic that the handler had been registered for.
99    /// * `listener` - The handler to unregister.
100    ///
101    /// # Errors
102    ///
103    /// Returns an error if the listener cannot be unregistered.
104    async fn stop_listening(
105        &self,
106        topic: &UUri,
107        listener: Arc<dyn UListener>,
108    ) -> Result<(), RegistrationError>;
109}
up_rust/communication/notification.rs

up_rust/communication/
notification.rs
