
HRegisterToHook()
*****************


FUNKTION
========

   int HRegisterToHook(int hookid, object|closure consumer, int
   hookprio,
      int consumertype, int timeInSeconds)


DEFINIERT IN
============

   /std/hook_provider.c /sys/hook.h


ARGUMENTE
=========

   * hookid: gibt den Hook-Typ an Man kann sich nur fuer Hooktypen
     eintragen, die die Methode HListHooks() angeboten hat.

   * consumer: Objekt oder Closure. Wenn ein Objekt uebergeben wird,
     wird eine Closure auf HookCallback() an diesem Objekt erstellt
     und gespeichert, andernfalls wird die uebergebene Closure
     gespeichert. Diese Closure wird spaeter beim Ausloesen des Hooks
     aufgerufen.

   * hookprio: Gibt die Prioritaet an, mit der der Hook laufen soll.
     Diese Angabe bestimmt die Reihenfolge, in der die Hooks in der
     Liste der Hooks eingetragen werden. Siehe Abschnitt Beschreibung
     fuer Details.

   * consumertype: Gibt an, um welche Art von Consumer es sich
     handelt.

   * timeInSeconds: gibt die Laufzeit des Hooks an. Falls 0
     eingetragen wird, laeuft der Hook ewig.


BESCHREIBUNG
============

   Registriert ein Objekt oder eine Closure als Hook-Konsument.

   Die Callback-Methode wird mit folgenden Argumenten gerufen:

   * object hooksource: das Objekt, in welchem das Ereignis
     ausgeloest wurde

   * int hookid: die ID des Hooks

   * mixed hookdata: die Daten des Hooks (siehe Doku zum jeweiligen
     Hook)

   Fuer hookprio sind folgende Werte vorgesehen (Konstanten aus
   hook.h):

   * H_HOOK_LIBPRIO(x)

   * H_HOOK_GUILDPRIO(x) oder

   * H_HOOK_OTHERPRIO(x).

   x darf 0, 1 oder 2 sein (je niedriger, desto hoeher die
   Prioritaet).

   Fuer consumertype gibt es vier festgelegte Arten, die fuer alle
   Hooks existieren koennen, aber nicht muessen (Konstanten aus
   hook.h):

   * H_LISTENER: Wird nur informiert

   * H_DATA_MODIFICATOR: Kann Daten des Ereignisses aendern

   * H_HOOK_MODIFICATOR: Kann das Ereignis zusaetzlich abbrechen

   * H_HOOK_SURVEYOR: Kann zusaetzlich entscheiden, ob sich Objekte
     registrieren, Daten modifizieren oder Ereignisse abbrechen
     koennen

   Die Methode  *HConsumerTypeIsAllowed* gibt Aufschluss darueber,
   welche Consumer-Typen tatsaechlich freigegeben sind.


RUECKGABEWERTE
==============

   1  : Registrierung erfolgreich

   -1 : Hook unbekannt

   -2 : consumer ist keine closure und es konnte kein Callback auf
      HookCallback im consumer erstellt werden.

   -3 : Consumer ist bereits registriert

   -4 : Consumer-Typ ist nicht erlaubt

   -5 : hookprio ist nicht erlaubt

   -6 : Surveyor hat Registrierung nicht erlaubt

   -7 : zuviele Hooks registriert / kein Hookeintrag frei


SIEHE AUCH
==========

   HUnregisterFromHook(), HookCallback(), HListHooks(),
   HIsHookConsumer()

Letzte Aenderung: 05.10.2022, Bugfix