GuardExit()
***********


FUNKTION
========

   protected <int|<string|closure>* >* GuardExit(object room, int hookid,
                                                 <string|closure>* hdata);


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

   /std/npc/moving.c


ARGUMENTE
=========

   room
        Der den Hook ausloesende Raum (environment())
   hookid
        Die ID des Hooks (H_HOOK_EXIT_USE)
   hdata
        Ein Array mit 3 Elementen:
        ({
            verb - Das Kommandoverb/Ausgangsname (string)
            dest - Zielraum (string) oder closure (special exits)
            msg  - Bewegungsrichtung (string) oder 0
        })


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

   Ist diese Funktion in einem NPC definiert, traegt sich der NPC bei jeder
   Bewegung automatisch als Konsument von H_HOOK_EXIT_USE ein und diese
   Funktion wird immer gerufen, wenn ein Lebewesen im gleichen Environment
   wie der NPC versucht, einen Ausgang zu benutzen.
   Der NPC kann dann die Bewegung abbrechen (und so den Ausgang
   blockieren), Ziel oder Bewegungsmeldung aendern oder keine Veraenderung
   vornehmen.
   Die Konstanten fuer Hookid und Hookstatus (s. Rueckgabewert) sind in
   <hook.h> definiert.


RUeCKGABEWERT
=============

   Array mit zwei Elementen:
   ({
       H_NO_MOD / H_ALTERED / H_CANCELLED,
       hdata
   })
   hdata ist ggf. das geaenderte Array, welches die Funktion uebergeben
   wird. Weitere Details s. auch /doc/std/hooks


BEMERKUNGEN
===========

   Die Anzahl an Konsumenten eines Hooks ist begrenzt. Es ist daher
   moeglich, dass die Registrierung nicht klappt, wenn zuviele (>5) Waechter
   im Raum sind. Will man darauf reagieren, muesste man die Registrierung
   pruefen.
   Ein NPC, welcher GuardExit() definiert, aber im aktuellen Environment
   keine Wache halten will, koennte sich selber de-registrieren.


BEISPIELE
=========

    <int|<string|closure>* >* GuardExit(object room, int hookid,
                                        <string|closure>* hdata)
    {
      // Nur in Gefaengnisraeumen Wache halten
      if (strstr(object_name(environment()), "/room/jail")==0)
      {
        // Hier gehts nicht raus. ;-)
        if (hdata[0] == "raus") {
            tell_object(this_player(), ...);
            return ({H_CANCELLED, hdata});
        }
        // Special exits ersetzen wir durch einen eigenen
        else if (closurep(hdata[1])) {
          hdata[1] = #'my_special_exit;
          return ({H_ALTERED, hdata});
        }
        // alle anderen Ausgaenge in die persoenliche Zelle
        else {
          tell_object(this_player(), ...);
          hdata[1] = "/room/jail_"+getuid(this_player());
          hdata[2] = "Sueden";
          return ({H_ALTERED, hdata});
        }
     }
     // in allen anderen Raeumen nicht eingreifen
     return ({H_NO_MOD, hdata});
   }


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

   AddExit, AddSpecialExit, RemoveExit
   HRegisterToHook, HRegisterModifier, HUnregisterFromHook
   /doc/std/hooks

20.02.2016, Zesstra 22.05.2016, Mupfel (Beispiel korrigiert)