path: root/lib/sasl/doc/src/alarm_handler.xml

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<erlref>
  <header>
    <copyright>
      <year>1996</year>
      <year>2014</year>
      <holder>Ericsson AB, All Rights Reserved</holder>
    </copyright>
    <legalnotice>
  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at
 
      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.

  The Initial Developer of the Original Code is Ericsson AB.
    </legalnotice>

    <title>alarm_handler</title>
    <prepared>Martin Bj&ouml;rklund</prepared>
    <responsible>Bjarne Dacker</responsible>
    <docno></docno>
    <approved>Bjarne D&auml;cker</approved>
    <checked>Martin Bj&ouml;rklund</checked>
    <date>1996-09-10</date>
    <rev>A</rev>
    <file>alarm_handler.sgml.t1</file>
  </header>
  <module>alarm_handler</module>
  <modulesummary>An Alarm Handling Process</modulesummary>
  <description>
    <p>The alarm handler process is a 
      <seealso marker="stdlib:gen_event"><c>gen_event</c></seealso> 
      event manager process that receives alarms in the system. 
      This process is not intended to be a complete alarm handler. 
      It defines a place to which alarms can be sent. One simple event 
      handler is installed in the alarm handler at startup, but users 
      are encouraged to write and install their own handlers.</p>
    <p>The simple event handler sends all alarms as info reports to
      the error logger, and saves all in a list. This list can be
      passed to a user-defined event handler, which can be installed
      later. The list can grow large if many alarms are generated.
      This is a good reason to install a better user-defined
      handler.</p>
    <p>Functions are provided to set and clear alarms. The alarm
      format is defined by the user. For example, an event handler
      for SNMP can be defined, together with an alarm Management
      Information Base (MIB).</p>
    <p>The alarm handler is part of the <c>SASL</c> application.</p>
    <p>When writing new event handlers for the alarm handler, the
      following events must be handled:</p>
    <taglist>
      <tag><c>{set_alarm, {AlarmId, AlarmDescr}}</c></tag>
      <item>
        <p>This event is generated by
          <c>alarm_handler:set_alarm({AlarmId, AlarmDecsr})</c>.</p>
      </item>
      <tag><c>{clear_alarm, AlarmId}</c></tag>
      <item>
        <p>This event is
          generated by <c>alarm_handler:clear_alarm(AlarmId)</c>.</p>
      </item>
    </taglist>
    <p>The default simple handler is called <c>alarm_handler</c> and
      it can be exchanged by calling 
      <seealso marker="stdlib:gen_event#swap_handler/3"><c>gen_event:swap_handler/3</c></seealso>
      as <c>gen_event:swap_handler(alarm_handler, {alarm_handler, swap},
      {NewHandler, Args})</c>. <c>NewHandler:init({Args, {alarm_handler,
      Alarms}})</c> is called. For more details, see
      <seealso marker="stdlib:gen_event"><c>gen_event(3)</c></seealso>
      in <c>STDLIB</c>.</p>
  </description>

  <funcs>
    <func>
      <name>clear_alarm(AlarmId) -> void()</name>
      <fsummary>Clears the specified alarms.</fsummary>
      <type>
        <v>AlarmId = term()</v>
      </type>
      <desc>
	<p>Sends event <c>clear_alarm</c> to all event handlers.</p>
        <p>When receiving this event, the default simple handler
          clears the latest received alarm with id <c>AlarmId</c>.</p>
      </desc>
    </func>

    <func>
      <name>get_alarms() -> [alarm()]</name>
      <fsummary>Gets all active alarms.</fsummary>
      <desc>
        <p>Returns a list of all active alarms. This function can only
          be used when the simple handler is installed.</p>
      </desc>
    </func>

    <func>
      <name>set_alarm(alarm())</name>
      <fsummary>Sets an alarm with an id.</fsummary>
      <type>
        <v>alarm() = {AlarmId, AlarmDescription}</v>
        <v>AlarmId = term()</v>
        <v>AlarmDescription = term()</v>
      </type>
      <desc>
	<p>Sends event <c>set_alarm</c> to all event handlers.</p>
        <p>When receiving this event, the default simple handler
          stores the alarm. <c>AlarmId</c> identifies the alarm
          and is used when the alarm is cleared.</p>
      </desc>
    </func>
  </funcs>

  <section>
    <title>See Also</title>
    <p><seealso marker="kernel:error_logger"><c>error_logger(3)</c></seealso>,
      <seealso marker="stdlib:gen_event"><c>gen_event(3)</c></seealso></p>
  </section>
</erlref>