Clock.h

Go to the documentation of this file.

#pragma once
 
#pragma region INCLUSIONS
// Libreria per la gestione del WiFi per il modulo 'esp8266'
#include <ESP8266WiFi.h>
 
// Librerie necessarie per la comunicazione con il TIME SERVER per la sincronizzazione online dell'ora corrente
/*
Le librerie necessarie sono due per una corretta comunicazione:
--- "WiFiUdp.h" gestisce la comunicazione WiFi secondo il PROTOCOLLO UDP
--- "NTPClient.h" gestisce la comunicazione con il Time Server. Questa comunicazione utilizza il PROTOCOLLO UDP.
Per tale motivo, sono necessarie due librerie per il corretto funzionamento.
*/
#include <WiFiUdp.h>
#include <NTPClient.h>
#pragma endregion INCLUSIONS
 
// Namespace di protezione dalle inclusioni multiple con nominazione uguale
/*
I valori constexpr, come spiegato appena sopra, equivalgono alla direttiva '#define'. Questo può creare problemi nel momento in cui un singolo file viene incluso
in una gerarchia di molti più file, dove si potrebbe riscontrare la presenza di constexpr appartenenti a file diversi ma con gli stessi nomi! Questa ripetitività dei nomi deriva
dagli standard di nominazione. Per evitare, quindi, conflitti di multipla definizione, andremo ad utilizzare un 'namespace', che, come dice il nome, fornisce uno SPAZIO per i NOMI del nostro
file in cui il 'namespace' è stato dichiarato ed implementato.
Mantieniamo comunque la specificazione 'static', per evitare errori di linker in caso di inclusioni multiple di questa unità di traslazione [file].
*/
 
namespace Clock__file
{
 
    // Espressione costante (equivalente della direttiva '#define') per la definizione dei valori '_PoolingZone', '_TimeOffset', '_UpdateInterval'.
    // Questi valori sono delle costanti immutabili che rappresentano VALORI DI DEFAULT scelti dal creatore ed implementatore della classe.
    // L'utilizzo di un metodo di inizializzazione di default 'Init (1)' provocherà l'uso di tali valori.
    // L'utilizzo, se disponibile, di un metodo di inizializzazione parametrico 'Init (2)' NON provocherà l'utilizzo di tali valori.
    /*Questi valori risiederanno nel Data Segment*/
    static constexpr auto _PoolingZone = "europe.pool.ntp.org";
 
    static constexpr auto _TimeOffset = 3600;           /*1 ora in avanti rispetto al Meridiano Zero*/
 
    static constexpr auto _UpdateInterval = 60000;      /*[ms]*/
 
    // Valore di default per il formato dell'ora
    /*forbidden*/ /***static constexpr auto _TimeFormat = Clock::TimeFormat::_24HOURS;***/
 
    // In default, anche se il formato è impostato sulle 12h, viene messo nello stato 'NOT_USED'.
    // Questo non crea problemi perchè l'attributo 'm_TimePeriod' viene aggiornato al valore corretto ad ogni chiamata di un qualsiasi metodo 'getter'.
    /*forbidden*/ /***static constexpr auto _TimePeriod = Clock::TimePeriod::NOT_USED;***/
 
    // Valore costante rappresentante il periodo per la gestione del formato --> 12h
    static constexpr auto _Period = 12;
 
    // Valore costante per la formattazione "elegante" del formato --> 12h
    static constexpr auto _ElegantAdj /*Adjustment*/ = 10;
 
    // Valore costante che viene ritornato in caso di invalidità riscontrata nell'oggetto durante il dereferenziamento
    // per la chiamata dei metodi.
    // Il valore invalido utilizzato è un valore impossibile, cioè che non potrebbe essere mai restituito naturalmente.
    static constexpr int _invalidvalue = -1;
}
/*
'forbidden' indica una operazione che non può essere effettuata per diverse motivazioni dipendenti dal contesto.
In questo caso, abbiamo riscontrato due proibizioni tentando di dichiarare dei valori di default che si riferivano ad una classe e ai componenti di tale prima della
sua effettiva dichiarazione.
Si potrebbe pensare all'impiego di una 'forward declaration'. In questo caso non avrebbe portato a nessun risultato dato che stavamo anche andando ad utilizzare
dei componenti della classe. Ricordiamo che la 'forward declaration' permette la creazione di puntatori e referenze al tipo 'forwarded', ma non implementa la sua
definizione/implementazione completa. Questo causa l'impossibilità nell'utilizzo di elementi esistenti nella definizione/implementazione del tipo.
*/
 
