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

  <refnamediv>
    <refname>SandUhr::AlarmAction</refname>
    <refname>SandUhr::AlarmBeep</refname>
    <refname>SandUhr::AlarmSound</refname>
    <refname>SandUhr::AlarmCommand</refname>
    <refpurpose>CORBA-Schnittstelle für die SandUhr-Alarmmethoden</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <title>ÜBERSICHT</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>BESCHREIBUNG</title>

    <para>
      Die Alarmmethoden von &sanduhr; werden durch Klassen
      beschrieben, die von <classname>SandUhr::AlarmAction</classname>
      abgeleitet sind.  Drei solcher Klassen sind vordefiniert und
      werden direkt von &sanduhr; implementiert.
    </para>

    <para>
      Alle Alarmmethoden verwenden die folgenden Attribute und
      Funktionen.
    </para>

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

        <para>
	  Falls dieses Attribut den Wert <literal>TRUE</literal> hat,
	  wird die Alarmmeldung nicht nur durch Aufruf der
	  <function>Deliver()</function>-Funktion zugestellt, sondern
	  &sanduhr; öffnet zusätzlich noch ein Popup-Fenster.
        </para>
      </listitem>

      <listitem>
        <para>Anschließen von Alarmmechanismen:</para>
        <synopsis>
void Attach (in Timer T);
        </synopsis>

        <para>
	  Diese Methode wird von dem Timer-Objekt aufgerufen, bevor es
	  auf das <classname>AlarmAction</classname>-Objekt auf
	  irgendeine andere Weise zugreift.  Die Funktion kann
	  z.B. verwendet werden, um ein <quote lang="en">reference
	  counting</quote> zu implementieren.
        </para>
      </listitem>

      <listitem>
        <para>Abtrennen von Alarmmechanismen:</para>
        <synopsis>
void Detach (in Timer T);
        </synopsis>

        <para>
	  Diese Methode wird von dem Timer-Objekt aufgerufen, wenn es
	  an dem <classname>AlarmAction</classname>-Objekt nicht
	  länger interessiert ist.  Die Funktion kann z.B. verwendet
	  werden, um ein <quote lang="en">reference counting</quote>
	  zu implementieren.
        </para>
      </listitem>

      <listitem>
        <para>Zustellung des Alarms:</para>
        <synopsis>
void Deliver (in string TimeSpec, in string Message)
                                        raises (DeliveryFailed);
        </synopsis>

        <para>
	  Diese Methode wird von dem Timer-Objekt aufgerufen, wenn die
	  Uhr abgelaufen ist.  Sie ist dafür verantwortlich, dem
	  Benutzer die Meldung zuzustellen.  Falls das misslingt, muss
	  die <literal>Deliver</literal>-Funktionen eine
	  <literal>DeliveryFailed</literal>-Ausnahme auslösen.  Das
	  Argument <literal>TimeSpec</literal> enthält eine
	  normalisierte Form der Alarmzeit, nicht die ursprüngliche
	  Beschreibung des Benutzers.
        </para>
      </listitem>
    </itemizedlist>

    <para>
      &sanduhr; selbst implentiert drei spezielle Subklassen von
      <classname>AlarmAction</classname>:
    </para>

    <itemizedlist>
      <listitem>
        <para>Tastaturpieps:</para>
        <synopsis>
interface AlarmBeep: AlarmAction {
  attribute unsigned short Count;
};
        </synopsis>

        <para>
	  Piepse mehrfach.  <literal>Count</literal> ist die Anzahl
          der Piepstöne.  Der Wert wird während der Zustellung der
          Alarms heruntergezählt, bis er Null erreicht.
        </para>
      </listitem>

      <listitem>
        <para>Abspielen einer Sounddatei:</para>
        <synopsis>
interface AlarmSound: AlarmAction {
  attribute string SoundFile;
};
        </synopsis>

        <para>
	  Spiele eine Sounddatei mittels des <quote>enlightened sound
          daemon</quote> <command>esd</command> ab.  Der Dateiname
          <literal>SoundFile</literal> bezeichnet eine Datei auf dem
          Rechner, auf dem das
          <classname>AlarmSound</classname>-Objekt lebt.
        </para>
      </listitem>

      <listitem>
        <para>Ausführen eines Programms:</para>
        <synopsis>
interface AlarmCommand: AlarmAction {
  attribute string CommandString;
};
        </synopsis>

        <para>
	  Führe ein beliebiges Shell-Kommando aus.  Das Kommando
	  <literal>CommandString</literal> wird mittels der Funktion
	  <function>gnome_execute_shell()</function> auf dem Rechner
	  ausgeführt, auf dem das
	  <classname>AlarmCommand</classname>-Objekt lebt.
        </para>
      </listitem>

    </itemizedlist>
  </refsect1>

  <refsect1>
    <title>SIEHE AUCH</title>

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

</refentry>
