// SPDX-License-Identifier: BSD-2-Clause

/*

 * Copyright © The libcoap-rs Contributors, all rights reserved.

 * This file is part of the libcoap-rs project, see the README file for

 * general information on this project and the NOTICE.md and LICENSE files

 * for information regarding copyright ownership and terms of use.

 *

 * context.rs - CoAP context related code.

 */

//! Module containing context-internal types and traits.

use core::ffi::c_uint;

#[cfg(feature = "dtls-pki")]

use std::ffi::CString;

#[cfg(feature = "dtls")]

use std::ptr::NonNull;

use std::{

    any::Any,

    ffi::{c_void, CStr},

    fmt::Debug,

    net::SocketAddr,

    ops::Sub,

    sync::Once,

    time::Duration,

};

#[cfg(all(feature = "dtls-pki", unix))]

use std::{os::unix::ffi::OsStrExt, path::Path};

#[cfg(feature = "dtls-pki")]

use libcoap_sys::coap_context_set_pki_root_cas;

use libcoap_sys::{

    coap_add_resource, coap_bin_const_t, coap_can_exit, coap_context_get_csm_max_message_size,

    coap_context_get_csm_timeout, coap_context_get_max_handshake_sessions, coap_context_get_max_idle_sessions,

    coap_context_get_session_timeout, coap_context_set_block_mode, coap_context_set_csm_max_message_size,

    coap_context_set_csm_timeout, coap_context_set_keepalive, coap_context_set_max_handshake_sessions,

    coap_context_set_max_idle_sessions, coap_context_set_session_timeout, coap_context_t, coap_delete_bin_const,

    coap_event_t, coap_event_t_COAP_EVENT_BAD_PACKET, coap_event_t_COAP_EVENT_DTLS_CLOSED,

    coap_event_t_COAP_EVENT_DTLS_CONNECTED, coap_event_t_COAP_EVENT_DTLS_ERROR,

    coap_event_t_COAP_EVENT_DTLS_RENEGOTIATE, coap_event_t_COAP_EVENT_KEEPALIVE_FAILURE,

    coap_event_t_COAP_EVENT_MSG_RETRANSMITTED, coap_event_t_COAP_EVENT_OSCORE_DECODE_ERROR,

    coap_event_t_COAP_EVENT_OSCORE_DECRYPTION_FAILURE, coap_event_t_COAP_EVENT_OSCORE_INTERNAL_ERROR,

    coap_event_t_COAP_EVENT_OSCORE_NOT_ENABLED, coap_event_t_COAP_EVENT_OSCORE_NO_PROTECTED_PAYLOAD,

    coap_event_t_COAP_EVENT_OSCORE_NO_SECURITY, coap_event_t_COAP_EVENT_PARTIAL_BLOCK,

    coap_event_t_COAP_EVENT_SERVER_SESSION_DEL, coap_event_t_COAP_EVENT_SERVER_SESSION_NEW,

    coap_event_t_COAP_EVENT_SESSION_CLOSED, coap_event_t_COAP_EVENT_SESSION_CONNECTED,

    coap_event_t_COAP_EVENT_SESSION_FAILED, coap_event_t_COAP_EVENT_TCP_CLOSED, coap_event_t_COAP_EVENT_TCP_CONNECTED,

    coap_event_t_COAP_EVENT_TCP_FAILED, coap_event_t_COAP_EVENT_WS_CLOSED, coap_event_t_COAP_EVENT_WS_CONNECTED,

    coap_event_t_COAP_EVENT_WS_PACKET_SIZE, coap_event_t_COAP_EVENT_XMIT_BLOCK_FAIL, coap_free_context,

    coap_get_app_data, coap_io_process, coap_join_mcast_group_intf, coap_new_bin_const, coap_new_context, coap_proto_t,

    coap_proto_t_COAP_PROTO_DTLS, coap_proto_t_COAP_PROTO_TCP, coap_proto_t_COAP_PROTO_UDP,

    coap_register_event_handler, coap_register_response_handler, coap_set_app_data, coap_startup_with_feature_checks,

    COAP_BLOCK_SINGLE_BODY, COAP_BLOCK_USE_LIBCOAP, COAP_IO_WAIT,

};