// Gerarchia sincronizzazione 
/*
- 'Init' alloca i due oggetti necessari per la comunicazione con il Time Server.
La comunicazione NON viene avviata. Vengono solamente create le impostazioni per la comunicazione.
 
- 'StartService' avvia la comunicazione con il Time Server.
La comunicazione VIENE avviata con le impostazioni prima allocate.
Con il valore definito nella constexpr '_UpdateInterval', l'aggiornamento dei valori avviene automaticamente ogni 60 secondi.
 
- 'update' (libreria "NTPClient") forza l'aggiornamento dei valori.
Richiamato ad ogni metodo 'getter' della classe "Clock". Questo per garantire in valore di ritorno sempre valori "strong-updated" (appena aggiornati/"freschi")
*/
 
class Clock
{
    /*Blocco trivial*/
    /*
    Stiamo trattando una classe interamente statica. Per la definizione di staticit�, descritta successivamente, questa classe funger� solamente
    da "contenitore astratto" per organizzare pi� logicamente i dati. In verit�, tutto risieder� principalmente nel Data Segment, quindi sar�
    globale, ma statico (anche questo descritto successivamente).
    Questa staticit� implica la NON necessit� di creare istanze di questa classe, che risulterebbero totalmente inutili dato che tutti gli attributi
    e i metodi esistono nell'ambito globale.
    Per evitare, quindi, inutili istanziamenti, verranno bloccati il costruttore trivial (di default generato dal compilatore) e il distruttore, reso
    inutile dalla non-istanziabilit� della classe stessa.
    */
private:
    // Blocco attraverso privatizzazione del costruttore trivial
    Clock() = default;
    // Blocco attraverso privatizzazione del distruttore trivial
    ~Clock() = default;
 
    /*Enumerazioni*/
    /*
    Una enumerazione permette una gestione più intelligente degli "switcher" forniti all'utente finale.
    Tramite nomi significativi, si gestiscono gli "switcher" appunto con dei nomi, utilizzati per mascherare i valori di enumerazione meno significativi per l'utente.
    Anche qua si applica la staticità descritta successivamente. Una classe di enumarazione è automaticamente statica.
    */
public:
    enum class TimeFormat
    {
        _12HOURS,
        _24HOURS,
        INVALID_REFERENCE
    };
 
    enum class TimePeriod
    {
        NOT_USED,
        AM,
        PM
    };
 
    /*Attributi*/
private:
    // Puntatore all'oggetto di classe "WiFiUDP"
    /*
    Questa variabile conterr� l'istanza dell'oggetto di classe "WiFiUDP" creata durante l'operazione di inizializzazione.
    Questo oggetto � necessario per garantire un corretto funzionamento del programma. Infatti, gestisce il protocollo di 
    comunicazione UDP, protocollo utilizzato dalla classe "NTPClient" per la comunicazione con il Time Server.
    L'oggetto sar� sottoposto ad allocazione dinamica [heap]. Questo per evitare problemi con la deallocazione mirata all'ambito
    caratteristica della memoria statica [stack]. Una allocazione statica [stack] provocherebbe l'allocazione e successiva deallocazione
    immediata dell'oggetto esistendo solamente nell'ambito di inizializzazione.
    Essendo statica, la variabile (puntatore) verr� allocata nel 'Data Segment' (segmento dei dati) ed "esister�" fino a termine
    del programma stesso. Quindi si tratta di una variabile globale, ma statica. Questo la rende esistente solamente in questa unit�
    di traslazione (file).
    */
    static WiFiUDP* m_UDPProtocol;
 
    // Puntatore all'oggetto di classe "NTPClient"
    /*
    Questa variabile conterr� l'istanza dell'oggetto di classe "NTPClient" creata durante l'operazione di inizializzazione.
    Questo oggetto funge da 'Entry Point' per la comunicazione con il Time Server.
    Anche qua, per via della staticit�, viene applicata la gestione analizzata prima.
    */
    static NTPClient* m_NTPEntryPoint;
 
