<refentry id="alarmref">
  <refmeta>
    <refentrytitle>SandUhr::AlarmAction</refentrytitle>
    <manvolnum>3</manvolnum>
    <refmiscinfo>SandUhr CORBA interface</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname>SandUhr::AlarmAction</refname>
    <refname>SandUhr::AlarmBeep</refname>
    <refname>SandUhr::AlarmSound</refname>
    <refname>SandUhr::AlarmCommand</refname>
    <refpurpose>CORBA interface for the SandUhr alarm actions</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <title>SYNOPSIS</title>
    <synopsis>
module SandUhr {
  interface AlarmAction {
    exception DeliveryFailed {
      string Reason;
    };

    readonly attribute boolean NeedsPopup;

    void Attach (in Timer T);
    void Detach (in Timer T);
    void Deliver (in string TimeSpec, in string Message)
                                        raises (DeliveryFailed);
    };

  interface AlarmBeep: AlarmAction {
    attribute unsigned short Count;
  };

  interface AlarmSound: AlarmAction {
    attribute string SoundFile;
  };

  interface AlarmCommand: AlarmAction {
    attribute string CommandString;
  };
};
    </synopsis></refsynopsisdiv>

  <refsect1>
    <title>DESCRIPTION</title>

    <para>
      The alarm action is described by Objects derived from
      <classname>SandUhr::AlarmAction</classname>.  There are
      three predefined subclasses, which are implemented by
      &sanduhr;.
    </para>

    <para>
      Every alarm action uses the following attributes and methods.
    </para>

    <itemizedlist>
      <listitem>
        <para>Popup windows:</para>
        <synopsis>
readonly attribute boolean NeedsPopup;
        </synopsis>

        <para>
          If this is <literal>TRUE</literal>, the timer will
          display the alarm message in a popup window in addition
          to the <function>Deliver()</function>
          call.
        </para>
      </listitem>

      <listitem>
        <para>Attaching timers to AlarmActions:</para>
        <synopsis>
void Attach (in Timer T);
        </synopsis>

        <para>
          This is called by a timer object, before it accesses the
          <classname>AlarmAction</classname> object in any other
          way.  It may be used to implement reference counting for
          alarm actions.
        </para>
      </listitem>

      <listitem>
        <para>Detaching timers from AlarmActions:</para>
        <synopsis>
void Detach (in Timer T);
        </synopsis>

        <para>
          This is called by the timer object when the timer is no
          longer interested in this
          <classname>AlarmAction</classname>.  This occurs after
          the <function>Deliver()</function> call or after the
          <classname>AlarmAction</classname> is replaced with
          another one.  This method may be used to implement
          reference counting for alarm actions.
        </para>
      </listitem>

      <listitem>
        <para>Delivering the alarm:</para>
        <synopsis>
void Deliver (in string TimeSpec, in string Message)
                                        raises (DeliveryFailed);
        </synopsis>

        <para>
          This method is called by the timer to actually deliver
          the alarm.  The function is responsible for delivering
          the alarm to the user.  If the delivery fails it must
          raise the <literal>DeliveryFailed</literal> exception.
          Note that the <literal>TimeSpec</literal> contains a
          normalized form of the alarm time, not the originial
          time specification.
        </para>
      </listitem>
    </itemizedlist>

    <para>
      &sanduhr; itself implements three special purpose subclasses
      of <classname>AlarmAction</classname>:
    </para>

    <itemizedlist>
      <listitem>
        <para>Ring the terminal bell:</para>
        <synopsis>
interface AlarmBeep: AlarmAction {
  attribute unsigned short Count;
};
        </synopsis>

        <para>
          Ring the keybord bell repeatedly.
          <literal>Count</literal> is the number of beeps.  This
          value is decreased while the alarm is delivered until
          the value reaches 0.
        </para>
      </listitem>

      <listitem>
        <para>Play a sound file:</para>
        <synopsis>
interface AlarmSound: AlarmAction {
  attribute string SoundFile;
};
        </synopsis>

        <para>
          Playes a sound file via the enlightened sound daemon
          <command>esd</command>.  The file name
          <literal>SoundFile</literal> must denote a file on the host
          the <classname>AlarmSound</classname> object lives on.
        </para>
      </listitem>

      <listitem>
        <para>Execute a system command:</para>
        <synopsis>
interface AlarmCommand: AlarmAction {
  attribute string CommandString;
};
        </synopsis>

        <para>
          Execute an arbitrary shell command.  This command is
          executed via <function>gnome_execute_shell()</function>
          on the host the <classname>AlarmCommand</classname>
          object lives on.
        </para>
      </listitem>

    </itemizedlist>
  </refsect1>

  <refsect1>
    <title>SEE ALSO</title>

    <para>
      <xref linkend="factoryref">,
      <xref linkend="timerref">
    </para>
  </refsect1>

</refentry>
