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

Filecommon/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 iomuxThe IIoMux instance that IAlarmClient instance will register to.
class ISocketProvider * const tcpSocketProviderA ISocketProvider instance that can create a TCP ISocket.
class ISocketProvider * const tlsSocketProviderA ISocketProvider instance that can create a TLS ISocket.
class UAlarmClient * const userThe UAlarmClient instance that will receive the callbacks of IAlarmClient.
class IInstanceLog * const logThe IInstanceLog instance used for loging purposes.
char * urlThe address of the alarm server to connect to.
char * usernameThe username to connect to the alarm server for authentication.
char * pwdThe password to connect to the alarm server for authentication.
class IDns * const dnsA 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 codeA unique code which identifies the alarm
AlarmSeverity severtiyDefines the severity of the alarm set.
ulong64 timeThe time at which the alarm was set (timestamp time in seconds)
const char * textA string which describes the name or purpose of the alarm
const char * detailsAdditional details that might be improtant when the alarm was set.
const char * srcThe 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 codeA unique code which identifies the alarm
AlarmSeverity severtiyDefines the severity of the alarm
ulong64 timeThe time at which the alarm was cleared (timestamp time in seconds)
const char * textA string which describes the name or purpose of the alarm
const char * detailsAdditional details that might be improtant when the alarm was cleared.
const char * srcThe 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 codeA unique code which identifies the event
AlarmSeverity severtiyDefines the severity of the event
ulong64 timeThe time at which the event was sent (timestamp time in seconds)
const char * textA string which describes the name or purpose of the event
const char * detailsAdditional details that might be improtant to the event.
const char * srcThe 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 * urlThe address of the new alarm server
char * usernameThe username for authentication
char * passwordThe 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 alarmClientThe 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_NORMALThe conenction had been closed successfully.
AC_HTTP_CONNECTION_ERRORThe 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_ALARMThe alarm type is set after a call to SetAlarm.
CLEAR_ALARMThe alarm type is set after a call to ClearAlarm.
ERRORThe 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();
    }
}