PeriodicNotifier.h

/*
 * Copyright(c) Sophist Solutions, Inc. 1990-2026.  All rights reserved
 */
#ifndef _Stroika_Frameworks_UPnP_SSDP_Server_PeriodicNotifier_h_
#define _Stroika_Frameworks_UPnP_SSDP_Server_PeriodicNotifier_h_ 1
 
#include "Stroika/Frameworks/StroikaPreComp.h"
 
#include "Stroika/Foundation/Characters/String.h"
#include "Stroika/Foundation/Common/Common.h"
#include "Stroika/Foundation/Execution/IntervalTimer.h"
#include "Stroika/Foundation/Execution/Synchronized.h"
#include "Stroika/Foundation/Traversal/Iterable.h"
 
#include "Stroika/Frameworks/UPnP/Device.h"
#include "Stroika/Frameworks/UPnP/SSDP/Advertisement.h"
#include "Stroika/Frameworks/UPnP/SSDP/Common.h"
#include "Stroika/Frameworks/UPnP/SSDP/Server/LocationProvider.h"
 
/*
 *  \file
 *
 *  \note Code-Status:  <a href="Code-Status.md#Alpha">Alpha</a>
 */
 
namespace Stroika::Frameworks::UPnP::SSDP::Server {
 
    using Traversal::Iterable;
 
    /**
     *  A big part of SSDP server functionality is to send periodic notifications of the Device description.
     *  Most applications want BasicServer instead, which does this and also answers searches (@see SearchResponder).
     *
     *  Instantiating the class starts the (background) notifications automatically, and they
     *  continue until the PeriodicNotifier object is destroyed. (so a smart pointer to one of these is typically kept around
     *  for the life of the application). Destroying it says ssdp:byebye, so control points drop the device at once - rather
     *  than when its announcements' max-age runs out.
     *
     *  \par Example Usage
     *      \code
     *          Execution::IntervalTimer::Manager::Activator intervalTimerMgrActivator; // once, near the start of main ()
     *          ...
     *          // announce this device, as a UPnP root device - with where deviceWS serves its description
     *          SSDP::Advertisement rootDevice;
     *          rootDevice.fServer = SSDP::MakeServerHeaderValue ("MyProduct/1.0"sv);
     *          rootDevice.fTarget = SSDP::kTarget_UPNPRootDevice;
     *          rootDevice.fUSN    = Characters::Format ("uuid:{}::{}"_f, deviceID, SSDP::kTarget_UPNPRootDevice);
     *          PeriodicNotifier notifier{Sequence<SSDP::Advertisement>{rootDevice}, LocationFromBindings (deviceWS.bindings ())};
     *      \endcode
     *
     *  \note requires Execution::IntervalTimer::Manager::Activator intervalTimerMgrActivator
     * 
     *  \note - this behavior differs from Stroika 2.1, where you had to explicitly call Run ()
     *  \note - requirement to instantiate IntervalTimer::Manager::Activator before this new in Stroika v3
     */
    class PeriodicNotifier {
    public:
        /**
         *  How often the NOTIFYs go out, and how long each says it is good for (its CACHE-CONTROL max-age) - a listener
         *  forgets a device whose announcement is not renewed by then. So fRepeatInterval must be less than fMaxAge: the UPnP
         *  Device Architecture recommends under half of it, and fMaxAge at least 1800 seconds.
         *
         *  fRepeatInterval is the longest wait between them: each comes a random time between half of it and all of it after the
         *  last (the UPnP Device Architecture's "randomly-distributed interval"), so devices do not keep announcing together.
         */
        struct FrequencyInfo {
            Time::DurationSeconds fRepeatInterval{3 * 60.0s};
            Time::DurationSeconds fMaxAge{kDefaultMaxAge};
        };
 
    public:
        /**
         */
        struct Options {
            FrequencyInfo fFrequencyInfo{}; ///< how often to send the NOTIFYs
            IO::Network::InternetProtocol::IP::IPVersionSupport fIPVersion{IO::Network::InternetProtocol::IP::IPVersionSupport::eDEFAULT}; ///< which SSDP channels: IPv4 (239.255.255.250) and/or IPv6 (ff02::c)
            uint8_t fMulticastTTL{kDefaultMulticastTTL}; ///< the TTL (IPv6: hop limit) of each NOTIFY: how many routers it may cross (@see kDefaultMulticastTTL)
            InterfaceFilter fInterfaces{DefaultInterfaceFilter}; ///< which network interfaces to send them out of - asked each time (@see SSDP::InterfaceFilter)
 
            /**
             *  When a network appears, send the NOTIFYs right away, rather than at the next cycle.
             *  It costs a LinkMonitor (all share one thread, waiting on the OS's address-change notifications) - and, only while
             *  a burst of changes settles and is acted on, a thread of its own. Where the OS cannot tell (e.g. some containers),
             *  it is just not done.
             */
            bool fFollowNetworkChanges{true};
        };
        static const Options kDefaultOptions;
 
    public:
        /**
         *  Makes its sockets on construction, then sends the advertisements - out of every network interface
         *  options.fInterfaces accepts, each with the LOCATION location gives for that interface - after a random wait of up to
         *  100 ms (as the UPnP Device Architecture asks, so devices starting together do not all announce at once; and again when
         *  a network appears), then about every options.fFrequencyInfo.fRepeatInterval (@see FrequencyInfo), until this object is
         *  destroyed. The interfaces are listed afresh each time, so networks that come and go are picked up. The advertisements'
         *  own fLocation is not used.
         *
         *  Each set of NOTIFYs goes out twice, 100 ms apart, as UDP loses packets (the UPnP Device Architecture says more than once)
         *  - the first set during construction, so making it up to 200 ms slower; and destruction too, for its ssdp:byebye.
         *
         *  Its sockets are not bound - they only send - so NOTIFYs come from an ephemeral port, not SSDP's 1900.
         *
         *  Errors doing sends are just logged with DbgTrace()
         */
        PeriodicNotifier (const Iterable<Advertisement>& advertisements, const LocationProvider& location, const Options& options = kDefaultOptions);
        PeriodicNotifier (const PeriodicNotifier&) = delete;
 
    public:
        const PeriodicNotifier operator= (const PeriodicNotifier&) = delete;
 
    public:
        /**
         *  \brief Stops the NOTIFYs, then sends an ssdp:byebye for each advertisement, out of each interface its last NOTIFYs went
         *         out of - in as many sets as the NOTIFYs. (A SearchResponder answering for the same device should go first, so no
         *         answer follows the byebye.)
         */
        ~PeriodicNotifier ();
 
    public:
        /**
         *  \brief The network interfaces its last NOTIFYs went out of - as they were then (so with the addresses they had then).
         *         Safe to call from any thread.
         */
        nonvirtual IO::Network::InterfacesByID GetNetworkInterfaces () const;
 
    private:
        shared_ptr<Execution::Synchronized<IO::Network::InterfacesByID>> fNotifyingOn_; // shared with the timer's callback
        function<void ()>                                                fSayByebye_;
        unique_ptr<Execution::IntervalTimer::Adder>                      fIntervalTimerAdder_;
        optional<SSDP::Private_::NetworkChangeFollower> fNetworkChanges_; // last, so destroyed first: no NOTIFY while the rest goes away
    };
 
}
 
/*
 ********************************************************************************
 ***************************** Implementation Details ***************************
 ********************************************************************************
 */
#include "PeriodicNotifier.inl"
 
#endif /*_Stroika_Frameworks_UPnP_SSDP_Server_PeriodicNotifier_h_*/