#[cfg(feature = "oscore")]

use libcoap_sys::{coap_context_oscore_server, coap_delete_oscore_recipient, coap_new_oscore_recipient};

#[cfg(any(feature = "dtls-rpk", feature = "dtls-pki"))]

use crate::crypto::pki_rpk::ServerPkiRpkCryptoContext;

#[cfg(feature = "dtls-psk")]

use crate::crypto::psk::ServerPskContext;

use crate::{

    error::{ContextConfigurationError, EndpointCreationError, IoProcessError, MulticastGroupJoinError},

    event::{event_handler_callback, CoapEventHandler},

    mem::{CoapLendableFfiRcCell, CoapLendableFfiWeakCell, DropInnerExclusively},

    resource::{CoapResource, UntypedCoapResource},

    session::{session_response_handler, CoapServerSession, CoapSession},

    transport::CoapEndpoint,

};

//TODO: New feature?

#[cfg(feature = "oscore")]

use crate::{

    error::{OscoreRecipientError, OscoreServerCreationError},

    OscoreConf,

};

static COAP_STARTUP_ONCE: Once = Once::new();

#[inline(always)]

#[derive(Debug)]

struct CoapContextInner<'a> {

    /// Reference to the raw context this context wraps around.

    raw_context: *mut coap_context_t,

    /// A list of endpoints that this context is currently associated with.

    endpoints: Vec<CoapEndpoint>,

    /// A list of resources associated with this context.

    resources: Vec<Box<dyn UntypedCoapResource>>,

    /// A list of server-side sessions that are currently active.

    server_sessions: Vec<CoapServerSession<'a>>,

    /// The event handler responsible for library-user side handling of events.

    event_handler: Option<Box<dyn CoapEventHandler>>,

    /// PSK context for encrypted server-side sessions.

    #[cfg(feature = "dtls-psk")]

    psk_context: Option<ServerPskContext<'a>>,

    /// PKI context for encrypted server-side sessions.

    #[cfg(any(feature = "dtls-pki", feature = "dtls-rpk"))]

    pki_rpk_context: Option<ServerPkiRpkCryptoContext<'a>>,

    /// Saves if appropriate oscore information has been added to the raw_context as stated by

    /// libcoap to assume before adding/removing additional recipient_id's to it.

    #[cfg(feature = "oscore")]

    provided_oscore_information: bool,

    /// A list of recipients associated with this context.

    #[cfg(feature = "oscore")]

    recipients: Vec<Box<String>>,

}

/// A CoAP Context — container for general state and configuration information relating to CoAP

///

/// The equivalent to the [coap_context_t] type in libcoap.

#[derive(Debug)]

pub struct CoapContext<'a> {

    inner: CoapLendableFfiRcCell<CoapContextInner<'a>>,

}

impl<'a> CoapContext<'a> {

    /// Creates a new context.

    ///

    /// # Errors

    /// Returns an error if the underlying libcoap library was unable to create a new context

    /// (probably an allocation error?).

        // SAFETY: Providing null here is fine, the context will just not be bound to an endpoint

        // yet.

        // SAFETY: We checked that raw_context is not null.

        // SAFETY: We checked that the raw context is not null, the provided function is valid and

        // the app data pointer provided must be valid as we just created it using

        // `create_raw_weak_box()`.

    /// Restores a CoapContext from its raw counterpart.

    ///

    /// # Safety

    /// Provided pointer must point to as valid instance of a raw context whose application data

