StopWatchData.h

Go to the documentation of this file.

#pragma once
 
#pragma region INCLUSIONS
// Classe per sfruttare la sincronizzazione online dell'ora corrente per la sincronia del cronometro
/*
Classe di autori 'Grandieri Andrea', 'Barsotti Mirko', 'Erba Lorenzo' per la sincronizzazione online dell'ora corrente.
Verrà utilizzata anche per il timing del cronometro fornendo una precisione fino all'unità "picosecondo".
*/
#include "Clock.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 StopWatchData__file
{
    // Espressione costante (equivalente della direttiva '#define') per la definizione del valore '_initvalue'.
    // Questo valore rappresenta il valore assegnato agli attributi 'm_Time', 'm_BaseTime', 'm_OldTime' durante la fase di costruzione
    // attraverso il costruttore di default.
    // All'attributo 'm_isWorking' verrà assegnato il valore di default 'WorkingState::OFFLINE'.
    static constexpr auto _initvalue = 0;
 
    // Valore per eseguire l'adattamento 'Elegant Adjustment'
    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;
}
 
class StopWatchData
{
    /*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 WorkingState
    {
        ONLINE,
        OFFLINE,
 
        // Lo stato 'INVALID' viene aggiunto per permettere un più semplice "WRAPPERING" (incapsulamento) della classe stessa "StopWatchData".
        // In questo caso, essendo la classe destinata all'incapsulamento in "StopWatch", è stato aggiunto quest'ultimo stato.
        // Questo stato verrà restituito NON da questa classe CORE, ma direttamente dal WRAPPER, in caso gli altri due stati
        // non siano accessibili (probabilmente per una mancata allocazione iniziale).
        INVALID
    };
 
    /*Attributi*/
private:
    // Variabile contenente il valore corrente del cronometro
    /*
    Questa variabile conterrà il valore corrente del cronometro. Verrà aggiornata ad ogni chiamata del metodo 'get_CurrentFormattedStopWatch'.
    Verrà anche utilizzata per mantenere in memoria il valore del cronometro anche dopo il suo arresto e il successivo avvio dello stesso.
    La variabile è stata resa di tipo 'unsigned long' per permetterli di contenere i valori forniti dal metodo "get_EpochTime" della classe "Clock"
    */
    unsigned long m_Time;
 
    // Variabile contenente la Base del 'Time' dalla quale iniziare per il calcolo dell'Offset
    /*
    Questa variabile è necessaria proprio per la natura del funzionamento di questo cronometro. Esso si baserà sulla presenza di una connessione Internet utilizzata
    per la sincronizzazione online dell'ora corrente. Alla chiamata del metodo 'Start' verrà campionata l'ora corrente e salvata in questa variabile. Da quel momento
    in poi (fino alla chiamata di 'Stop') il valore del cronometro 'm_Time' non sarà altro che l'Offset tra l'ora precedentemente campionata 'm_BaseTime' e l'ora
    corrente, ottenuta grazie ai metodi della classe "Clock".
    Si effettueranno operazioni sull'ora corrente espressa in secondi, secondo i valori ottenuti dal metodo "get_EpochTime" della classe "Clock"
    */
    unsigned long m_BaseTime;
 
    // Variabile contente il valore precedente del cronometro, salvato nel momento dello 'Stop'
    /*
    Questa variabile consente la ripresa dell'esecuzione del cronometro dopo l'arresto dal punto nel quale si era fermato.
    Il valore di 'm_Time' verrà salvato in 'm_OldTime' durante la chiamata al metodo 'Stop'.
    Nel caso non è stata indivuata ancora alcuna chiamata al metodo, il valore sarà '_initvalue' in modo tale da non interferire con 
    i calcoli correnti.
    */
    unsigned long m_OldTime;
 
    // Variabile contenente lo stato corrente del cronometro
    /*
    Questa variabile contiene il valore dello stato corrente del cronometro. Essendo di tipo booleano, può assumere soltanto due stati, corrispondenti 
    al cronometro in funzione oppure no. Servirà a gestire possibili eccezioni causate dalla ripetuta chiamata al metodo 'Start' o 'Stop'.
    */
    WorkingState m_WorkingState;
 
    // Variabile per la gestione dell'errore
    /*
    Il cronometro è stato realizzato in modo tale da "auto-resettarsi" in caso di errore di connessione alla rete Internet.
    Questo per garantire una corretta sincronizzazione, che rischierebbe di venir persa in caso di continue sconnessioni e riconessioni alla rete.
    */
    bool m_isErrorOccured;
 
    /*Costruttori e Distruttori*/
public:
    // Costruttore default
    /*
    Il costruttore di default di questa classe inizializza un oggetto di classe "StopWatchData" che raprresenta un cronometro.
    Inizialmente i valori degli attributi sono impostati al valore default della constexpr '_initvalue'.
    Possono esistere contemporaneamente più istanze di questa classe, ognuna rappresentante un diverso cronometro.
    Nonostante ciò, bisogna prestare attenzione alla concorrenza di chiamata per i metodi della classe "Clock"
    */
    StopWatchData();
 
