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::sync::Arc;
15
16use async_trait::async_trait;
17use thiserror::Error;
18
19use crate::{UListener, UStatus, UUri};
20
21use super::{CallOptions, RegistrationError, UPayload};
22
23/// An error indicating a problem with sending a notification to another uEntity.
24// [impl->dsn~communication-layer-api-declaration~1]
25#[derive(Debug, Error)]
26pub enum NotificationError {
27    /// Indicates that the given message cannot be sent because it is not a
28    /// [valid Notification message](crate::UAttributesValidators::Notification).
29    #[error("invalid argument: {0}")]
30    InvalidArgument(String),
31    /// Indicates an unspecific error that occurred at the Transport Layer while trying to send a notification.
32    #[error("failed to send notification: {0}")]
33    NotifyError(Box<UStatus>),
34}
35
36/// A client for sending Notification messages to a uEntity.
37///
38/// Please refer to the
39/// [Communication Layer API Specifications](https://github.com/eclipse-uprotocol/up-spec/blob/main/up-l2/api.adoc).
40// [impl->dsn~communication-layer-api-declaration~1]
41#[cfg_attr(any(test, feature = "test-util"), mockall::automock)]
42#[async_trait]
43pub trait Notifier: Send + Sync {
44    /// Sends a notification to a uEntity.
45    ///
46    /// # Arguments
47    ///
48    /// * `resource_id` - The (local) resource identifier representing the origin of the notification.
49    /// * `destination` - A URI representing the uEntity that the notification should be sent to.
50    /// * `call_options` - Options to include in the notification message.
51    /// * `payload` - The payload to include in the notification message.
52    ///
53    /// # Errors
54    ///
55    /// Returns an error if the given message is not a valid
56    /// [uProtocol Notification message](`crate::UAttributesValidators::Notification`).
57    async fn notify(
58        &self,
59        resource_id: u16,
60        destination: &UUri,
61        call_options: CallOptions,
62        payload: Option<UPayload>,
63    ) -> Result<(), NotificationError>;
64
65    /// Starts listening to a notification topic.
66    ///
67    /// More than one handler can be registered for the same topic.
68    /// The same handler can be registered for multiple topics.
69    ///
70    /// # Arguments
71    ///
72    /// * `topic` - The topic to listen to. The topic must not contain any wildcards.
73    /// * `listener` - The handler to invoke for each notification that has been sent on the topic.
74    ///
75    /// # Errors
76    ///
77    /// Returns an error if the listener cannot be registered.
78    async fn start_listening(
79        &self,
80        topic: &UUri,
81        listener: Arc<dyn UListener>,
82    ) -> Result<(), RegistrationError>;
83
84    /// Deregisters a previously [registered handler](`Self::start_listening`) for listening to notifications.
85    ///
86    /// # Arguments
87    ///
88    /// * `topic` - The topic that the handler had been registered for.
89    /// * `listener` - The handler to unregister.
90    ///
91    /// # Errors
92    ///
93    /// Returns an error if the listener cannot be unregistered.
94    async fn stop_listening(
95        &self,
96        topic: &UUri,
97        listener: Arc<dyn UListener>,
98    ) -> Result<(), RegistrationError>;
99}
up_rust/communication/notification.rs

up_rust/communication/
notification.rs
