# Alarm Client

The IAlarmClient is simple alarm client interface that can be used to send alarms and events to an alarm server. Upon receiving the first alarm/event, the alarm/event is queued and an http connection is established. When the connection is up, the alarm is successfully sent via POST.
Active alarms are continuously send (in ~ 30 minutes interval) until a clear alarm is recieved. When the connection to the alarm server is down, the alarm client tries to re-establish it (increasing reconnect timer) until the connection is up. In this case, the queued alarms/events are resent.

## File information

File | common/interface/alarm_client.h
Classes | IAlarmClient UAlarmClient
Data types | ac_shutdown_reason AlarmSeverity AlarmType
Examples | IAlarmClient

# Classes

## IAlarmClient

    class IAlarmClient {
    public:
        static IAlarmClient * Create(class IIoMux * const iomux,
                                    class ISocketProvider * const tcpSocketProvider,
                                    class ISocketProvider * const tlsSocketProvider,
                                    class UAlarmClient * const user,
                                    class IInstanceLog * const log,
                                    char * url,
                                    char * username,
                                    char * pwd,
                                    class IDns * const dns = nullptr);
        virtual ~IAlarmClient() {};
        virtual void SetAlarm(dword code, AlarmSeverity severtiy, ulong64 time, const char * text, const char * details, const char * src);
        virtual void ClearAlarm(dword code, AlarmSeverity severtiy, ulong64 time, const char * text, const char * details, const char * src);
        virtual void SendEvent(dword code, AlarmSeverity severtiy, ulong64 time, const char * text, const char * details, const char * src);
        virtual void ResetConnection(char * url, char * username, char * pwd);
        virtual void Shutdown();
        virtual void ChangeAlarmTimeout(unsigned int timeout);
    };

### Overview

This is the interface to send alarms and events to a defined alarm server.

### Logging

To enable logging for IAlarmClient, the flag LOG_ALARM_CLIENT must be set in the Managers diagnostic settings.

### Public Functions

Create
  This static function creates the IAlarmClient instance. The returned instance must be release if no longer needed by using the C++ delete operator.

  #### Parameters

  class IIoMux * const iomux | The IIoMux instance that IAlarmClient instance will register to.
  class ISocketProvider * const tcpSocketProvider | A ISocketProvider instance that can create a TCP ISocket.
  class ISocketProvider * const tlsSocketProvider | A ISocketProvider instance that can create a TLS ISocket.
  class UAlarmClient * const user | The UAlarmClient instance that will receive the callbacks of IAlarmClient.
  class IInstanceLog * const log | The IInstanceLog instance used for loging purposes.
  char * url | The address of the alarm server to connect to.
  char * username | The username to connect to the alarm server for authentication.
  char * pwd | The password to connect to the alarm server for authentication.
  class IDns * const dns | A IDns instance that provides DNS resolution.

  #### Return value

  The IAlarmClient instance which should be freed as soon as it is no longer used by calling the C++ delete operator.
SetAlarm
  This function sets an alarm and then sends it to the alarm server, if a connection is established. If the connection to the alarm server could not be established, the alarm is saved to be sent later. Alarms are continuoesly sent until a clear alarm is received.

  #### Parameters

  dword code | A unique code which identifies the alarm
  AlarmSeverity severtiy | Defines the severity of the alarm set.
  ulong64 time | The time at which the alarm was set (timestamp time in seconds)
  const char * text | A string which describes the name or purpose of the alarm
  const char * details | Additional details that might be improtant when the alarm was set.
  const char * src | The source which set the alarm

ClearAlarm
  This function clears a previuosly set alarm. If the connection to the alarm server could not be established, the cleared alarm is saved to be sent later. Clear alarms received are queued first before sending.

  #### Parameters

  dword code | A unique code which identifies the alarm
  AlarmSeverity severtiy | Defines the severity of the alarm
  ulong64 time | The time at which the alarm was cleared (timestamp time in seconds)
  const char * text | A string which describes the name or purpose of the alarm
  const char * details | Additional details that might be improtant when the alarm was cleared.
  const char * src | The source which cleared the alarm

