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