    // Distruttore
    /*
    Il distruttore di questa classe semplicemente dealloca l'oggetto interessato. Questo provocherà la perdita di tutte le informazioni annesse.
    Prima di ciò, verrà eseguita una chiamata di sicurezza al metodo 'Stop'.
    */
    ~StopWatchData();
 
    /*Service Management*/
public:
    // Una volta richiamato, il cronometro verrà avviato.
    /*
    Questo metodo permette un semplice avvio del cronometro. Dal momento della chiamata in poi il cronometro sarà in funzione.
    Da ricordare che questo metodo restituisce un valore booleano nel caso l'avvio non sia riuscito 'false', oppure nel caso l'avvio sia riuscito 'true'.
    Questo metodo NON fornisce in ritorno il valore corrente del cronometro.
    */
    bool Start();
 
    // Una volta richiamato, il cronometro verrà arrestato.
    /*
    Questo metodo permette un semplice arresto del cronometro. Dal momento della chiamata in poi il cronometro NON sarà in funzione.
    Questo non signfica perdere i valori, ma solamente fermare il cronometro. Il valore 'm_Time' conterrà l'ultimo valore registrato dal cronometro.
    Per perdere questo valore bisognerà creare una nuova istanza di questa classe.
    Un successivo avvio del cronometro ripartirà dal precedente valore 'm_Time'.
    */
    bool Stop();
 
private:
    // Opera con il metodo 'get_EpochTime' della classe "Clock" per calcolare il tempo base 'm_BaseTime' dal quale successivamente
    // calcolare l'offset.
    /*
    Questo metodo rappresenta una risorsa privata non richiamabile direttamente dall'utente.
    Il suo compito è effettuare le operazioni necessarie a determinare il valore base del cronometro. Alla fine, salva questo valore nell'attributo
    'm_BaseTime'.
    Questo metodo verrà automaticamente richiamato al richiamo, da parte dell'utente, dei metodi 'getter' disponibili.
    Il valore che verrà salvato nell'attributo 'm_BaseTime' è espresso in secondi
    */
    void get_BaseTime();
 
    // Opera in maniera diretta su 'Base' ed 'Offset' per calcolare i valori di distanza.
    // Salva nell'attributo 'm_Time' il valore corrente del cronometro.
    /*
    Questo metodo rappresenta una risorsa privata non richiamabile direttamente dall'utente.
    Il suo compito è effettuare le operazioni necessarie a determinare il valore corrente del cronometro. Alla fine, salva questo valore nell'attributo
    'm_Time'.
    Questo metodo verrà automaticamente richiamato al richiamo, da parte dell'utente, dei metodi 'getter' disponibili.
    Il valore che verrà salvato nell'attributo 'm_Time' è espresso in secondi, secondo i valori ritornati dal metodo "get_EpochTime" della classe "Clock".
    Sarà necessaria una conversione per ottenere il formato --> 'hh:mm:ss'
    */
    bool get_Time();
 
    /*Metodi*/
public:
    // Ritorna il valore corrispondente al valore corrente del cronometo secondo la formattazione --> 'hh:mm:ss'
    /*
    Questo metodo rappresenta il principale scopo della classe: ottenere il valore del cronometro.
    Il tipo restituito è 'String' [stringa]. Il formato dei valori è --> 'hh:mm:ss'
    */
    String get_CurrentFormattedStopWatch();
 
    // Ritorna il valore corrispondente allo stato attuale di funzionamento del cronometro
    /*
    Questo metodo permette di ottenere come valore di ritorno lo stato attuale del cronometro.
    Sono possibili 2 stati:
    'WorkingState::OFFLINE' --> il cronometro non è in funzione
    'WorkingState::ONLINE' --> il cronometro è in funzione
    */
    const WorkingState& get_WorkingState();
 
    // Controlla la disponibilità di una connessione Internet. In caso negativo, effettua il reset di sicurezza del valore del cronometro
    void Trigger_to_Check();
 
    /*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_CoreInvalidator;
 
    /*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.
    */
    /*L'invalidatore del CORE (questa unità di traslazione [file]) prende il nome di 'CoreInvalidator' (i.e. 'invalidatore del nucleo').
    Questo è reso necessario per l'identificazione della differenza tra invalidatore del WRAPPER e invalidatore del CORE.
    Come riportato nel brief del WRAPPER, l'unico invalidatore al quale l'utente deve aver accesso è quello del WRAPPER 'Invalidator'.
    L'invalidatore del CORE 'CoreInvalidator' è necessario solamente per la gestione dell'invalidatore del WRAPPER 'Invalidator' che dipende in parte (non in ogni caso, ma solo in alcuni)
    dall'invalidatore del CORE 'CoreInvalidator'. L'invalidatore del CORE non deve essere disponibile all'utente.*/
    static inline const int& get_CoreInvalidator();
};
 
// 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.
*/
const int StopWatchData::m_CoreInvalidator = StopWatchData__file::_invalidvalue;
 
//////////////////////////////////////////////////////////////////////////