SendEvent
  This function sends an event to the alarm server. If the connection to the alarm server could not be established, the event is saved to be sent later. Events received are queued first before sending.

  #### Parameters

  dword code | A unique code which identifies the event
  AlarmSeverity severtiy | Defines the severity of the event
  ulong64 time | The time at which the event was sent (timestamp time in seconds)
  const char * text | A string which describes the name or purpose of the event
  const char * details | Additional details that might be important to the event.
  const char * src | The source which sent the event

ResetConnection
  Resets the connection to the alarm server, by closing the previuos connection (if any) and establishing a new one.

  #### Parameters

  char * url | The address of the new alarm server
  char * username | The username for authentication
  char * password | The password for authentication

Shutdown
  Shuts down the connection to the alarm server.

  #### Callbacks

  After the connection is gracefully closed, UAlarmClient::AlarmClientShutdown() will be called.
ChangeAlarmTimeout
  Changes the default timeout of the alarms. This function is used only for test purposes.

## UAlarmClient

    class UAlarmClient {
    public:
        ~UAlarmClient() {}
        virtual void AlarmClientShutdown(IAlarmClient * const alarmClient);
    };

### Overview

The UAlarmClient class is used to receive callbacks from an IAlarmClient instance. An application must subclass UAlarmClient, implement the functions that must be implemented and pass that class as user to IAlarmClient::Create(). The instance of that subclass must not be freed before the IAlarmClient instance assigned to. One UAlarmClient instance can be assigned to multiple IAlarmClient instances, because the calling IAlarmClient will be passed as parameter to the callback functions.

### Public functions

AlarmClientShutdown
  Will be called, after calling IAlarmClient::Shutdown() and after the connection had been closed.

  #### Parameters

  class IAlarmClient * const alarmClient | The calling IAlarmClient instance.

# Data types

## ac_shutdown_reason

### Overview

When the connection had been closed, UAlarmClient::AlarmClientShutdown() will be called with the reason for closing the connection.

#### Values

AC_SHUTDOWN_NORMAL | The conenction had been closed successfully.
AC_HTTP_CONNECTION_ERROR | The conenction had been closed due to an http error.

## AlarmSeverity

### Overview

Defines the severity of an alarm or event, which is used for SetAlarm, ClearAlarm and SendEvent functions.

#### Values

ALARM_SEVERITY_INDETERMINATE
ALARM_SEVERITY_MAJOR
ALARM_SEVERITY_CRITICAL

## AlarmType

### Overview

Defines internally the type of the alarm or event to be send to the alarm server.

#### Values

SET_ALARM | The alarm type is set after a call to SetAlarm.
CLEAR_ALARM | The alarm type is set after a call to ClearAlarm.
ERROR | The event type is set after a call to SendEvent.

# Code Example

## IAlarmClient

    void app::CreateAlarm(char * url, char * username, char * pwd)
    {
        this->alarmClient = IAlarmClient::Create(iomux, tcpSocketProvider, tlsSocketProvider, this, this, url_1, username_1, pwd_1);
    }
    void app::SetAlarm()
    {
        this->alarmClient->SetAlarm(FAULT_CODE_1, ALARM_SEVERITY_CRITICAL, ITime::TimeStampMilliseconds() / 1000, text, details, app_SRC));
    }
    void app::ClearAlarm()
    {
        this->alarmClient->ClearAlarm(FAULT_CODE_1, ALARM_SEVERITY_INDETERMINATE, ITime::TimeStampMilliseconds() / 1000, text, details, app_SRC);
    }
    void app::SendEvent()
    {
        this->alarmClient->SendEvent(ERROR_CODE_1, ALARM_SEVERITY_MAJOR, ITime::TimeStampMilliseconds() / 1000, text, details, app_SRC);
    }
    void * app::ResetConnection()
    {
        this->alarmClient->ResetConnection(url_2, username_2, pwd_2);
    }
    void app::Shutdown()
    {
        if (this->alarmClient) {
            this->alarmClient->Shutdown();
        }
    }