libcoap_rs/
event.rs

1// SPDX-License-Identifier: BSD-2-Clause
2/*
3 * event.rs - Event handling traits and logic for the libcoap Rust Wrapper.
4 * This file is part of the libcoap-rs crate, see the README and LICENSE files for
5 * more information and terms of use.
6 * Copyright © 2021-2023 The NAMIB Project Developers, all rights reserved.
7 * See the README as well as the LICENSE file for more information.
8 */
9
10//! Event handling-related code
11
12use std::fmt::Debug;
13
14use libcoap_sys::{coap_event_t, coap_session_get_context, coap_session_t};
15
16use crate::context::CoapContext;
17use crate::session::CoapSession;
18
19use crate::session::CoapServerSession;
20
21/// Trait for CoAP event handlers.
22///
23/// Implementations of this trait can be provided to a [CoapContext] to handle various events relating
24/// to sessions.
25///
26/// This is the equivalent to the [libcoap `coap_event_handler_t` type](https://libcoap.net/doc/reference/develop/group__events.html#ga5d57fba7df54eae6f8cb3a47a4cb3569).
27pub trait CoapEventHandler: Debug {
28    /// Handle a DTLS connected event.
29    ///
30    /// This event is triggered when a DTLS session switches to the connected state.
31    #[allow(unused_variables)]
32    fn handle_dtls_connected(&mut self, session: &mut CoapSession) {}
33
34    /// Handle a DTLS closed event.
35    ///
36    /// This event is triggered when a DTLS session is closed.
37    #[allow(unused_variables)]
38    fn handle_dtls_closed(&mut self, session: &mut CoapSession) {}
39
40    /// Handle a DTLS renegotiation event.
41    ///
42    /// This event is triggered when a DTLS renegotiation occurs.
43    #[allow(unused_variables)]
44    fn handle_dtls_renegotiate(&mut self, session: &mut CoapSession) {}
45
46    /// Handle a DTLS error event.
47    ///
48    /// This event is triggered when a DTLS error occurs.
49    #[allow(unused_variables)]
50    fn handle_dtls_error(&mut self, session: &mut CoapSession) {}
51
52    /// Handle a TCP connected event.
53    ///
54    /// This event is triggered when a new TCP connection is established.
55    #[allow(unused_variables)]
56    fn handle_tcp_connected(&mut self, session: &mut CoapSession) {}
57
58    /// Handle a TCP closed event.
59    ///
60    /// This event is triggered when a new TCP connection is closed.
61    #[allow(unused_variables)]
62    fn handle_tcp_closed(&mut self, session: &mut CoapSession) {}
63
64    /// Handle a TCP failed event.
65    #[allow(unused_variables)]
66    fn handle_tcp_failed(&mut self, session: &mut CoapSession) {}
67
68    /// Handle a session connected event.
69    ///
70    /// This event is triggered by CSM exchanges only when reliable protocols are used.
71    #[allow(unused_variables)]
72    fn handle_session_connected(&mut self, session: &mut CoapSession) {}
73
74    /// Handle a session closed event.
75    ///
76    /// This event is triggered by CSM exchanges only when reliable protocols are used.
77    #[allow(unused_variables)]
78    fn handle_session_closed(&mut self, session: &mut CoapSession) {}
79
80    /// Handle a session failed event.
81    ///
82    /// This event is triggered by CSM exchanges only when reliable protocols are used.
83    #[allow(unused_variables)]
84    fn handle_session_failed(&mut self, session: &mut CoapSession) {}
85
86    /// Handle a (Q-)Block receive error.
87    #[allow(unused_variables)]
88    fn handle_partial_block(&mut self, session: &mut CoapSession) {}
89
90    /// Handle the creation of a new server-side session.
91    ///
92    /// This event is called inside of the IO loop when a new server-side session is created.
93    #[allow(unused_variables)]
94    fn handle_server_session_new(&mut self, session: &mut CoapServerSession) {}
95
96    /// Handle the deletion of a server-side session.
97    ///
98    /// This event is called inside of the IO loop when a server-side session is deleted.
99    /// This can happen for a number of reasons:
100    /// - The session has been idle for too long (see [CoapContext::session_timeout()] and
101    ///   [CoapContext::set_session_timeout()])
102    /// - The maximum number of handshaking sessions is exceeded (see
103    ///   [CoapContext::max_handshake_sessions()] and [CoapContext::set_max_handshake_sessions()])
104    /// - The maximum number of idle sessions is exceeded (see
105    ///   [CoapContext::max_idle_sessions()] and [CoapContext::set_max_idle_sessions()])
106    #[allow(unused_variables)]
107    fn handle_server_session_del(&mut self, session: &mut CoapServerSession) {}
108}
109
110// This should be fine as we don't provide this type to a FFI function, we only read from it.
111#[allow(improper_ctypes_definitions)]
112pub(crate) unsafe extern "C" fn event_handler_callback(raw_session: *mut coap_session_t, event: coap_event_t) -> i32 {
113    let session: CoapSession = if event == coap_event_t::COAP_EVENT_SERVER_SESSION_NEW {
114        CoapServerSession::initialize_raw(raw_session).into()
115    } else {
116        CoapSession::from_raw(raw_session)
117    };
118    // SAFETY: Pointer is always valid as long as there is no bug in libcoap.
119    let context = CoapContext::from_raw(coap_session_get_context(raw_session));
120    context.handle_event(session, event);
121    0
122}
libcoap_rs/event.rs

libcoap_rs/
event.rs