    /// points to a `*mut CoapLendableFfiWeakCell<CoapContextInner>`.

        );

    /// Handle an incoming event provided by libcoap.

        // Call event handler for event.

            // Variant names are named by bindgen, we have no influence on this.

            // Ref: https://github.com/rust-lang/rust/issues/39371

            #[allow(non_upper_case_globals)]

                coap_event_t_COAP_EVENT_SERVER_SESSION_NEW => {

                    } else {

                    }

                },

                coap_event_t_COAP_EVENT_SERVER_SESSION_DEL => {

                    } else {

                    }

                },

                coap_event_t_COAP_EVENT_OSCORE_DECRYPTION_FAILURE => {

                },

                coap_event_t_COAP_EVENT_OSCORE_NO_PROTECTED_PAYLOAD => {

                },

            }

        // For server-side sessions: Ensure that server-side session wrappers are either kept in memory or dropped when needed.

            // Variant names are named by bindgen, we have no influence on this.

            // Ref: https://github.com/rust-lang/rust/issues/39371

            #[allow(non_upper_case_globals)]

                coap_event_t_COAP_EVENT_SERVER_SESSION_DEL => {

                        ),

                    ));

                },

            }

    /// Sets the server-side cryptography information provider.

    ///

    /// # Errors

    ///

    /// Returns [`ContextConfigurationError::Unknown`] if the call to the underlying libcoap library

    /// function fails and [`ContextConfigurationError::CryptoContextAlreadySet`] if the PSK context

    /// has already been set previously.

    #[cfg(feature = "dtls-psk")]

        // SAFETY: raw context is valid, we ensure that an already set encryption context will not

        // be overwritten, and the raw coap_context_t is cleaned up before the encryption context is

        // dropped (ensuring the encryption context outlives the CoAP context).

        unsafe {

        }

    /// Sets the server-side cryptography information provider.

    ///

    /// # Errors

    ///

    /// Returns [`ContextConfigurationError::Unknown`] if the call to the underlying libcoap library

    /// function fails and [`ContextConfigurationError::CryptoContextAlreadySet`] if the PSK context

    /// has already been set previously.

    #[cfg(any(feature = "dtls-pki", feature = "dtls-rpk"))]

        // SAFETY: raw context is valid, we ensure that an already set encryption context will not

        // be overwritten, and the raw coap_context_t is cleaned up before the encryption context is

        // dropped (ensuring the encryption context outlives the CoAP context).

        unsafe {

        }

    /// Convenience wrapper around [`set_pki_root_cas`](CoapContext::set_pki_root_cas) that can be

    /// provided with any type that implements `AsRef<Path>`.

    ///

    /// `ca_file` should be the full path of a PEM-encoded file containing all root CAs to be used

    /// or `None`, `ca_dir` should be a directory path containing PEM-encoded CA certificates to

    /// be used or `None`.

    ///

    /// As not all implementations of [`OsString`] (which is the basis of [`Path`]) provide

    /// conversions to non-zero byte sequences, this function is only available on Unix.

    /// On other operating systems, perform manual conversion of paths into [`CString`] and call

    /// [`set_pki_root_cas`](CoapContext::set_pki_root_cas) directly instead.

    ///

    /// See the Rust standard library documentation on [FFI conversions](https://doc.rust-lang.org/std/ffi/index.html#conversions])

    /// and the [`OsString` type](https://doc.rust-lang.org/std/ffi/struct.OsString.html) for more

    /// information.

    ///

    /// # Errors

    /// Will return [`ContextConfigurationError::Unknown`] if the call to the underlying libcoap

    /// function fails (indicating an error in either libcoap or the underlying TLS library).

    #[cfg(all(feature = "dtls-pki", unix))]

            // Unix paths never contain null bytes, so we can unwrap here.

            // Unix paths never contain null bytes, so we can unwrap here.

    /// Sets the path to a CA certificate file and/or a directory of CA certificate files that

    /// should be used as this context's default root CA information.

    ///

    /// `ca_file` should be the full path of a PEM-encoded file containing all root CAs to be used

    /// or `None`, `ca_dir` should be a directory path containing PEM-encoded CA certificates to

    /// be used or `None`.

    ///

    /// # Errors

    /// Will return [`ContextConfigurationError::Unknown`] if the call to the underlying libcoap

    /// function fails (indicating an error in either libcoap or the underlying TLS library).

    #[cfg(feature = "dtls-pki")]

            )

        };

        } else {

        }

}

