RegisterHelperObject()
**********************


FUNKTION
========

   int RegisterHelperObject(object helper, int type,
                            string|closure callback);


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

   /std/living/helpers.c


ARGUMENTE
=========

   object helper
     Das Objekt, das bei einem Lebewesen als Hilfsobjekt registriert
     werden soll. Das Objekt muss sich dazu nicht im Inventar des
     Lebewesens befinden.
   int type
     Helfertyp, einer der in /sys/living/helpers.h definierten Typen:
     - HELPER_TYPE_AERIAL fuer die Flug-/Segelunterstuetzung
     - HELPER_TYPE_AQUATIC fuer Tauchunterstuetzung
   string|closure callback
      Closure oder Funktionsname als String; dies ist die Funktion, die im
      Objekt helper gerufen wird, um abzufragen, ob es sich aktuell fuer
      zustaendig erklaert oder nicht.


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

   Das Objekt "helper" wird als Hilfsobjekt fuer bestimmte Aktivitaeten wie
   zum Beispiel Fliegen oder Tauchen registriert.


   Die als Callback uebergebene Funktion wird bei der Abfrage der
   P_*_HELPERS-Properties (siehe unten) aufgerufen und deren
   Rueckgabewert in der Property vermerkt.


   Der Rueckgabewert der Callback-Methode muss im Wertebereich
   0..10000 liegen, wobei ein Wert von 0 bedeutet, dass das Hilfsobjekt
   sich gerade nicht zustaendig fuehlt. Bei den Werten >0 ist es dem
   abfragenden Objekt ueberlassen, wie es diese Daten bewertet.

   Die Funktion muss existieren und public sein, d.h. von aussen gerufen
   werden koennen.


   Die Funktion bekommt das Spielerobjekt und das abfragende Objekt als
   Parameter uebergeben.


HINWEIS
=======

   Es ist ein Unterschied, ob sich ein Objekt via UnregisterHelperObject()
   als Helfer austraegt, oder ob der Aufruf der Callback-Funktion eine
   0 zurueckgibt. Im letzteren Fall ist das Objekt nach wie vor
   registriert und kann trotzdem vom abfragenden Objekt als
   funktionsfaehig angesehen werden.


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

    1  Objekt wurde erfolgreich registriert (HELPER_SUCCESS)
   -1  angegebenes Hilfsobjekt existiert nicht (HELPER_NO_CALLBACK_OBJECT)
   -2  angegebenes Hilfsobjekt ist bereits fuer diese Art der
       Unterstuetzung registriert (HELPER_ALREADY_LISTED)


BEISPIELE
=========

   a) Eine luftgefuellte Blase will sich als Tauch-Helfer am Spieler
   anmelden und ist zustaendig, solange sich noch Luft in ihr befindet:

   int luft = 5; // globale Variable z.B. fuer Luftinhalt von 5 Atemzuegen

   // Registrierung im Spielerobjekt
   if ( TP->RegisterHelperObject(ME, HELPER_TYPE_AQUATIC,
        "DivingCallback") == HELPER_SUCCESS ) {
     tell_object(TP, "Du kannst jetzt mit Hilfe der Luftblase unter Wasser "
       "atmen.\n");
   }

   // hier koennen natuerlich auch noch komplexere Dinge ablaufen, z.B.
   // wenn ein Wert zurueckgegeben werden soll, der nicht nur 0 oder 1 ist.
   public int DivingCallback(object player, object caller) {
     return (environment(ME)==player && luft>0);
   }

   b) Ein Spieler befindet sich in einem Raum mit einem steilen Abhang, den
   man hinunterspringen kann. Dies geht aber nur dann gefahrlos, wenn es
   Hilfsobjekte gibt, die den (Segel)flug erlauben:

   // cmd_springen() sei die Funktion, die bei der Eingabe des Befehls durch
   // den Spieler aufgerufen wird.
   static int cmd_springen(string str) {
     [...]
     // Property abfragen
     mapping helpers = TP->QueryProp(P_AERIAL_HELPERS);
     // Liste der Werte fuer die einzelnen Unterstuetzungsobjekte ermitteln
     int *values = m_values(helpers,0);
     // Spieler schonmal runterbewegen, die Folgen seines Handelns spuert
     // er dann, wenn er unten angekommen ist.
     TP->move(zielraum, M_GO|M_SILENT);
     // "helpers" ist immer ein Mapping, das pruefen wir nicht extra.
     // Wenn die Liste der Objekte noch mindestens ein Element enthaelt,
     // nachdem alle unzustaendigen Hilfsobjekte (Rueckgabewert der
     // Callback-Funktion == 0) rausgerechnet wurden, existiert mindestens
     // ein geeignetes Hilfsobjekt.
     if ( sizeof(values-({0})) ) {
       tell_object(TP, "Sanft segelst Du den Hang hinab.\n");
     }
     else {
       tell_object(TP, BS("Todesmutig springst Du den Hang hinab und "
         "schlaegst hart unten auf. Du haettest vielleicht daran denken "
         "sollen, Dir geeignete Hilfsmittel fuer so eine Aktion zu "
         "besorgen.");
       TP->Defend(800, ({DT_BLUDGEON}), ([SP_NO_ACTIVE_DEFENSE:1]), ME);
     }
     return 1;
   }


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

   Funktionen:  UnregisterHelperObject(), GetHelperObject()
   Properties:  P_HELPER_OBJECTS, P_AERIAL_HELPERS, P_AQUATIC_HELPERS
   Sonstiges:   /sys/living/helpers.h

05.02.2015 Arathorn