gnustep/libs-ec
0
0
Fork 0
mirror of https://github.com/gnustep/libs-ec.git synced 2025-02-16 00:21:01 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
libs-ec/EcAlarm.h
Richard Frith-Macdonald 2484af9894 improve commentds/doc
2020-07-20 13:16:30 +01:00

686 lines
27 KiB
Objective-C
Raw Blame History

/** Enterprise Control Configuration and Logging
Copyright (C) 2012 Free Software Foundation, Inc.
Written by: Richard Frith-Macdonald <rfm@gnu.org>
Date: Febrary 2010
Originally developed from 1996 to 2020 by Brainstorm, and donated to
the FSF.
This file is part of the GNUstep project.
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 3 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Library General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free
Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
Boston, MA 02111 USA.
*/
#ifndef _ECALARM_H
#define _ECALARM_H
#import <Foundation/NSObject.h>
@class NSCoder;
@class NSDate;
@class NSDictionary;
@class NSString;
/**
* The EcAlarmEventType enumeration defines the different types of
* alarm we support.<br />
* The enumerated values MUST be matched by those in your SNMP MIB if
* you wish to have your software interact with SNMP tools.<br />
* NB. EcAlarmEventTypeUnknown must <em>NOT</em> be used in an alarm ...
* it is employed solely as a marker for the case where a lookup of
* type from probable cause can not determine a specific event type.
* <deflist>
* <term>EcAlarmEventTypeUnknown</term>
* <desc>Not used</desc>
* <term>EcAlarmEventTypeCommunications</term>
* <desc>A communications/networking/protocol issue</desc>
* <term>EcAlarmEventTypeEnvironmental</term>
* <desc>An external environmental issue (eg building on fire)</desc>
* <term>EcAlarmEventTypeEquipment</term>
* <desc>A hardware problem (eg disk failure)</desc>
* <term>EcAlarmEventTypeProcessingError</term>
* <desc>A software problem (a bug or misconfiguration)</desc>
* <term>EcAlarmEventTypeQualityOfService</term>
* <desc>A system not running as well as expected ... eg. overloaded</desc>
* </deflist>
*/
typedef enum {
EcAlarmEventTypeUnknown = 0,
EcAlarmEventTypeCommunications = 2,
EcAlarmEventTypeEnvironmental = 3,
EcAlarmEventTypeEquipment = 4,
EcAlarmEventTypeProcessingError = 10,
EcAlarmEventTypeQualityOfService = 11,
} EcAlarmEventType;
/** The EcAlarmProbableCause enumeration defines the probable causes of
* alarms produced by the system.<br />
* These are taken from the CCITT X.733 specification with the numeric
* values from the CCITT X.721 specification.<br />
* Enumeration values include a comment to specify which
* EcAlarmEventType they apply to.
* <deflist>
* <term>EcAlarmProbableCauseUnknown</term>
* <desc>Category: Any</desc>
* <term>EcAlarmAdapterError</term>
* <desc>Category: Equipment</desc>
* <term>EcAlarmApplicationSubsystemFailure</term>
* <desc>Category: Processing</desc>
* <term>EcAlarmBandwidthReduced</term>
* <desc>Category: QoS</desc>
* <term>EcAlarmCallEstablishmentError</term>
* <desc>Category: Communications</desc>
* <term>EcAlarmCommunicationsProtocolError</term>
* <desc>Category: Communications</desc>
* <term>EcAlarmCommunicationsSubsystemFailure</term>
* <desc>Category: Communications</desc>
* <term>EcAlarmConfigurationOrCustomizationError</term>
* <desc>Category: Processing</desc>
* <term>EcAlarmCongestion</term>
* <desc>Category: QoS</desc>
* <term>EcAlarmCorruptData</term>
* <desc>Category: Processing</desc>
* <term>EcAlarmCpuCyclesLimitExceeded</term>
* <desc>Category: Processing</desc>
* <term>EcAlarmDataSetOrModemError</term>
* <desc>Category: Equipment</desc>
* <term>EcAlarmDegradedSignal</term>
* <desc>Category: Communications</desc>
* <term>EcAlarmDTE_DCEInterfaceError</term>
* <desc>Category: Communications</desc>
* <term>EcAlarmEnclosureDoorOpen</term>
* <desc>Category: Environmental</desc>
* <term>EcAlarmEquipmentMalfunction</term>
* <desc>Category: Equipment</desc>
* <term>EcAlarmExcessiveVibration</term>
* <desc>Category: Environmental</desc>
* <term>EcAlarmFileError</term>
* <desc>Category: Processing</desc>
* <term>EcAlarmFireDetected</term>
* <desc>Category: Environmental</desc>
* <term>EcAlarmFloodDetected</term>
* <desc>Category: Environmental</desc>
* <term>EcAlarmFramingError</term>
* <desc>Category: Communications</desc>
* <term>EcAlarmHeatingOrVentilationOrCoolingSystemProblem</term>
* <desc>Category: Environmental</desc>
* <term>EcAlarmHumidityUnacceptable</term>
* <desc>Category: Environmental</desc>
* <term>EcAlarmInputOutputDeviceError</term>
* <desc>Category: Equipment</desc>
* <term>EcAlarmInputDeviceError</term>
* <desc>Category: Equipment</desc>
* <term>EcAlarmLANError</term>
* <desc>Category: Communications</desc>
* <term>EcAlarmLeakDetected</term>
* <desc>Category: Environmental</desc>
* <term>EcAlarmLocalNodeTransmissionError</term>
* <desc>Category: Communications</desc>
* <term>EcAlarmLossOfFrame</term>
* <desc>Category: Communications</desc>
* <term>EcAlarmLossOfSignal</term>
* <desc>Category: Communications</desc>
* <term>EcAlarmMaterialSupplyExhausted</term>
* <desc>Category: Environmental</desc>
* <term>EcAlarmMultiplexerProblem</term>
* <desc>Category: Equipment</desc>
* <term>EcAlarmOutOfMemory</term>
* <desc>Category: Processing</desc>
* <term>EcAlarmOutputDeviceError</term>
* <desc>Category: Equipment</desc>
* <term>EcAlarmPerformanceDegraded</term>
* <desc>Category: QoS</desc>
* <term>EcAlarmPowerProblem</term>
* <desc>Category: Equipment</desc>
* <term>EcAlarmPressureUnacceptable</term>
* <desc>Category: Environmental</desc>
* <term>EcAlarmProcessorProblem</term>
* <desc>Category: Equipment</desc>
* <term>EcAlarmPumpFailure</term>
* <desc>Category: Environmental</desc>
* <term>EcAlarmQueueSizeExceeded</term>
* <desc>Category: QoS</desc>
* <term>EcAlarmReceiveFailure</term>
* <desc>Category: Equipment</desc>
* <term>EcAlarmReceiverFailure</term>
* <desc>Category: Equipment</desc>
* <term>EcAlarmRemoteNodeTransmissionError</term>
* <desc>Category: Communications</desc>
* <term>EcAlarmResourceAtOrNearingCapacity</term>
* <desc>Category: QoS</desc>
* <term>EcAlarmResponseTimeExcessive</term>
* <desc>Category: QoS</desc>
* <term>EcAlarmRetransmissionRateExcessive</term>
* <desc>Category: QoS</desc>
* <term>EcAlarmSoftwareProgramAbnormallyTerminated</term>
* <desc>Category: Processing</desc>
* <term>EcAlarmSoftwareProgramError</term>
* <desc>Category: Processing</desc>
* <term>EcAlarmStorageCapacityProblem</term>
* <desc>Category: Processing</desc>
* <term>EcAlarmTemperatureUnacceptable</term>
* <desc>Category: Environmental</desc>
* <term>EcAlarmThresholdCrossed</term>
* <desc>Category: QoS</desc>
* <term>EcAlarmTimingProblem</term>
* <desc>Category: Equipment</desc>
* <term>EcAlarmToxicLeakDetected</term>
* <desc>Category: Environmental</desc>
* <term>EcAlarmTransmitFailure</term>
* <desc>Category: Equipment</desc>
* <term>EcAlarmTransmitterFailure</term>
* <desc>Category: Equipment</desc>
* <term>EcAlarmUnderlyingResourceUnavailable</term>
* <desc>Category: Processing</desc>
* <term>EcAlarmVersionMismatch</term>
* <desc>Category: Processing</desc>
* </deflist>
*/
typedef enum {
EcAlarmProbableCauseUnknown = 0, // Any
EcAlarmAdapterError = 1, // Equipment
EcAlarmApplicationSubsystemFailure = 2, // Processing
EcAlarmBandwidthReduced = 3, // QoS
EcAlarmCallEstablishmentError = 4, // Communications
EcAlarmCommunicationsProtocolError = 5, // Communications
EcAlarmCommunicationsSubsystemFailure = 6, // Communications
EcAlarmConfigurationOrCustomizationError = 7, // Processing
EcAlarmCongestion = 8, // QoS
EcAlarmCorruptData = 9, // Processing
EcAlarmCpuCyclesLimitExceeded = 10, // Processing
EcAlarmDataSetOrModemError = 11, // Equipment
EcAlarmDegradedSignal = 12, // Communications
EcAlarmDTE_DCEInterfaceError = 13, // Communications
EcAlarmEnclosureDoorOpen = 14, // Environmental
EcAlarmEquipmentMalfunction = 15, // Equipment
EcAlarmExcessiveVibration = 16, // Environmental
EcAlarmFileError = 17, // Processing
EcAlarmFireDetected = 18, // Environmental
EcAlarmFloodDetected = 19, // Environmental
EcAlarmFramingError = 20, // Communications
EcAlarmHeatingOrVentilationOrCoolingSystemProblem = 21, // Environmental
EcAlarmHumidityUnacceptable = 22, // Environmental
EcAlarmInputOutputDeviceError = 23, // Equipment
EcAlarmInputDeviceError = 24, // Equipment
EcAlarmLANError = 25, // Communications
EcAlarmLeakDetected = 26, // Environmental
EcAlarmLocalNodeTransmissionError = 27, // Communications
EcAlarmLossOfFrame = 28, // Communications
EcAlarmLossOfSignal = 29, // Communications
EcAlarmMaterialSupplyExhausted = 30, // Environmental
EcAlarmMultiplexerProblem = 31, // Equipment
EcAlarmOutOfMemory = 32, // Processing
EcAlarmOutputDeviceError = 33, // Equipment
EcAlarmPerformanceDegraded = 34, // QoS
EcAlarmPowerProblem = 35, // Equipment
EcAlarmPressureUnacceptable = 36, // Environmental
EcAlarmProcessorProblem = 37, // Equipment
EcAlarmPumpFailure = 38, // Environmental
EcAlarmQueueSizeExceeded = 39, // QoS
EcAlarmReceiveFailure = 40, // Equipment
EcAlarmReceiverFailure = 41, // Equipment
EcAlarmRemoteNodeTransmissionError = 42, // Communications
EcAlarmResourceAtOrNearingCapacity = 43, // QoS
EcAlarmResponseTimeExcessive = 44, // QoS
EcAlarmRetransmissionRateExcessive = 45, // QoS
EcAlarmSoftwareProgramAbnormallyTerminated = 47, // Processing
EcAlarmSoftwareProgramError = 48, // Processing
EcAlarmStorageCapacityProblem = 49, // Processing
EcAlarmTemperatureUnacceptable = 50, // Environmental
EcAlarmThresholdCrossed = 51, // QoS
EcAlarmTimingProblem = 52, // Equipment
EcAlarmToxicLeakDetected = 53, // Environmental
EcAlarmTransmitFailure = 54, // Equipment
EcAlarmTransmitterFailure = 55, // Equipment
EcAlarmUnderlyingResourceUnavailable = 56, // Processing
EcAlarmVersionMismatch = 57, // Processing
} EcAlarmProbableCause;
/** The EcAlarmSeverity enumeration defines the 'perceived severities' of
* alarms produced by the system.<br />
* The enumerated values MUST be matched by those in your SNMP MIB if
* you wish to have your software interact with SNMP tools.<br />
* NB. The use of EcAlarmSeverityIndeterminate should be avoided.
* <deflist>
* <term>EcAlarmSeverityIndeterminate</term><desc>Do not use</desc>
* <term>EcAlarmSeverityCritical</term>
* <desc>Immediate intervention required to restore service</desc>
* <term>EcAlarmSeverityMajor</term>
* <desc>Severe but partial system failure or a problem which
* might recover without intervention</desc>
* <term>EcAlarmSeverityMinor</term>
* <desc>A failure, but one which is likely to recover or which is
* probably not urgent</desc>
* <term>EcAlarmSeverityWarning</term>
* <desc>An unusual event which may not indicate any problem, but
* which ought to be looked into</desc>
* <term>EcAlarmSeverityCleared</term>
* <desc>This indicates the resolution of an earlier issue</desc>
* </deflist>
*/
typedef enum {
EcAlarmSeverityIndeterminate = 0,
EcAlarmSeverityCritical = 1,
EcAlarmSeverityMajor = 2,
EcAlarmSeverityMinor = 3,
EcAlarmSeverityWarning = 4,
EcAlarmSeverityCleared = 5
} EcAlarmSeverity;
/** The EcAlarmTrend enumeration defines the severity trend of alarms
* produced by the system.<br />
* The enumerated values MUST be matched by those in your SNMP MIB if
* you wish to have your software interact with SNMP tools.<br />
* <deflist>
* <term>EcAlarmTrendNone</term>
* <desc>This is not a change in severity of an earlier alarm</desc>
* <term>EcAlarmTrendUp</term>
* <desc>This is a more severe version of an earlier alarm</desc>
* <term>EcAlarmTrendDown</term>
* <desc>This is a less severe version of an earlier alarm</desc>
* </deflist>
*/
typedef enum {
EcAlarmTrendNone = 0,
EcAlarmTrendUp = '+',
EcAlarmTrendDown = '-',
} EcAlarmTrend;
/** This function builds a managed object name from host, process,
* and component.<br />
* The host part may be nil ... for the current host.<br />
* The process part may be nil ... for the current process.<br />
* The component may well be nil if the alert applies to the process as
* a whole rather than to a particular component. This field is typically
* used to identify a particular network connection etc within a process.<br />
* This parses the process and separates out any instance ID (trailing
* hyphen and string of digits). It then builds the managed object from
* four parts (host, process, instance, component) separated by underscores.
* Any underscores in the arguments are replaced by hyphens.<br />
* NB. The total length must not exceed 127 ASCII characters.
*/
NSString *
EcMakeManagedObject(NSString *host, NSString *process, NSString *component);
/** <p>The EcAlarm class encapsulates an alarm to be sent out to a monitoring
* system. It's designed to work cleanly with industry standard SNMP
* alarm monitoring systems. For more information on how the SNMP
* operation works, see the [EcAlarmSinkSNMP] class documentation.
* </p>
* <p>Instances are created and sent to a central coordination point
* where checks are performed to see if there is an existing alarm for
* the same issue. If the incoming alarm does not change the severity
* of an existing alarm, it is ignored, otherwise it may be passed on to
* an external monitoring system. The central coordination system is
* responsible for ensuring that alarms for the same issue are updated
* to contain the first event date, notification ID and a trend indicator.
* </p>
* <p>Alarms which have been raised (by passing them to an alarm destination)
* remain raised until they are cleared (by passign a matching alarm with
* a cleared severity status) to the destination. Alarm clears sent with
* no earlier matching raise are generally ignored, but a clear may be
* flagged as a special audit alarm: one which is passed on and logged
* for audit porposes. This is a rare situation where the alarm does not
* actually represent a problem (or even the suspicion of a problem).
* </p>
*/
@interface EcAlarm : NSObject <NSCoding,NSCopying>
{
NSString *_managedObject;
NSDate *_eventDate;
NSDate *_firstEventDate;
EcAlarmEventType _eventType;
EcAlarmSeverity _perceivedSeverity;
EcAlarmProbableCause _probableCause;
NSString *_specificProblem;
NSString *_proposedRepairAction;
NSString *_additionalText;
EcAlarmTrend _trendIndicator;
int _notificationID;
NSDictionary *_userInfo;
void *_extra;
BOOL _frozen;
uint8_t _delay;
BOOL _audit;
}
/** Creates and returns an autoreleased instance by calling the
* designated initialiser with all the supplied arguments.
*/
+ (EcAlarm*) alarmForManagedObject: (NSString*)managedObject
at: (NSDate*)eventDate
withEventType: (EcAlarmEventType)eventType
probableCause: (EcAlarmProbableCause)probableCause
specificProblem: (NSString*)specificProblem
perceivedSeverity: (EcAlarmSeverity)perceivedSeverity
proposedRepairAction: (NSString*)proposedRepairAction
additionalText: (NSString*)additionalText;
/** This method provides a mapping from the probable cause of an event to
* the event type.<br />
* The method is called during initialisation of an alarm instance (except
* where the probable cause is EcAlarmProbableCauseUnknown) to check that the
* supplied arguments are consistent. If a subclass extends the possible
* probable cause values, it must also override this method to handle those
* new values by returning a known event type.
*/
+ (EcAlarmEventType) eventTypeFromProbableCause: (EcAlarmProbableCause)value;
/** Provides a human readable string representation of an event type.<br />
* This method is called during initialisation of an alarm instance to check
* that the supplied event type is legal.<br />
* Returns nil if the value is unknown.<br />
*/
+ (NSString*) stringFromEventType: (EcAlarmEventType)value;
/** Provides a human readable string representation of a probable cause.<br />
* Returns nil if the value is unknown.
*/
+ (NSString*) stringFromProbableCause: (EcAlarmProbableCause)value;
/** Provides a human readable string representation of a severity.<br />
* Returns nil if the value is unknown.
*/
+ (NSString*) stringFromSeverity: (EcAlarmSeverity)value;
/** Provides a human readable string representation of a trend.<br />
* Returns nil if the value is unknown.
*/
+ (NSString*) stringFromTrend: (EcAlarmTrend)value;
/** This is the supplementary text (optional) which may be provided with
* and alarm an an aid to the human operator for the monitoring system.
*/
- (NSString*) additionalText;
/** Returns YES if this alarm is flagged as an audit object: a clear which
* should be recorded/monitored even without a matching raise of the alarm.
*/
- (BOOL) audit;
/** Compares the other object with the receiver for sorting/ordering.<br />
* If both objects have a notificationID set then the result of the
* numeric comparison of those IDs is used.<br />
* Otherwise the result of the comparison orders the objects by
* managedObject, eventType, probableCause, and specificProblem.
*/
- (NSComparisonResult) compare: (EcAlarm*)other;
/** Returns an autoreleased copy of the receiver with the same notificationID
* but with a perceivedSeverity set to be EcAlarmSeverityCleared ... this may
* be used to clear the alarm represented by the receiver.
*/
- (EcAlarm*) clear;
/** EcAlarm objects may be copied. This method is provided to implement
* the NSCopying protocol.<br />
* A copy of an object does <em>not</em> copy any value provided by the
* -setExtra: method.<br />
* A copy of an object is not frozen.
*/
- (id) copyWithZone: (NSZone*)aZone;
/** Deallocates the receiver.
*/
- (void) dealloc;
/** Returns the queue delay set for this alarm (or zero if none was set).
*/
- (uint8_t) delay;
/** Returns YES if the receiver should be delayed in the queue past the
* supplied timestamp, NO otherwise.
*/
- (BOOL) delayed: (NSTimeInterval)at;
/** EcAlarm objects may be passed over the distributed objects system or
* archived. This method is provided to implement the NSCoding protocol.<br />
* An encoded copy of an object does <em>not</em> copy any value provided
* by the -setExtra: method.
*/
- (void) encodeWithCoder: (NSCoder*)aCoder;
/** Returns the timestamp of the event which generated the alarm.
*/
- (NSDate*) eventDate;
/** This method returns the type for event which generated the alarm.
*/
- (EcAlarmEventType) eventType;
/** Returns any extra information stored by the -setExtra: method.<br />
*/
- (void*) extra;
/** If this alarm is known to be represent an event updating the status of
* an existing alarm, this method returns the date of the initial event.
* otherwise it returns nil.
*/
- (NSDate*) firstEventDate;
/** Freeze the state of the receiver;
* no more calls to setters are permitted.<br />
* When a frozen alarm is copied, the new copy is <em>not</em> frozen.
*/
- (void) freeze;
/** Returns the hash of the receiver ... which is also the hash of its
* managedObject.
*/
- (NSUInteger) hash;
/** <init/>
* Initialises the receiver as an alarm for a particular event.<br />
* The managedObject argument may be nil if the alarm should use the
* default managed object value for the current process.<br />
* The eventDate argument may be nil if the alarm should use the current
* timestamp.<br />
* The managedObject, eventType, probableCause, and specificProblem
* arguments uniquely identify the issue for which an alarm is being
* produced.<br />
* The perceivedSeverity indicates the importance of the problem, with a
* value of EcAlarmSeverityCleared indicating that the problem is over.<br />
* A proposedRepairAction is mandatory (unless the severity is cleared)
* to provide the human operator with some sort of hint about how they
* should resolve the issue.
*/
- (id) initForManagedObject: (NSString*)managedObject
at: (NSDate*)eventDate
withEventType: (EcAlarmEventType)eventType
probableCause: (EcAlarmProbableCause)probableCause
specificProblem: (NSString*)specificProblem
perceivedSeverity: (EcAlarmSeverity)perceivedSeverity
proposedRepairAction: (NSString*)proposedRepairAction
additionalText: (NSString*)additionalText;
/** EcAlarm objects may be passed over the distributed objects system or
* archived. This method is provided to implement the NSCoding protocol.
*/
- (id) initWithCoder: (NSCoder*)aCoder;
/** Returns a flag indicating whether the receiver is equal to the other
* object. To be considered equal either:<br />
* The two objects must have equal managedObject values and equal (non-zero)
* notificationID values or<br />
* the two objects must have equal managedObject values,
* equal eventType values, equal probableCause values,
* and equal specificProblem values.<br />
* NB. you must not set two alarm instances to have the same notificationID
* values if they are not considered equal using the other criteria.
*/
- (BOOL) isEqual: (id)other;
/** Returns the managedObject value set when the receiver was initialised.
*/
- (NSString*) managedObject;
/** Returns the component of the managed object (if any).
*/
- (NSString*) moComponent;
/** Returns the host of the managed object.
*/
- (NSString*) moHost;
/** Returns the instance of the managed object (if any).
*/
- (NSString*) moInstance;
/** Returns the process name of the managed object including the instance
* separated from the main name by a hyphen. If the managed object has no
* process instance, this method simply returns the process name.
*/
- (NSString*) moInstancedProcess;
/** Returns the process name of the managed object.
*/
- (NSString*) moProcess;
/** Returns zero or the notificationID value most recently set by
* the -setNotificationID: method.
*/
- (int) notificationID;
/** Returns the perceivedSeverity set when the receiver was initialised.
*/
- (EcAlarmSeverity) perceivedSeverity;
/** Returns the proposedRepairAction set when the receiver was initialised.
*/
- (NSString*) proposedRepairAction;
/** Returns the probableCause set when the receiver was initialised.
*/
- (EcAlarmProbableCause) probableCause;
/** Specified if this alarm is to be flagged as an audit object: a clear which
* should be recorded/monitored even without a matching raise of the alarm.
*/
- (void) setAudit: (BOOL)flag;
/** Sets the number of seconds for which this alarm should be delayed in the
* queue to allow coalescing with other matching alarms. This defaults to
* zero so that there is no special delay in processing beyond that imposed
* by periodic queue flushing.
*/
- (void) setDelay: (uint8_t)delay;
/** Sets extra data for the current instance.<br />
* Extra data is not copied, archived, or transferred over DO, it is available
* only in the exact instance of the class in which it was set.
*/
- (void) setExtra: (void*)extra;
/** Sets the first event date for the receiver.<br />
* You should not normally call this as it is reserved for use by code
* which has matched the receiver to an existing alarm.
*/
- (void) setFirstEventDate: (NSDate*)firstEventDate;
/** Sets the notification ID for the receiver.<br />
* You should not normally call this as it is reserved for use by code
* which has matched the receiver to an existing alarm.<br />
* In particular, two instances should not be set to have the same non-zero
* notificationID unless they are equal according to other criteria of
* equality (ie have the same managedObject, eventType, probableCause,
* and specificProblem values).
*/
- (void) setNotificationID: (int)notificationID;
/** Sets the trend indicator for the receiver.<br />
* You should not normally call this as it is reserved for use by code
* which has matched the receiver to an existing alarm.
*/
- (void) setTrendIndicator: (EcAlarmTrend)trendIndicator;
/** Sets the user information associated with this alarm (a dictionary).<br />
* This user information is additional data associated with the alarm
* which is copied when the alarm is copied. This data is not used by
* the CCITT X.733 ... it's optional additional data.<br />
* Conventional keys are:<br />
* <deflist>
* <term>ResponsibleEmail</term>
* <desc>The Email address of the person/entity with primary responsibility
* for dealing with an alarm ... this is intended for use by the alerting
* system (EcAlerter) when deciding where to send email alerts.
* </desc>
* </deflist>
*/
- (void) setUserInfo: (NSDictionary*)userInfo;
/** Returns the specificProblem set when the receiver was initialised.
*/
- (NSString*) specificProblem;
/** Returns the value most recently set by the -setTrendIndicator: method
* (or EcAlarmTrendNone if that method has not been called).<br />
* This tells you whether the receiver represents an increase in severity
* of an issue, or a decrease in severity (or no change).
*/
- (EcAlarmTrend) trendIndicator;
/** Returns any previously set information (see -setUserInfo:) or nil
* if none has been set.
*/
- (NSDictionary*) userInfo;
@end
@interface EcAlarm (Convenience)
/** Generates an alarm to clears an alarm previously generated.<br />
* The componentName may be nil for a process-wide alarm.<br />
* The probableCause must NOT be unknown ... it is used to infer
* the event type.<br />
* The specificProblem must be identical to the value supplied in the
* original alarm that this is intended to clear.
*/
+ (EcAlarm*) clear: (NSString*)componentName
cause: (EcAlarmProbableCause)probableCause
problem: (NSString*)specificProblem;
/** Generates a new alarm event with minimal parameters.<br />
* The componentName may be nil for a process-wide alarm.<br />
* The probableCause must NOT be unknown ... it is used to infer
* the event type.<br />
* The specificProblem is used to identify the event for which the
* alarm is raised.<br />
* The perceivedSeverity must be one of EcAlarmSeverityWarning,
* EcAlarmSeverityMinor, EcAlarmSeverityMajor or EcAlarmSeverityCritical.<br />
* The proposedRepairAction must contain information sufficient
* for any person receiving notification of the alarm to be able
* to deal with it. The action is a format string, optionally
* followed by any number of arguments to be incorporated into
* the repair action. NB. The resulting proposed repair action
* must be no more than 255 bytes in length when converted to
* UTF-8 data.
*/
+ (EcAlarm*) raise: (NSString*)componentName
cause: (EcAlarmProbableCause)probableCause
problem: (NSString*)specificProblem
severity: (EcAlarmSeverity)perceivedSeverity
action: (NSString*)proposedRepairAction, ...;
@end
#endif
Reference in a new issue View git blame Copy permalink