OBJECT
       /std/weather


UPDATE
       Mateese, 08-Sep-1994, 16:00 MET


SYNOPSIS
       #include <weather.h>

       inherit "/std/weather";


DESCRIPTION
       This is the standard weather server. It implements the basic
       mechanisms used for a weather server, along with some auxiliary
       functions. It is not meant for stand-alone use but only for
       inheritance.

       Though the server implements the weather by a fixed number of
       states, all collected in one big array, all calls are done
       through the 'official' functions and properties so any
       non-numbering weather scheme is possible, too.

       The standard calls and builtin properties are all there:

	 mixed * P_STATEDATA   "StateData"
	   The data-array for the _current_ state.
	   If set, the new data will erased with the next state
	   transition.
	   When querying the 'true' statedata (say: performing a call
	   'QueryStateData(1)') the result will be the true current
	   statedata regardless of any changes done since transition.

	 string P_STATEDESC    "StateDesc"
	   The description WD_DESC of the current state.
	   If set, the new data will erased with the next state
	   transition.

	 string P_CHANGEDESC   "ChangeDesc"
	   The change description WD_CDESC of the current state.
	   If set, the new data will erased with the next state
	   transition.

	 int	P_SUNLIGHT     "SunLight"
	   The sunlight WD_SUNLIGHT of the current state.
	   If set, the new data will erased with the next state
	   transition.

	 int	P_LENGTH       "Length"
	   The duration WD_DURATION of the current state in seconds.
	   If set, the new data will erased with the next state
	   transition.

	 int TimeLeft()
	   Returns the seconds left till the next state transition.

	 void NextState ()
	   Forces a state transition.

	 void InitStates ()
	   This function has to setup P_STATES (or equivalent).
	   The default action is to query the official NIGHTDAY server
	   for its data.

	 void StartServer (void)
	   This is to initialize and start the weather service.
	   If P_STATES is set, the function will deduce the current
	   state from the data and the current time and set it.
	   Else, if P_STATES is 0, it will just 'SetState(0)' and
	   exit.

       InitStates() and StartServer() is called upon creation as last
       action by the /std/server's 'create()'. This way the actual
       server has the opportunity to setup its specific state data in
       time.
       If you just want to change the descriptions, not the timing (as
       it is recommended), overload in your server InitStates(), call
       the inherited InitStates() and then modify the P_STATES.


       The /std/weather organizes it's internal data as an array of
       all statedata, thus imposing a numberable set of states.
       In most cases, the number of states will be fixed, but that is
       not assumed by the servers code.
       The collected data is managed with these calls and builtin
       properties:

	 int CountStates ()
	   Return the (current) number of states of this server.
	   If the server doesn't have numberable states, return 0.


	 mixed * P_STATES   "States"
	   The array of all single statedata.


	 int	  P_STATE    "State"
	   The ordinal number of the current state.
	   The setting of it is special:

	     int SetState (int number, void|int no_callout)

	       If <no_callout> is not zero, the call_out() for the
	       next state transition is not restarted.
	       Else the next state transition would occur after the
	       time determined by WD_LENGTH of the set state.

	   Setting the state causes also all clients to be notified.
	   During the notification, P_STATE is still the old state!


	 mixed QueryStateEntry (int ix)
	 mixed SetStateEntry (int ix, mixed data)
	   Query/Set the state<data> for the given entry number <ix>
	   from the P_STATES array.


       The /std/server also contains the code necessary for handling
       the clients:

	 object * P_CLIENTS   "Clients"
	   The array of all subscribed clients.

	 void AddClient (object client)
	   Adds the given <client> to the P_CLIENTS array.


	 void RemoveClient (object client)
	   Removes the given <client> from the P_CLIENTS array.

	 void CleanupClients ()
	   Removes all destructed clients from the P_CLIENTS array.
	   If the array is large, this is done with a series
	   of call_out()s.

       The notification of all clients and affected players are done
       with these functions:

	 mixed * FilterData (object client, mixed *data, int newstate)
	   The <client> is located using IsMyPlayer() and the
	   state<data> and <newstate> is filtered through all of its
	   environments, calling their lfun FilterWeatherData(),
	   starting with outmost environment (the outdoors room).
	   If the <client> is interactive and not within the servers
	   range, or its environments filter the <data> completely out,
	   0 is returned, else the filtered data to use.

	 void NotifyClients (void|mixed *statedata, void|int newstate)
	   All clients and affected players are notified about the
	   state given by <statedata> (default is the current state).
	   <newstate> denotes the state set after the all clients are
	   notified.
	   This is done by calling NotifyClient(), possibly from an
	   call_out().

	 int NotifyClient (object client, mixed *data, int newstate)
	   Notify the <client> with the state<data> and <newstate> after
	   filtering it through FilterData() by setting the filtered data
	   as the P_STATEDATA property. For interactive users, this
	   will tell the WD_CDESC to the user.

	 int IsMyPlayer (object player, void | object &env)
	   This function (also called by FilterData()) returns
	   0 if the <player> is not within the range of the server,
	   else it returns the count+1 of environments the player has.
	   The 'count-1'th environment is the outdoors room, and will
	   be put into <env> if given.


INHERITANCE TREE

       weather


SEE ALSO
       weather(C), room(S), nightday(O)