Set()

FUNKTION

public varargs mixed Set(string name, mixed Value, int Type, int extern);

DEFINIERT IN

/std/thing/properties.c
/sys/thing/properties.h (Prototyp)

ARGUMENTE

 name - Property, die manipuliert werden soll
 Value - der zu setzende/aendernde Wert
 Type - die Eigenschaft der Property, die manipuliert werden soll
 extern - Interne Verwendung:
Wurde Set ueber SetProp von aussen gerufen.

BESCHREIBUNG

Eine der inneren Eigenschaften der Property 'name' wird veraendert.
'Type' ist dabei einer der in /sys/thing/properties.h definierten
F_XXX - Werte:

F_VALUE (==0, default)
  Setzt den Inhalt der Property auf 'Value'. Aehnlich "SetProp",
  umgeht jedoch eine etwaige F_SET_METHOD oder _set_'name'()-Methode.
F_MODE
F_MODE_AS
F_MODE_AD
  Aendert eines der internen Flags der Property. F_MODE negiert den
  vorherigen Wert vom Flag 'Value', F_MODE_AS setzt und F_MODE_AD
  loescht ihn.
  Verfuegbare interne Flags:

    SAVE

      Property wird bei save_object() gespeichert

    PROTECTED

      Flag setzbar durch:   beliebiges Objekt
      Flag loeschbar durch: this_object(), ROOT, EM+
      Inhalt der Property veraendern sowie Set- und Query-Methoden
      setzen oder loeschen duerfen nur noch this_object(), ROOT, EM+
      WARNUNG: Dieses Flag nicht leichtfertig bei Spielern setzen!

    SECURED

      Flag setzbar durch:   this_object(), ROOT, EM+
      Flag loeschbar durch: Niemanden!
      Inhalt der Property veraendern sowie Set- und Query-Methoden
      setzen oder loeschen duerfen nur noch this_object(), ROOT, EM+

    NOSETMETHOD

      Property nicht mehr ueber SetProp() aenderbar
      (damit entfallen auch SET_METHOD, _set_'name')
F_SET_METHOD
  Aendert den Eintrag fuer eine SetMethod - eine Closure, die anstatt
  des Setzens der Property beim Aufruf von SetProp mit 'Value'
  aufgerufen wird.
F_QUERY_METHOD
  Aendert den Eintrag fuer eine QueryMethod - eine Closure, die anstatt
  des Lesens der Property beim Aufruf von QueryProp aufgerufen wird.

RUeCKGABEWERT

Das Ergebnis der Manipulation bzw. einer der definierten
Fehlercodes.

BEMERKUNGEN

 - Set() sollte nicht zum regulaeren Manipulieren des Inhalts einer
   Property verwendet werden, da sowohl F_SET_METHOD als auch libinterne
   _set_'name'()-Methoden umgangen werden und das Ergebnis fuer so
   veraenderte Properties undefiniert ist.
 - eine gesetzte F_SET/F_QUERY_METHOD hat bei SetProp/QueryProp Vorrang
   vor einer _set/_query_method
   -> _set/_query wird nach erfolgreichem Ruf von F_XXX_METHOD ignoriert
 - F_SET/F_QUERY_METHOD sollte normalerweise Vorzug vor einer
   _set_/_query_* gegeben werden.

SetMethods/QueryMethods:
 - falls ihr Query/SetMethods an oeffentlichen Properties setzen
   wollt, prueft bitte vorher, ob dort nicht schon eine (fremde) gesetzt
   ist und brecht ggf. euer Set() ab, um nicht die Arbeit anderer
   Mitmagier zu sabotieren (z.B. P_HANDS)
 - Properties sollten mit Query- oder SetMethoden nur so lange wie
   noetig belegt werden
   -> manche Properties sollte man als Wert setzen, _auch wenn_ die
      Spieler sie zuruecksetzen koennten (zB P_MSGIN/P_MSGOUT)
 - auf keinen Fall den Wert speichern, ueberschreiben, rueckschreiben,
   das fuehrt fast immer zu Problemen.
 - Set/QueryMethoden sollten nicht als Trigger/Listener fuer ein
   Ereignis (z.B. P_DIE_MSG fuer das Ereignis "Tod des Spielers")
   missbraucht werden
   -> es gibt sichere und saubere Moeglichkeiten (NotifyPlayerDeath),
      und wenn nicht, wendet euch an den EM eures Vertrauens
 - F_SET/F_QUERY_METHODs koennen 'protected' (empfohlen) oder 'static'
   sein. _set_/_query_ duerfen momentan _nicht_ 'protected' sein, fuer
   geht nur 'static' (in diesem Fall empfohlen).

BEISPIELE

### Aendern von Eigenschaften einer Property ###
// Setzen des SAVE-Flags (bei save_object() mitzuspeichern)
Set(P_XYZ, SAVE, F_MODE_AS);

// Loeschen des SAVE-Flags
Set(P_XYZ, SAVE, F_MODE_AD);



// Negieren des bisherigen SAVE-Flags
Set(P_XYZ, SAVE, F_MODE);
// Hinweis: das Setzen des Flags funktioniert mittels F_MODE nur dann,
// wenn sichergestellt ist, dass es vorher nicht gesetzt war. Die
// sichere Variante ist daher, F_MODE_AS zu verwenden.

// Sperren des SetProp/SET_METHOD-Zugriffs:
Set(P_XYZ, NOSETMETHOD, F_MODE_AS);

// Vorlaeufiger Zugriffsschutz fuer eine Property:
Set(P_XYZ, PROTECTED, F_MODE_AS);

// Permanenter Zugriffsschutz fuer eine Property:
Set(P_XYZ, SECURED, F_MODE_AS);

### Setzen einer SetMethod/QueryMethod ###
// Setzen einer internen SetMethod
mixed foo(mixed val);
...
Set(P_XYZ, #'foo, F_SET_METHOD);
...

// Setzen einer QueryMethod bei einem anderen Objekt
mixed bar();
...
other->Set(P_XYZ, #'bar, F_QUERY_METHOD);
...

// Der Vollstaendigkeit halber sei das Aendern einer Property unter
// Umgehung von Set-Methoden angegeben. Es ist aber aus o.g. Gruenden
// zu empfehlen, diese Variante nicht zu verwenden.
Set(P_XYZ, "bla", F_VALUE);

SIEHE AUCH

Aehnliches: SetProp(L), QueryProp(L), Query(L)
Generell:  SetProperties(L), QueryProperties(L)
Konzept:  properties, /std/thing/properties.c
Sonstiges:  P_AUTOLOADOBJ

6. Jan 2008 Arathorn