impl CoapContext<'_> {

    /// Performs a controlled shutdown of the CoAP context.

    ///

    /// This will perform all still outstanding IO operations until [coap_can_exit()] confirms that

    /// the context has no more outstanding IO and can be dropped without interrupting sessions.

        // Send remaining packets until we can cleanly shutdown.

        // SAFETY: Provided context is always valid as an invariant of this struct.

        }

    /// Store reference to the endpoint

    /// Creates a new UDP endpoint that is bound to the given address.

    /// Creates a new TCP endpoint that is bound to the given address.

    #[cfg(feature = "tcp")]

    /// Set the context's default OSCORE configuration for a server.

    ///

    /// # Errors

    /// Will return a [OscoreServerCreationError] if adding the oscore configuration fails.

    #[cfg(feature = "oscore")]

    pub fn oscore_server(&mut self, oscore_conf: OscoreConf) -> Result<(), OscoreServerCreationError> {

        let mut inner_ref = self.inner.borrow_mut();

        let result: i32;

        // SAFETY: The raw_conf is guranteed to be dropped by the call to coap_context_oscore_server() below.

        let (raw_conf, initial_recipient) = oscore_conf.into_raw_conf();

        // SAFETY: Properly initialized CoapContext always has a valid raw_context that is not deleted until

        // the CoapContextInner is dropped. OscoreConf raw_conf should be valid, else return an error.

        //

        // coap_context_oscore_server will also always free the raw_conf, regardless of the result:

        // [libcoap docs](https://libcoap.net/doc/reference/4.3.5/group__oscore.html#ga71ddf56bcd6d6650f8235ee252fde47f)

        unsafe {

            result = coap_context_oscore_server(inner_ref.raw_context, raw_conf);

        };

        // Check whether adding the config to the context failed.

        if result == 0 {

            return Err(OscoreServerCreationError::Unknown);

        }

        // Add the initial_recipient (if present).

        if let Some(initial_recipient) = initial_recipient {

            inner_ref.recipients.push(Box::new(initial_recipient));

        }

        // Mark context as valid oscore server.

        inner_ref.provided_oscore_information = true;

        Ok(())

    }

    /// Adds a recipient_id to the OscoreContext.

    ///

    /// # Errors

    /// Will return a [OscoreRecipientError] if adding the recipient failed.

    /// You might want to check the error to determine if adding the recipient failed

    /// due to the recipient_id beeing already added to the context.

    /// Trying to call this on a CoapContext without appropriate oscore information will

    /// also result in an error.

    #[cfg(feature = "oscore")]

    pub fn new_oscore_recipient(&mut self, recipient_id: &str) -> Result<(), OscoreRecipientError> {

        let mut inner_ref = self.inner.borrow_mut();

        // Return if context has no appropriate oscore information.

        if !inner_ref.provided_oscore_information {

            #[cfg(debug_assertions)]

            eprintln!("tried adding recipient to context with no appropriate oscore information");

            return Err(OscoreRecipientError::NoOscoreContext);

        }

        let recipient = recipient_id.to_string();

        // Return if the recipient is already added as the coap_new_oscore_recipient

        // would free the raw struct for duplicate recipients.

        // As we can't check why adding the recipient failed we have to filter this

        // case to prevent a double free.

        if inner_ref.recipients.iter().any(|elem| *elem.as_ref() == recipient) {

            return Err(OscoreRecipientError::DuplicateId);

        }

        let raw_recipient;

        let result;

        // SAFETY: If adding the recipient to the context fails we drop its underlying raw

        // struct manually as it's not handled by libcoap except for when trying to add a duplicate

        // recipient, which is filtered out above because libcoap does not offer a proper way to

        // determine the cause of the failure.

        // The raw_recipient is checked for validity before use and properly initialized

        // CoapContext should always have a valid raw_context until CoapContextInner is dropped.

        unsafe {

            raw_recipient = coap_new_bin_const(recipient.as_ptr(), recipient.len());

            if raw_recipient.is_null() {

                return Err(OscoreRecipientError::Unknown);

            }

            result = coap_new_oscore_recipient(inner_ref.raw_context, raw_recipient);

        };

        // If adding the recipient failed...

        if result == 0 {

            // ...manually call coap_delete_bin_const to get rid of the created instance.

            // SAFETY: The raw_recipient's raw_pointer has to be valid here because libcoap does

            // only free the recipient if adding it failed due to a duplicate, which is filtered

            // out above because libcoap currently does not offer a proper way to determine the

            // cause of the failure as of version 4.3.5.

            unsafe {

                coap_delete_bin_const(raw_recipient);

            }

            return Err(OscoreRecipientError::Unknown);

        }

        // Else box the recipient and add it to the CoapContext to keep its raw_pointer valid.

        inner_ref.recipients.push(Box::new(recipient));

        Ok(())

    }

    /// Removes a recipient_id from the OscoreContext.

    ///

    /// # Errors

    /// Will return a [OscoreRecipientError] if removing the recipient failed.

    /// You might want to check the error to determine if removing the recipient failed

    /// due to the recipient_id beeing not present within the context.

    /// Trying to call this on a CoapContext without appropriate oscore information will

    /// also result in an error.

    #[cfg(feature = "oscore")]

    pub fn delete_oscore_recipient(&mut self, recipient_id: &str) -> Result<(), OscoreRecipientError> {

        let mut inner_ref = self.inner.borrow_mut();

        // Return if context has no appropriate oscore information.

        if !inner_ref.provided_oscore_information {

            #[cfg(debug_assertions)]

            eprintln!("tried removing recipient from context with no appropriate oscore information");

            return Err(OscoreRecipientError::NoOscoreContext);

        }

        let recipient = recipient_id.to_string();

        // Search for the recipient and try to remove it if present.

        if let Some(index) = inner_ref.recipients.iter().position(|elem| *elem.as_ref() == recipient) {

            let result: i32;

            // SAFETY: If libcoap successfully removed the raw_recipient from the raw_context

            // it is also freed. The recipient's raw_struct should always be valid, as it would

            // have been removed from the context once deleting it succeeded.

            // The raw_recipient is checked for validity before use and properly initialized

            // CoapContext should always have a valid raw_context until CoapContextInner is

            // dropped.

            unsafe {

                let mut raw_recipient = coap_bin_const_t {

                    length: recipient.len(),

                    s: recipient.as_ptr(),

                };

                result = coap_delete_oscore_recipient(inner_ref.raw_context, &mut raw_recipient);

            }

            // Check whether removing the recipient from the CoapContext's raw_context failed.

            if result == 0 {

                return Err(OscoreRecipientError::Unknown);

            }

            // Remove the recipient from the CoapContext if it has been successfully removed

            // from the CoapContext's raw_context. At this point the raw_recipient has been dropped

            // by libcoap.

            inner_ref.recipients.remove(index);

            return Ok(());

        }

        Err(OscoreRecipientError::NotFound)

    }

    /// Creates a new DTLS endpoint that is bound to the given address.

    ///

    /// Note that in order to actually connect to DTLS clients, you need to set a crypto provider

    /// using [CoapContext::set_psk_context] and/or [CoapContext::set_pki_rpk_context].

    #[cfg(feature = "dtls")]

    /// Joins a multicast group.

    ///

    /// `groupname` is usually a multicast IP address, while `ifname` is the used interface.

    /// If `ifname` is set to `None`, the first appropriate interface will be chosen by the operating system.

        // SAFETY: `inner_ref.raw_context` is always valid by construction of this type, group and interface name are pointers to valid C strings.

        unsafe {

        };

    // /// TODO

    // #[cfg(all(feature = "tcp", dtls))]

    // pub fn add_endpoint_tls(&mut self, _addr: SocketAddr) -> Result<(), EndpointCreationError> {

    //     todo!()

    //     // TODO: self.add_endpoint(addr, coap_proto_t_COAP_PROTO_TLS)

    // }

    /// Adds the given resource to the resource pool of this context.

        // SAFETY: raw context is valid, raw resource is also guaranteed to be valid as long as

        // contract of CoapResource is upheld.

    /// Performs currently outstanding IO operations, waiting for a maximum duration of `timeout`.

    ///

    /// This is the function where most of the IO operations made using this library are actually

    /// executed. It is recommended to call this function in a loop for as long as the CoAP context

    /// is used.

        // Round up the duration if it is not a clean number of seconds.

        } else {

            // If no timeout is set, wait indefinitely.

        };

        // Lend the current mutable reference to potential callers of CoapContext functions on the

        // other side of the FFI barrier.

        // SAFETY: Properly initialized CoapContext always has a valid raw_context that is not

        // deleted until the CoapContextInner is dropped.

        // Other raw structs used by libcoap are encapsulated in a way that they cannot be in use

        // while in this function (considering that they are all !Send).

        // Demand the return of the lent handle, ensuring that the mutable reference is no longer

        // used anywhere.

        // Check for errors.

        // Return with duration of call.

    /// Return the duration that idle server-side sessions are kept alive if they are not referenced

    /// or used anywhere else.

        // SAFETY: Properly initialized CoapContext always has a valid raw_context that is not

        // deleted until the CoapContextInner is dropped.

    /// Set the duration that idle server-side sessions are kept alive if they are not referenced or

    /// used anywhere else.

    ///

    /// # Panics

    /// Panics if the provided duration is too large to be provided to libcoap (larger than a

    /// [libc::c_uint]).

        // SAFETY: Properly initialized CoapContext always has a valid raw_context that is not

        // deleted until the CoapContextInner is dropped.

        unsafe {

            )

        }

    /// Returns the maximum number of server-side sessions that can concurrently be in a handshake

    /// state.

    ///

    /// If this number is exceeded, no new handshakes will be accepted.

        // SAFETY: Properly initialized CoapContext always has a valid raw_context that is not

        // deleted until the CoapContextInner is dropped.

    /// Sets the maximum number of server-side sessions that can concurrently be in a handshake

    /// state.

    ///

    /// If this number is exceeded, no new handshakes will be accepted.

        // SAFETY: Properly initialized CoapContext always has a valid raw_context that is not

        // deleted until the CoapContextInner is dropped.

    /// Returns the maximum number of idle server-side sessions for this context.

    ///

    /// If this number is exceeded, the oldest unreferenced session will be freed.

        // SAFETY: Properly initialized CoapContext always has a valid raw_context that is not

        // deleted until the CoapContextInner is dropped.

    /// Sets the maximum number of idle server-side sessions for this context.

    ///

    /// If this number is exceeded, the oldest unreferenced session will be freed.

        // SAFETY: Properly initialized CoapContext always has a valid raw_context that is not

        // deleted until the CoapContextInner is dropped.

    /// Returns the maximum size for Capabilities and Settings Messages

    ///

    /// CSMs are used in CoAP over TCP as specified in

    /// [RFC 8323, Section 5.3](https://datatracker.ietf.org/doc/html/rfc8323#section-5.3).

        // SAFETY: Properly initialized CoapContext always has a valid raw_context that is not

        // deleted until the CoapContextInner is dropped.

    /// Sets the maximum size for Capabilities and Settings Messages

    ///

    /// CSMs are used in CoAP over TCP as specified in

    /// [RFC 8323, Section 5.3](https://datatracker.ietf.org/doc/html/rfc8323#section-5.3).

        // SAFETY: Properly initialized CoapContext always has a valid raw_context that is not

        // deleted until the CoapContextInner is dropped.

    /// Returns the timeout for Capabilities and Settings Messages

    ///

    /// CSMs are used in CoAP over TCP as specified in

    /// [RFC 8323, Section 5.3](https://datatracker.ietf.org/doc/html/rfc8323#section-5.3).

        // SAFETY: Properly initialized CoapContext always has a valid raw_context that is not

        // deleted until the CoapContextInner is dropped.

    /// Sets the timeout for Capabilities and Settings Messages

    ///

    /// CSMs are used in CoAP over TCP as specified in

    /// [RFC 8323, Section 5.3](https://datatracker.ietf.org/doc/html/rfc8323#section-5.3).

    ///

    /// # Panics

    /// Panics if the provided timeout is too large for libcoap (> [u32::MAX]).

        // SAFETY: Properly initialized CoapContext always has a valid raw_context that is not

        // deleted until the CoapContextInner is dropped.

        unsafe {

            )

        };

    /// Sets the number of seconds to wait before sending a CoAP keepalive message for idle

    /// sessions.

    ///

    /// If the provided value is None, CoAP-level keepalive messages will be disabled.

    ///

    /// # Panics

    /// Panics if the provided duration is too large to be provided to libcoap (larger than a

    /// [libc::c_uint]).

        // SAFETY: Properly initialized CoapContext always has a valid raw_context that is not

        // deleted until the CoapContextInner is dropped.

        unsafe {

            )

        };

    /// Returns a reference to the raw context contained in this struct.

    ///

    /// # Safety

    /// In general, you should not do anything that would interfere with the safe functions of this

    /// struct.

    /// Most notably, this includes the following:

    /// - Associating raw resources with the context and not removing them before the context is

    ///   dropped (may cause segfaults on drop).

    /// - Associating raw sessions that have a reference count != 0 when the CoapContext is dropped

    ///   (will cause an abort on drop)

    /// - Calling `coap_free_context()` on this context (for obvious reasons, this will probably

    ///   cause a segfault if you don't immediately [std::mem::forget()] the CoapContext and never

    ///   use anything related to the context again, but why would you do that?)

    // Kept here for consistency, even though it is unused.

    #[allow(unused)]

        // SAFETY: raw_context is checked to be a valid pointer on struct instantiation, cannot be

        // freed by anything outside of here (assuming the contract of this function is kept), and

        // the default (elided) lifetimes are correct (the pointer is valid as long as the endpoint

        // is).

    /// Returns a mutable reference to the raw context contained in this struct.

    ///

    /// # Safety

    /// In general, you should not do anything that would interfere with the safe functions of this

    /// struct.

    /// Most notably, this includes the following:

    /// - Associating raw resources with the context and not removing them before the context is

    ///   dropped (may cause segfaults on drop).

    /// - Associating raw sessions that have a reference count != 0 when the CoapContext is dropped

    ///   (will cause an abort on drop)

    /// - Calling `coap_free_context()` on this context (for obvious reasons, this will probably

    ///   cause a segfault if you don't immediately [std::mem::forget()] the CoapContext and never

    ///   use anything related to the context again, but why would you do that?)

        // SAFETY: raw_context is checked to be a valid pointer on struct instantiation, cannot be

        // freed by anything outside of here (assuming the contract of this function is kept), and

        // the default (elided) lifetimes are correct (the pointer is valid as long as the endpoint

        // is).

    // TODO coap_session_get_by_peer

}