    // Valore stringa indicante la 'pool zone' dalla quale prelevare i valori richiesti (ora corrente)
    /*
    Questa variabile conterrà una stringa che rappresenta una zona, denominata 'pool', nel Time Server dalla quale prelevare
    il dato da noi richiesto.
    Anche qua, per via della staticità, viene applicata la gestione analizzata prima.
    */
    static const char* m_PoolingZone;
 
    // Valore indicante l'Offset in secondi per "ridimensionare" l'ora corrente. La Base è il Meridiano di Greenwich
    /*
    La lettura dell'ora corrente dal Time Server restituisce il valore secondo il meridiano zero, cioè quello di Greenwich.
    Ovviamente, noi dobbiamo adattare questo valore al nostro fuso orario. Per fare ciò, applichiamo un Offset al valore ottenuto. Quello che stiamo
    facendo non è altro che sommare una certa quantità in secondi [s] al valore ottenuto dal Meridiano di Greenwich.
    Anche qua, per via della staticità, viene applicata la gestione analizzata prima.
    L'attributo è del tipo 'int' perchè deve concordare con il tipo richiesto dal costruttore parametrico della classe "NTPClient".
    Sarebbe stato più ottimizzato specificarlo come 'unsigned int'.
    */
    static int m_TimeOffset;
 
    // Valore indicante l'intervallo, in 'ms' [millisecondi] per l'aggiornamento dei valori, cioè ogni quanto viene effettuata 
    // una richiesta dei valori al Time Server
    /*
    Per ottenere l'ora corrente, andremo ad utilizzare un metodo della classe "NTPClient" chiamato "getFormattedTime()". E' necessario precisare che questo
    metodo andrà solamente a restituire un valore che è l'ora corrente. La lettura dei valori dal Time Server non è vincolata da questo metodo, ma inizierà 
    alla chiamata del metodo "begin()" sempre della stessa classe e continuerà ogni 'm_UpdateInterval' millisecondi [ms] fino alla deallocazione dell'oggetto
    rappresentante l'Entry Point.
    Anche qua, per via della staticità, viene applicata la gestione analizzata prima.
    L'attributo è del tipo 'int' perchè deve concordare con il tipo richiesto dal costruttore parametrico della classe "NTPClient".
    Sarebbe stato più ottimizzato specificarlo come 'unsigned int'.
    */
    static int m_UpdateInterval;
 
    // Valore di enumerazione 'TimeFormat' indicante il formato di visualizzazione dell'ora --> 12h/24h
    /*
    - TimeFormat::_12HOURS --> formato 12h
    - TimeFormat::_24HOURS --> formato 24h
    Anche qua, per via della staticità, viene applicata la gestione analizzata prima.
    */
    static TimeFormat m_TimeFormat;
 
    // Valore di enumerazione 'TimePeriod' indicante il periodo
    /*
    Variabile utilizzata solo nel caso dell'uso del formato --> 12h.
    - TimePeriod::NOT_USED --> non in uso
    - TimePeriod::AM --> AM
    - TimePeriod::PM --> PM
    Anche qua, per via della staticità, viene applicata la gestione analizzata prima.
    */
    static TimePeriod m_Period;
 
