Alarm.h

Go to the documentation of this file.

#pragma once
 
// Macro per sovvertire alla presenza dell'enumerazione 'AlarmState' nella classe CORE "AlarmData", alla quale l'utente non 
// deve avere accesso
/*
L'utente deve poter utilizzare l'enumerazione degli stati 'AlarmState' come se fosse definita all'interno del WRAPPER "Alarm".
Questo è più complicato dato dal fatto che l'enumerazione, per la logica sulla quale si basa il progetto, si trova nel CORE "AlarmData"
[classe] alla quale l'utente non ha accesso.
Per "risolvere" questo inconvenite risulta "comodo" "ingannare l'utente" "facendoli sembrare" che l'enumerazione si trovi nel WRAPPER "Alarm".
Altri metodi potrebbero prevedere la riformulazione totale della logica base sulla quale si basa il progetto.
In questo caso, però, avendo sia CORE e corrispondente WRAPPER, risulta più logico definire tutte le eventuali enumerazioni nel CORE.
Il WRAPPER fungerà solamente da TRAMITE e INTERPRETE tra utente e codice.
*/
#define Alarm__AlarmState AlarmData::AlarmState
 
#pragma region INCLUSIONS
 // Classe per la gestione dell'oggetto SVEGLIA
 /*
 Classe di autori 'Grandieri Andrea', 'Barsotti Mirko', 'Erba Lorenzo' rappresentante l'oggetto SVEGLIA e tutti gli attributi
 e i metodi associati.
 */
#include "AlarmData.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 Alarm__file
{
    // Espressione costante (equivalente della direttiva '#define') per la definizione del valore '_invalidvalue'
    // 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 Alarm
{
    /*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
    Alarm() = default;
    // Blocco attraverso privatizzazione del distruttore trivial
    ~Alarm() = default;
 
    /*Attributi*/
private:
    // Puntatore all'oggetto sveglia di classe "AlarmData"
    /*
    Questa variabile conterrà l'istanza dell'oggetto di classe "StopWatchData" creata durante l'operazione di inizializzazione.
    Questo oggetto rappresenta una vera e propria sveglia. Fornisce tutti i metodi necessari alla sua gestione e implementa una comunicazione
    generica degli errori.
    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 AlarmData* m_Alarm;
 
    /*Init*/
public:
    // Inizializza la sveglia con il rispettivo costruttore
    /*
    Questo metodo, fondamentale, "dà vita" alla sveglia. Effettua una allocazione (dinamica [heap]) attraverso il rispettivo costruttore della classe
    "AlarmData".
    Analizzando questo costruttore, notiamo come non accetti nessun parametro. Possiamo quindi trattarlo come un costruttore di default.
    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).
    */
    static bool Init();
 
    /*Value Setters*/
    // Permette l'impostazione dello stato della sveglia
    /*
    Per fare ciò, effettua una chiamata ad uno specifico metodo implementato nella classe "AlarmData"
    Restituisce un valore booleano per comunicare la corretta assegnazione dei valori 'true' oppure no 'false'
    Permette quindi, la gestione ad alto livello lasciata all'utente.
    Anche qua, per via della staticità, viene applicata la gestione analizzata prima.
    */
    // set_Time (1)
    static bool set_Time(const unsigned int& t_Hour, const unsigned int& t_Minute);
 
    // set_Time (2)
    static bool set_Time(const unsigned int& t_Hour, const unsigned int& t_Minute, const Clock::TimePeriod& t_Period);
 
    // set_Time (3)
    static bool set_Time(const String& t_Value);
 
    // set_Time (4)
    static bool set_Time(const String& t_Value, const Clock::TimePeriod& t_Period);
 
    // Permette l'impostazione dello stato della sveglia
    /*
    Per fare ciò, effettua una chiamata ad uno specifico metodo implementato nella classe "AlarmData"
    Restituisce un valore booleano per comunicare la corretta assegnazione dei valori 'true' oppure no 'false'
    Permette quindi, la gestione ad alto livello lasciata all'utente.
    Anche qua, per via della staticità, viene applicata la gestione analizzata prima.
    */
    static bool set_State(const AlarmData::AlarmState& t_State);
 
    /*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 "StopWatchData"
    static AlarmData* const get_Alarm();
 
    /*LowLevel reallocator*/
    // In questo caso, non è necessaria l'implementazione essendo equivalente al metodo 'Init'
 
    /*Metodi*/
public:
    // Restituisce, in tipo 'String' [stringa], l'ora impostata per il trigger della sveglia
    /*
    Per fare ciò, effettua una chiamata ad uno specifico metodo implementato nella classe "AlarmData"
    Anche qua, per via della staticità, viene applicata la gestione analizzata prima.
    */
    static String get_SetTime();
 
    // Controlla se la sveglia è in trigger oppure no al momento della chiamata del medesimo metodo
    /*
    Per fare ciò, effettua una chiamata ad uno specifico metodo implementato nella classe "AlarmData"
    Restituisce un valore booleano in base al trigger:
    - 'true' --> sveglia in trigger nel momento della chiamata
    - 'false' --> sveglia non in trigger nel momento della chiamata
    Anche qua, per via della staticità, viene applicata la gestione analizzata prima.
    */
    static bool Check();
 
    // Effettua l'aggiornamento del formato dell'ora dal punto di vista di AlarmData per sincronizzarlo con quello di Clock
    static bool UpdateFormat();
 
    /*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.
*/
AlarmData* Alarm::m_Alarm;
const int Alarm::m_Invalidator = Alarm__file::_invalidvalue;
 
//////////////////////////////////////////////////////////////////////////