#ifndef WDT_H
#define WDT_H

#ifdef __cplusplus
extern "C" {
#endif

#define WDT_OK                   0
#define WDT_REQUEST              1
#define WDT_ALREADY_REGISTERED  -1
#define WDT_UNKNOWN_HANDLE      -2
#define WDT_INVALID_TIMEOUT     -3
#define WDT_RESOURCE_ERROR      -4
#define WDT_INVALID_NAME        -5

/**
 * Kündigt das Starten einer Applikation an.
 *
 * name: null-terminierter Name des Prozesses (muß eindeutig sein)
 * timeout: Intervall in Sekunden, innerhalb dessen sich die Applikation mit demselben Namen
 *          registrieren muß.
 *
 * returns: WDT_OK, wenn erfolgreich
 */
int watchdog_announce(const char *name, int timeout);

/**
 * Registriert einen Prozeß beim Watchdog
 * Der Default-Timeout ist hardwareabhängig und liegt zwischen 2 * 5s bis 2 * 20s
 * Es empfehlen sich aber Werte von ca. 100s (siehe watchdog_settimeout)
 * Zur halben Zeit wird die Applikation benachrichtigt (optional)
 *
 * name: null-terminierter Name des Prozesses (muß eindeutig sein)
 *
 * returns:    > 0: handle für registrierten Prozeß, sonst Fehler
 */
int watchdog_register(const char *name);

/**
 * Liefert den Filehandle zum Watchdog-Handle zurück
 *
 * handle: Beim Register erhaltener Handle
 * returns: file handle
 */
int watchdog_get_fd(int handle);

/**
 * Deregistriert einen Prozeß beim Watchdog
 *
 * handle: Beim Register erhaltener Handle
 *
 * returns: WDT_OK, wenn erfolgreich, sonst Fehler
 *
 * NOTE: Ein Prozeß muß sich per watchdog_release() abmelden, bevor er sich beendet,
 *       anderenfalls wird ein Reboot ausgelöst! Dies gilt auch für den Fall, daß der
 *       Prozeß von einem anderen Prozeß (gewollt) beendet wird. Hierfür ist ein
 *       watchdog_release() im Signal-Handler vorzusehen.
 */
int watchdog_release(int handle);

/**
 * Ändert den default Timeout für den registrierten Prozeß
 *
 * handle:  Beim Register erhaltener Handle
 * timeout: neuer Timeout in Sekunden ab sofort
  * Es empfehlen sich Werte von ca. 100s
 *
 * returns: WDT_OK, sonst Fehler
 *
 * NOTE: watchdog_settimeout() dient gleichzeitig als Trigger für den Watchdog
 */
int watchdog_settimeout(int handle, int timeout);

/**
 * Triggert den Watchdog für den angegebenen Prozeß
 *
 * handle:  Beim Register erhaltener Handle
 *
 * returns: WDT_OK, sonst Fehler
 */
int watchdog_trigger(int handle);

/**
 * Blockiert, bis Watchdog neu getriggert werden muß
 * Nach Rückkehr aus der Funktion hat die Applikation noch die Hälfte des gesetzten Timeouts
 * Zeit zum Zurücksetzen des Watchdogs.
 *
 * handle:  Beim Register erhaltener Handle
 *
 * returns: WDT_OK, sonst Fehler
 * @retval WDT_REQUEST
 */
int watchdog_wait(int handle);

/**
 * Teilt mit, ob der Watchdog neu getriggert werden muß.
 * Die Funktion blockiert nicht.
 *
 * handle:  Beim Register erhaltener Handle
 *
 * returns: WDT_OK vor Ablauf der Hälfte des gesetzten Timeouts, ungleich WDT_OK danach
 * @retval WDT_REQUEST
 */
int watchdog_poll(int handle);

/**
 * Startet die Watchdog-Init-Überwachung
 * timeout: Maximale Init-Prozess-Überwachung in Sekunden
 * Ein Überschreiten führt zum Reboot der Box
 *
 * returns: WDT_OK, sonst Fehler
 */
int watchdog_init_start(int timeout);

/**
 * Beendet die Watchdog-Init-Überwachung
 *
 * returns: WDT_OK, sonst Fehler
 */
int watchdog_init_done(void);

#ifdef __cplusplus
}
#endif

#endif // WDT_H