RegisterEvent()
===============

FUNKTION
--------
::

     int RegisterEvent(string eid, string fun, object listener);

DEFINIERT IN
------------
::

     /p/daemon/eventd.c

DEKLARIERT IN
-------------
::

     /sys/events.h

ARGUMENTE
---------
::

     string eid,
       Die ID des Events, fuer den man sich registrieren will. Da dieser
       String fuer alle Events jeweils eindeutig sein muss, empfiehlt es sich,
       fuer eigene Events z.B. als Praefix den eigenen Magiernamen zu nehmen,
       z.B. "zesstra_vulkanausbruch".
       ACHTUNG: IDs, die mit '_evt_lib_' beginnen, sind AUSSCHLIESSLICH der
       Mudlib vorbehalten!
     string fun,
       Name der Funktion, die im Objekt listener bei Auftreten des Events
       gerufen werden soll.
     object listener,
       Das Objekt, das als Lauscher fuer diesen Event registriert werden soll.

BESCHREIBUNG
------------
::

     Das Objekt 'listener' wird als Lauscher dieses Events registriert. Ab
     diesem Moment wird immer dann, wenn ein Event mit der ID 'eid' ausgeloest
     wird, in 'listener' die Funktion 'fun' aufgerufen (zeitverzoegert, meist
     0-2s).

     

     Die Funktion wird dabei immer mit 3 Argumenten aufgerufen:
     listener->fun(eid, triggerob, data);
     Hierbei ist 'eid' die jeweilige Event-ID und 'triggerob' ist das Objekt,
     welches den Event ausloeste. 
     'data' kann jeder LPC-Datentyp sein und enthaelt die Daten, die das
     triggernde Objekt an alle Listener uebermitteln will (damit sind Datentyp
     und Inhalt komplett abhaengig vom Event!)

     Existiert bisher noch kein Event mit der ID 'eid', wird implizit ein
     neuer Event erstellt, der erstmal nur das sich gerade registrierende
     Objekt als Lauscher hat.

RUeCKGABEWERT
-------------
::

     1 fuer Erfolg, <=0 fuer Misserfolg.
     1   - Erfolg, 'listener' wurde eingetragen.
     -1  - falsche Argumente wurden uebergeben
     -2  - nicht-oeffentlicher Event und 'listener' wurde nicht fuer diesen
           Event freigegeben (momentan gibt es noch keine nicht-oeffentlichen
           Events)
     -3  - 'fun' in 'listener' ist nicht vorhanden oder nicht von aussen 
           aufrufbar (protected, static, private).

     

BEMERKUNGEN
-----------
::

     Wenn 'listener' bereits fuer den Event registriert wird, wird die alte
     Registrierung ueberschrieben (als ggf. gilt dann der jetzt uebergebene
     Funktionsname).
     Die Funktion 'fun' sollte sparsam mit den Eval-Ticks umgehen. Momentan
     ist die max. Menge an Ticks auf 30000 beschraenkt. Dies kann bei
     Problemen auch jederzeit reduziert werden!
     Der EVENTD merkt sich Event-Lauscher nicht ueber Reboots hinaus.
     Sollte sich eine Blueprint anmelden, sich zerstoeren und neugeladen
     werden, ist die neue Blueprint noch angemeldet, weil das neue Objekt
     unter dem alten Namen wiedergefunden wird. Dies gilt _nicht_ fuer
     Clones!

BEISPIELE
---------
::

     1. Ein Objekt moechte ueber Spielertode informiert werden:
          EVENTD->RegisterEvent(EVT_LIB_PLAYER_DEATH, "spieler_ist_tot", 
                                this_object());
        Ab jetzt wird im Objekt jedes Mal, wenn ein Spieler stirbt, die 
        Funktion "spieler_ist_tot" aufgerufen.

     2. Ein Objekt will informiert werden, wenn der Event
        "boing_zwergenkoenig_angriff" ausgeloest wird:
           EVENTD->RegisterEvent("boing_zwergenkoenig_angriff","alarm",
                                  this_object());

SIEHE AUCH
----------
::

     events, eventd, UnregisterEvent(), TriggerEvent()


Last modified: 15.08.2007, Zesstra