1 .** vim: sw=4 ts=4 et :
3 ==================================================================================
4 Copyright (c) 2020 Nokia
5 Copyright (c) 2020 AT&T Intellectual Property.
7 Licensed under the Apache License, Version 2.0 (the "License");
8 you may not use this file except in compliance with the License.
9 You may obtain a copy of the License at
11 http://www.apache.org/licenses/LICENSE-2.0
13 Unless required by applicable law or agreed to in writing, software
14 distributed under the License is distributed on an "AS IS" BASIS,
15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 See the License for the specific language governing permissions and
17 limitations under the License.
18 ==================================================================================
23 This imbed file contains the portion of the document that describes the
24 alarm collector AIP provided by the framework.
29 .** work round bug in cmd_ps.im
36 .** ------ positioning -------------------------------------
38 &h1(Alarm Manager Interface)
39 The C++ framework provides an API which allows the xAPP to easily construct and
40 generate alarm messages.
41 Alarm messages are a special class of RMR message, allocated in a similar fashion
42 as an RMR message through the framework's &cw(Alloc_alarm()) function.
45 The API consists of the following function types:
49 &beg_dlist( 1i &ditemtext: )
50 &di(Raise) Cause the alarm to be assigned a severity and and sent via RMR
51 message to the alarm collector process.
54 &di(Clear) Cause a clear message to be sent to the alarm collector.
57 &di(Raise Again) Cause a clear followed by a raise message to be sent to
63 &h2(Allocating Alarms)
64 The &cw(xapp::Alloc_alarm()) function provided by the framework is used to create
66 Once the xAPP has an alarm object it can be used to send one, or more, alarm
67 messages to the collector.
70 The allocation function has three prototypes which allow the xAPP to create
71 an alarm with an initial set of information as is appropriate.
72 The following are the prototypes for the allocate functions:
78 Each of the allocation functions returns a unique pointer to the alarm.
79 In the simplest form (1) the alarm is initialised with an empty meid
80 (managed element ID) string, and unset problem ID (-1).
81 The second prototype allows the xAPP to supply the meid, and in the
82 third form both the problem ID and the meid are used to initialise the
86 Once an alarm has been allocated, its &cw(Raise()) function can be used
87 to cause the alarm to be sent to the collector.
88 The raise process allows the xAPP to perform the following modifications
89 to the alarm before sending the message:
94 &li Set the alarm severity
96 &li Set the problem ID value
98 &li Set the alarm information string
100 &li Set the additional information string
105 The following are the prototypes for the &cw(Raise()) functions of an alarm object:
110 In its simplest form (1) the &cw(Raise()) function will send the alarm without making any
112 The final two forms allow the xAPP to supply additional data which is added to the
113 alarm before sending the message.
115 Each of the raise functions returns &cw(true) on success and &cw(false) if the alarm
116 message could not be sent.
119 The severity is one of the &cw(SEV_) constants listed below.
120 These map to alarm collector strings and insulate the xAPP from any future alarm collector
122 The specific meaning of these severity types are defined by the alarm collector and thus
123 no attempt is made to guess what their actual meaning is.
124 These constants are available by including &cw(alarm.hpp.)
135 &fig_cen(Severity constants available in alarm.hpp.)
138 The problem ID is an integer which is assigned by the xAPP.
139 The framework makes no attempt to verify that it has been se, nor does it attempt
140 to validate the value.
141 If the xAPP does not set the value, &cw(-1) is used.
143 &h3(Information Strings)
144 The two information strings are also xAPP defined and provide the information that
145 the xAPP deems necessary and related to the alarm.
146 What the collector expects, and how these strings are used, is beyond the scope of
147 the framework to describe or validate.
148 If not supplied, empty strings are sent in the alarm message.
150 &h2(Clearing An Alarm)
151 The &cw(Clear()) function of an alarm may be used to send a clear message.
152 In a manner similar to the &cw(Raise()) functions, the &cw(Clear()) functions allow
153 the existing alarm data to be sent without change, or for the xAPP to modify the
154 data before the message is sent to the collector.
155 The following are the prototype for these functions.
160 bool Clear( int severity, int problem, std::string info );
161 bool Clear( int severity, int problem, std::string info, std::string addional_info );
165 &fig_cen(Clear function prototypes. )
168 Each of the clear functions returns &cw(true) on success and &cw(false) if the alarm
169 message could not be sent.
173 The &cw(Clear_all()) function sends a special action code to the collector which is assumed
175 However, it is unknown whether that implies &bold(all) alarms, or all alarms matching the
176 &cw(problem_id,) or some other interpretation.
177 Please consult the alarm collector documentation for these specifics.
180 &h2(Adjusting Alarm Contents)
181 It might be necessary for the xAPP to adjust the alarm contents outside of the scope of
182 the &cw(Raise()) function, or to adjust data that cannot be manipulated by &cw(Raise().)
183 The following are the (self explanatory) prototypes for the &ital(setter) functions
184 which are available to the xAPP.
188 void Set_additional( std::string new_info );
189 void Set_appid( std::string new_id );
190 void Set_info( std::string new_info );
191 void Set_meid( std::string new_meid );
192 void Set_problem( int new_id );
193 void Set_severity( int new_sev );
195 &fig_cen(Alarm Setters)