    /*Init*/
public:
    // Inizializza la comunicazione con il Time Server con i rispettivi costruttori
    // Verranno utilizzati costruttori della classe "WiFiUDP" e della classe "NTPClient"
    /*
    Questo metodo, fondamentale, "dà vita" alla sincronizzazione dell'ora corrente. Effettua rispettivamente due allocazioni (dinamiche [heap])
    attraverso rispettivi costruttori delle classi sopra elencate.
    Analizzando i due costruttori:
    --- costruttore della classe "WiFiUDP" non richiede alcun parametro
    --- costruttore della classe "NTPClient" richiede 4 parametri, i quali sono:
    1 --> Oggetto che rappresenta il protocollo di comunicazione utilizzato
    2 --> Stringa che rappresenta su quale 'pool' prelevare i valori richiesti (ora corrente)
    3 --> Offset per il calcolo dell'ora corrente con Base --> Meridiano di Greenwich
    4 --> intervallo, in 'ms' [millisecondi] per l'aggiornamento dei valori, cioè ogni quanto viene effettuata una richiesta dei valori al Time Server
    I parametri, per evitare inutili copie, vengono passati per riferimento [reference --> '&'] (ove possibile).
    Il metodo ritorna un valore booleano, utilizzato per comunicare eventuali errori durante l'allocazione.
    Inoltre, prima dell'effettiva allocazione, esegue una deallocazione [delete] se necessaria.
    Anche qua ritroviamo la specificazione di staticità. Nel caso di applicazione ad un metodo, dissocia il metodo stesso da qualsiasi possibile istanza
    della classe. Quindi, il metodo sarà richiamabile come se fosse globale (e statico). Sarà solamente necessario anteporre il nome della classe di
    appartenenza. Ricordiamo anche che i metodi statici possono operare solo su variabili statiche, che anch'esse, essendo globali (e statiche) sono
    totalmente dissociate da possibili istanze della classe stessa (da oggetti).
    */
 
    // Init (1) --> default
    // Utilizzerà i valori forniti dalle espressioni costanti [constexpr] dichiarate all'inizio dell'intestazione
    static bool Init();
 
    // Init (2) --> parametrico
    // Utilizzerà i valori forniti dalle espressioni costanti [constexpr] dichiarate all'inizio dell'intestazione
    // Utilizzerà il valore fornito come parametro dall'utente richiamante questo metodo solamente per l'assegnazione del valore all'attributo 'm_TimeFormat'
    static bool Init(const TimeFormat& t_TimeFormat);
 
    // Init (3) --> parametrico
    // Utilizzerà i valori forniti dai parametri forniti dall'utente richiamante questo metodo
    static bool Init(WiFiUDP* t_UDPProtocol, const char* t_PoolingZone, const int& t_TimeOffset, const int& t_UpdateInterval, const TimeFormat& t_TimeFormat);
 
    /*Service management*/
private:
    // Inizia l'interrogazione del Time Server
    /*
    Questo metodo viene utilizzato per iniziare l'interrogazione del Time Server. Non è supposto come metodo richiamabile dall'utente, ma viene automaticamente richiamato
    in ciascun override del metodo 'Init'. 
    Non assicura un'effettivo inizio della procedura di interrogazione. Infatti, quest'ultima necessità di una connessione ad Internet. Per testarla verrà utilizzata la classe
    "ESP8266WiFi". In caso negativo, verrà restituito un valore booleano 'false' al metodo 'Init', che a sua volta comunicherà l'errore. 
    In questo caso sarà necessaria una richiamata del metodo 'Init', il quale effettuerà deallocazioni e reallocazioni e ritenterà con lo 'StartService'.
    Anche qua, per via della staticità, viene applicata la gestione analizzata prima.
    */
    static bool StartService();
 
    // Arresta l'interrogazione del Time Server
    /*
    Questo metodo viene utilizzato per arrestare l'interrogazione del Time Server. Non è supposto come metodo richiamabile dall'utente. Questo metodo viene richiamto
    ogni qualvolta l'oggetto 'm_UDPProtocol' sta per essere deallocato. Questo viene effettuato per garantire non tanto una corretta deallocazione, ma soprattutto
    una corretta chiusura della conversazione con il Time Server.
    Le effettive chiamate di questo metodo compaiono in ciascun override del metodo 'Init' durante la reallocazione con pre-deallocazione.
    Anche qua, per via della staticità, viene applicata la gestione analizzata prima.
    */
    static bool StopService();
 
    /*LowLevel getters*/
    /*
    I seguenti metodi LowLevel sono supposti soprattutto per uso a scopo di debug e management manuale.
    Forniscono un punto di accesso costante a VALORE MODIFICABILE (quindi dereferenziabile ma non reindirizzabile).
    In release mode, potrebbe risultare efficace cambiare il contrassegno da 'public' a 'private'.
    Anche qua, per via della staticità, viene applicata la gestione analizzata prima.
    */
public:
    // Ritorna un puntatore all'oggetto di classe "WiFiUDP"
    static WiFiUDP* const get_UDPProtocol();
 
    // Ritorna un puntatore all'oggetto di classe "NTPClient"
    static NTPClient* const get_NTPEntryPoint();
 