impl Drop for CoapContextInner<'_> {

        // Disable event handler before dropping, as we would otherwise need to lend our reference

        // and because calling event handlers is probably undesired when we are already dropping

        // the context.

        // SAFETY: Validity of our raw context is always given for the lifetime of CoapContextInner

        // unless coap_free_context() is called during a violation of the [as_mut_raw_context()] and

        // [as_mut_context()] contracts (we check validity of the pointer on construction).

        // Passing a NULL handler/None to coap_register_event_handler() is allowed as per the

        // documentation.

        // Clear endpoints because coap_free_context() would free their underlying raw structs.

        // Extract reference to CoapContextInner from raw context and drop it.

        // SAFETY: Value is set upon construction of the inner context and never deleted.

        unsafe {

            ))

        }

        // Attempt to regain sole ownership over all resources.

        // As long as [CoapResource::into_inner] isn't used and we haven't given out owned

        // CoapResource instances whose raw resource is attached to the raw context, this should

        // never fail.

        // SAFETY: We have already dropped all endpoints and contexts which could be freed alongside

        // the actual context, and our raw context reference is valid (as long as the contracts of

        // [as_mut_raw_context()] and [as_mut_context()] are fulfilled).

        // Drop all recipients as coap_free_context() has dropped all associated raw_recipients.

        #[cfg(feature = "oscore")]

        self.recipients.clear();

}