STM32LoRaWAN::setMaintainNeededCallback: Add method

This method allows asynchronous applications to get notified when there
is work to be done, which allows them to be much more efficient and
also allows implementing sleeping without race conditions.

Author: matthijskooijman

src/STM32LoRaWAN.cpp

@@ -105,6 +105,8 @@ void STM32LoRaWAN::MacProcessNotify()
 {
   // Called by the stack from an ISR when there is work to do
   instance->mac_process_pending = true;
+  if (instance->maintain_needed_callback)
+    instance->maintain_needed_callback();
 }
 
 void STM32LoRaWAN::maintain()

src/STM32LoRaWAN.h

@@ -758,6 +758,27 @@ class STM32LoRaWAN : public Stream {
      */
     void maintainUntilIdle();
 
+    /**
+     * Registers a callback that is called whenever there is some work
+     * to do and the maintain() function must be called soon.
+     *
+     * \warning This callback is called from an interrupt handler, so it
+     * should not do any work and definitely *not* call `maintain()`,
+     * but just set a flag, enable a task, or something similarly short,
+     * and make sure to do that in a interrupt-safe manner.
+     *
+     * When using this callback, it is not needed to call the
+     * `maintain()` method unless this callback is called, allowing
+     * applications to be more efficient, or use sleeping (but care
+     * should be taken to prevent race conditions).
+     *
+     * Only one callback can be active at the same time, so any
+     * previously configured callback is replaced by the new one passed.
+     *
+     * \NotInMKRWAN
+     */
+    void setMaintainNeededCallback(std::function<void(void)> callback);
+
     /// @}
 
 
@@ -999,6 +1020,8 @@ class STM32LoRaWAN : public Stream {
     uint32_t fcnt_up = 0;
     uint32_t fcnt_down = 0;
 
+    std::function<void(void)> maintain_needed_callback;
+
     bool mac_process_pending = false;
 
     static constexpr uint32_t DEFAULT_JOIN_TIMEOUT = 60000;