Doku fuer Hooks
Hook-Funktionen und weitere Libhooks.
Ausserdem ein paar Typos und Klarstellungen in aelteren Manpages zu
Libhooks.
Change-Id: I27de063d852ccb3971379503ab041682d711be9c
diff --git a/doc/sphinx/lfun/HIsHookConsumer.rst b/doc/sphinx/lfun/HIsHookConsumer.rst
new file mode 100644
index 0000000..5f83efb
--- /dev/null
+++ b/doc/sphinx/lfun/HIsHookConsumer.rst
@@ -0,0 +1,39 @@
+HIsHookConsumer()
+=================
+
+FUNKTION
+--------
+
+ int HIsHookConsumer(int hookid, object|closure consumer)
+
+DEFINIERT IN
+------------
+
+ /std/hook_provider.c
+ /sys/hook.h
+
+ARGUMENTE
+---------
+
+ - hookid: gibt den Hook-Typ an
+ - consumer: Objekt oder Closure. Wenn ein Objekt uebergeben wird, wird
+ eine Closure auf :doc:`HookCallback` an diesem Objekt erstellt.
+
+BESCHREIBUNG
+------------
+
+ Prueft, ob eine Closure als consumer fuer einen bestimmten Hook eingetragen
+ ist.
+
+RUECKGABEWERTE
+--------------
+
+ 1 : Closure ist als consumer registriert
+ 0 : Closure nicht als Konsument gefunden
+
+SIEHE AUCH
+----------
+
+ :doc:`HRegisterToHook`, :doc:`HUnregisterFromHook`, :doc:`HookCallback`
+
+Letzte Aenderung: 08.10.2022, Bugfix
diff --git a/doc/sphinx/lfun/HListHooks.rst b/doc/sphinx/lfun/HListHooks.rst
new file mode 100644
index 0000000..dd7343e
--- /dev/null
+++ b/doc/sphinx/lfun/HListHooks.rst
@@ -0,0 +1,57 @@
+HListHooks()
+============
+
+FUNKTION
+--------
+
+ int* HListHooks()
+
+DEFINIERT IN
+------------
+
+ /std/hook_provider.c
+ /sys/hook.h
+
+ARGUMENTE
+---------
+
+ keine
+
+BESCHREIBUNG
+------------
+
+ Diese Methode liefert eine Liste von Hooktypen, fuer die das Objekt
+ Registrierungen akzeptiert. Standardmaessig bieten die Mudlib-Basis-
+ objekte folgende Hooks an:
+ Spielerobjekte: H_HOOK_MOVE, H_HOOK_DIE, H_HOOK_DEFEND, H_HOOK_ATTACK,
+ H_HOOK_HP, H_HOOK_SP, H_HOOK_ATTACK_MOD, H_HOOK_ALCOHOL
+ H_HOOK_FOOD, H_HOOK_DRINK, H_HOOK_POISON, H_HOOK_CONSUME,
+ H_HOOK_TEAMROWCHANGE ,H_HOOK_INSERT
+ NPCs: H_HOOK_MOVE, H_HOOK_DIE, H_HOOK_DEFEND, H_HOOK_ATTACK,
+ H_HOOK_ATTACK_MOD, H_HOOK_ALCOHOL, H_HOOK_FOOD, H_HOOK_DRINK,
+ H_HOOK_POISON, H_HOOK_CONSUME, H_HOOK_TEAMROWCHANGE
+ Raeume: H_HOOK_EXIT_USE, H_HOOK_INIT
+ Dinge: keine
+
+RUECKGABEWERTE
+--------------
+
+ Integer-Array der angebotenen Hook-IDs
+
+BEISPIEL
+--------
+
+.. code-block:: pike
+
+ // Bietet das Objekt einen Consume-Hook an?
+ if(H_HOOK_CONSUME in ob->HListHooks())
+ {
+ do_something();
+ }
+
+SIEHE AUCH
+----------
+
+ :doc:`HRegisterToHook`, :doc:`HUnregisterFromHook`, :doc:`HIsHookConsumer`
+
+Letzte Aenderung: 06.10.2022, Bugfix
diff --git a/doc/sphinx/lfun/HRegisterToHook.rst b/doc/sphinx/lfun/HRegisterToHook.rst
new file mode 100644
index 0000000..01d9c77
--- /dev/null
+++ b/doc/sphinx/lfun/HRegisterToHook.rst
@@ -0,0 +1,78 @@
+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
+ :doc:`HListHooks` angeboten hat.
+ - consumer: Objekt oder Closure. Wenn ein Objekt uebergeben wird, wird
+ eine Closure auf :doc:`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 :doc:`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
+----------
+
+ :doc:`HUnregisterFromHook`, :doc:`HookCallback`, :doc:`HListHooks`,
+ :doc:`HIsHookConsumer`
+
+Letzte Aenderung: 05.10.2022, Bugfix
diff --git a/doc/sphinx/lfun/HUnregisterFromHook.rst b/doc/sphinx/lfun/HUnregisterFromHook.rst
new file mode 100644
index 0000000..056ef9f
--- /dev/null
+++ b/doc/sphinx/lfun/HUnregisterFromHook.rst
@@ -0,0 +1,41 @@
+HUnregisterFromHook()
+=====================
+
+FUNKTION
+--------
+
+ int HUnregisterFromHook(int hookid, object|closure consumer)
+
+DEFINIERT IN
+------------
+
+ /std/hook_provider.c
+ /sys/hook.h
+
+ARGUMENTE
+---------
+
+ - hookid: gibt den Hook-Typ an
+ - consumer: Objekt oder Closure. Wenn ein Objekt uebergeben wird, wird
+ eine Closure auf :doc:`HookCallback` an diesem Objekt erstellt und
+ versucht diese auszutragen, andernfalls wird versuchtdie uebergebene
+ Closure ausgetragen.
+
+BESCHREIBUNG
+------------
+
+ Hebt die Registrierung von <consumer> fuer einen bestimmten Hook-Typ
+ wieder auf.
+
+RUECKGABEWERTE
+--------------
+
+ 1 : Austragen erfolgreich
+ 0 : consumer nicht als Konsument gefunden
+
+SIEHE AUCH
+----------
+
+ :doc:`HRegisterToHook`, :doc:`HookCallback`, :doc:`HIsHookConsumer`
+
+Letzte Aenderung: 06.10.2022, Bugfix
diff --git a/doc/sphinx/lfun/HookCallback.rst b/doc/sphinx/lfun/HookCallback.rst
new file mode 100644
index 0000000..c3b60df
--- /dev/null
+++ b/doc/sphinx/lfun/HookCallback.rst
@@ -0,0 +1,66 @@
+HookCallback()
+==============
+
+FUNKTION
+--------
+
+ mixed HookCallback(object hooksource, int hookid, mixed hookdata)
+
+DEFINIERT IN
+------------
+
+ Eigenen Objekten
+
+ARGUMENTE
+---------
+
+ - hooksource: Das Objekt, in dem das Ereignis ausgeloest wurde
+ - hookid: Hooktyp des ausgeloesten Hooks
+ - hookdata: Daten des ausgeloesten Hooks
+ (S. Doku des jeweiligen Hooks.)
+
+BESCHREIBUNG
+------------
+
+ Standard-Callback-Methode fuer Hooks. Wird beim Registrieren ein Objekt
+ uebergeben, wird versucht, eine Closure auf HookCallback() an diesem Objekt
+ zu erstellen. Man kann die Funktion auch anders benennen und direkt als
+ Closure uebergeben. Dies ist insb. bei mehreren Hooks im gleichen Objekt
+ hilfreich, weil es den Code uebersichtlicher macht. Die Argumente muessen
+ jedoch immer die gleichen wie bei HookCallback() sein.
+
+ Die Reihenfolge des Aufrufs der Konsumenten ist Surveyor, Hook-Modifikator,
+ Data-Modifikator, Listener. Innerhalb der Gruppen wird nach Prioritaet
+ abgearbeitet.
+ Ein Surveyor-Hook kann verhindern, dass Hooks bestimmte Aenderungen
+ durchfuehren.
+
+RUECKGABEWERTE
+--------------
+
+ ({<status>, <hookdata>})
+
+ - Status: Eine der folgenden Konstanten:
+ - H_NO_MOD: keine Veraenderung
+ - H_ALTERED: Daten des Hooks geaendert
+ - H_CANCELLED: Die Ausfuehrung der Hook-Kette und das ausloesende
+ Ereignis werden abgebrochen
+ Nicht alle Hooks unterstuetzen jeden Status.
+ - hookdata: Die ggf. modifizierten Hookdaten.
+ (S. Doku des jeweiligen Hooks.)
+
+BEMERKUNGEN
+-----------
+
+ Bitte nutzt in neuem code nicht mixed, sondern unions entsprechend der
+ Dokumentation der verwendeten Hooks.
+
+ Auch reine Listener-Objekte muesse nein Array zurueckgeben, dessen erstes
+ Element H_NO_MOD sein muss.
+
+SIEHE AUCH
+----------
+
+ :doc:`HRegisterToHook`, :doc:`HUnregisterFromHook`, unions
+
+Letzte Aenderung: 06.10.2022, Bugfix