    // Ritorna un puntatore a 'm_PoolingZone'
    static const char* const get_PoolingZone();
 
    // Ritorna un puntatore a 'm_TimeOffset'
    static int* const get_TimeOffset();
 
    // Ritorna un puntatore a 'm_UpdateInterval'
    static int* const get_UpdateInterval();
 
    // Ritorna un puntatore a 'm_TimeFormat'
    static TimeFormat* const get_TimeFormat();
 
    // Ritorna un puntatore a 'm_TimePeriod'
    static TimePeriod* const get_TimePeriod();
 
    /*LowLevel reallocator*/
    /*
    Il seguente metodo è supposto soprattutto per uso a scopo di debug e management manuale.
    Esegue una riallocazione degli oggetti interessati con i corrispettivi coostruttori (di librerie 'WiFiUDP' e 'NTPClient') con i valori degli attributi interessati
    della classe.
    Inoltre, prima dell'effettiva riallocazione, esegue una deallocazione [delete] se necessaria.
    Il metodo ritorna un valore booleano, utilizzato per comunicare eventuali errori durante l'allocazione.
    Anche qua, per via della staticità, viene applicata la gestione analizzata prima.
    */
public:
    // Riesegue una operazione di inizializzazione con i valori degli attributi 'm_UDPProtocol', 'm_NTPEntryPoint', 'm_TimeOffset', 'm_UpdateInterval'
    static bool ReInit();
    
    /*Value Setters*/
public:
    // Imposta il valore dell'attributo 'm_TimeFormat'
    /*
    Metodo di impostazione che permette di impostare il valore dell'attributo 'm_TimeFormat' tramite il parametro 't_FormatTime' indicato dall'utente.
    Questo metodo restituisce un valore booleano per indicare se il valore fornito come parametro 't_TimeFormat' ha provocato o meno un cambiamento nel valore
    precedente di 'm_TimeFormat'. Quindi, si avrà in ritorno il valore 'false' se il 'm_TimeFormat' risulterà uguale a 'm_TimeFormat'.
    Anche qua, per via della staticità, viene applicata la gestione analizzata prima.
    */
    static bool set_TimeFormat(const TimeFormat& t_TimeFormat);
 
    /*Metodi*/
public:
    // Ritorna il valore corrispondente al giorno corrente
    /*
    Uno dei metodi principali di questa classe. 
    Ritorna il giorno corrente sincronizzato via connessione Internet.
    Anche qua, per via della staticità, viene applicata la gestione analizzata prima.
    */
    static int get_Day();
    
    // Ritorna il valore corrispondente all'ora corrente formattazione --> 'hh'
    /*
    Uno dei metodi principali di questa classe.
    Ritorna l'ora nel formato 'hh' corrente sincronizzata via connessione Internet.
    Anche qua, per via della staticità, viene applicata la gestione analizzata prima.
    */
    static int get_Hours();
    
    // Ritorna il valore corrispondente all'ora corrente formattazione --> 'mm'
    /*
    Uno dei metodi principali di questa classe.
    Ritorna l'ora corrente nel formato 'mm' corrente sincronizzata via connessione Internet.
    Anche qua, per via della staticità, viene applicata la gestione analizzata prima.
    */
    static int get_Minutes();
 
    // Ritorna il valore corrispondente all'ora corrente formattazione --> 'ss'
    /*
    Uno dei metodi principali di questa classe.
    Ritorna l'ora corrente nel formato 'ss' corrente sincronizzata via connessione Internet.
    Anche qua, per via della staticità, viene applicata la gestione analizzata prima.
    */
    static int get_Seconds();
 
    // Ritorna il valore corrispondente all'ora corrente formattazione --> 'hh:mm:ss'
    /*
    Il metodo principale di questa classe.
    Ritorna l'ora corrente sincronizzata via connessione Internet automaticamente formattata nel modo seguente --> 'hh:mm:ss'.
    L'ora corrente formattata in questo modo viene ritornata nel tipo 'String' [stringa].
    Anche qua, per via della staticità, viene applicata la gestione analizzata prima.
    */
    static String get_CurrentFormattedTime();
 
