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 improtant 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();
    }
}