    // Ritorna il valore corrispondente all'ora corrente nella formattazione --> 'hh:mm'
    /*
    Il metodo principale di questa classe.
    Ritorna l'ora corrente sincronizzata via connessione Internet automaticamente formattata nel modo seguente --> 'hh:mm'.
    L'ora corrente formattata in questo modo viene ritornata nel tipo 'String' [stringa].
    Anche qua, per via della staticità, viene applicata la gestione analizzata prima.
    */
    static String get_CurrentFormattedTimeHM();
 
    // Ritorna il valore corrispondente all'ora corrente espressa in SECONDI passati dalla data "1 Gennaio 1900"
    /*
    Questo metodo ritorna il valore dell'ora corrente come "secondi passati dalla data "1 Gennaio 1900"".
    Ci aspettiamo un valore "enorme", per questo il tipo di ritorno è 'unsigned long'.
    Anche qua, per via della staticità, viene applicata la gestione analizzata prima.
    */
    static unsigned long get_EpochTime();
 
    // Ritorna il valore corrispondente al periodo durante la lettura in formato 12h
    /*
    Anche qua, per via della staticità, viene applicata la gestione analizzata prima.
    */
    static const TimePeriod get_Period();
    
    // Ritorna il valore corrispondente al formato corrente dell'ora 
    /*
    Anche qua, per via della staticità, viene applicata la gestione analizzata prima.
    */
    static const TimeFormat get_Format();
 
    /*Invalidator*/
    /*
    L'invalidatore consiste in quel valore che viene ritornato ogni qualvolta una chiamata da parte dell'utente ai metodi non produce il risultato atteso.
    E' importante specificare che, l'invalidatore, pur essendo costante, non deve essere dichiarato come 'constexpr' perchè NON deve seguire le regole di
    comportamento della direttiva '#define'. Il compilatore NON deve sostituire il nome dell'attributo con un valore numerico costante --> i.e. RVALUE!!
    L'invalidatore deve essere un vero e proprio attributo della classe, che però non deve mai appartenere ad uno specifico oggetto. Per questo deve essere sempre
    specificato come statico. Ovviamente, avrà una locazione nel Data Segment, sarà quindi globale ma statico (valido sono in questa unità di traslazione (file)) e utilizzabile
    solamente nell'ambito della classe di dichiarazione.
    */
    /*Attributo*/
private:
    // Valore costante che viene ritornato in caso di invalidità riscontrata nell'oggetto durante il dereferenziamento
    // per la chiamata dei metodi.
    // Il valore invalido utilizzato è un valore impossibile, cioè che non potrebbe essere mai restituito naturalmente.
    static const int m_Invalidator;
 
    /*getter*/
public:
    // Metodo per il ritorno del valore dell'Invalidatore. Verrà ritornata una referenza [reference --> '&'] costante, in modo tale da ottimizzare il processo e,
    // allo stesso tempo evitare modifiche inappropriate.
    /*
    Un'altra particolarità di questo metodo sta nel fatto che è definita come 'inline'. Questa keyword comunica al compilatore, ovunque trovi una chiamata
    a questo metodo, di NON effettuare una vera e propria chiamata, ma di sostituire la porzione del codice per la chiamata con il BODY del metodo (la implementazione stessa).
    Questa tecnica risulta molto utile per funzioni che effettuano pochissime operazioni e sono sottoposte a frequenti chiamate.
    Anche qua, per via della staticità, viene applicata la gestione analizzata prima.
    */
    static inline const int& get_Invalidator();
};
 
// Dichiarazione delle variabili GLOBALI STATICHE 
// Risiederanno nel Data Segment
/*
Essendo statiche in classe, tutti gli attributi non sono altro che variabili GLOBALI STATICHE.
Per questo è richiesta la dichiarazione globale. Non è necessario specificare 'static' essendo già stato specificato nella dichiarazione degli
attributi nella classe stessa.
*/
WiFiUDP* Clock::m_UDPProtocol = nullptr;
NTPClient* Clock::m_NTPEntryPoint = nullptr;
const char* Clock::m_PoolingZone;
int Clock::m_TimeOffset;
int Clock::m_UpdateInterval;
Clock::TimeFormat Clock::m_TimeFormat;
Clock::TimePeriod Clock::m_Period;
const int Clock::m_Invalidator = Clock__file::_invalidvalue;