src/NetworkOLK/features.hxx

   1 // features.hxx - Exporting feature access to remote applications
   2 //
   3 // Started by Alex Perry
   4 //
   5 // Copyright (C) 2000  Alexander Perry - alex.perry@ieee.org
   6 //
   7 // This program is free software; you can redistribute it and/or
   8 // modify it under the terms of the GNU General Public License as
   9 // published by the Free Software Foundation; either version 2 of the
  10 // License, or (at your option) any later version.
  11 //
  12 // This program is distributed in the hope that it will be useful, but
  13 // WITHOUT ANY WARRANTY; without even the implied warranty of
  14 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15 // General Public License for more details.
  16 //
  17 // You should have received a copy of the GNU General Public License
  18 // along with this program; if not, write to the Free Software
  19 // Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  20 //
  21 // $Id$
  22
  23
  24 #ifndef FG_FEATURES
  25 #define FG_FEATURES
  26
  27
  28 #ifdef HAVE_CONFIG_H
  29 #  include <config.h>
  30 #endif
  31
  32 #include <simgear/compiler.h>
  33
  34 #include <time.h>
  35 #include STL_STRING
  36
  37 SG_USING_NAMESPACE(std);
  38
  39
  40 /*
  41  * FEATURES
  42  *
  43  * This class accepts static variables from arbitrary other parts
  44  * of the code and maintains a list of their locations and the
  45  * heirarchical names that the user associates with them.
  46  * This is essentially a runtime symbol table.  The associated
  47  * library dynamically builds (and rebuilds) a menu tree from this
  48  * information.  One or more remote console programs, that do
  49  * not need to be under the same operating system, can query
  50  * the contents of the list, request values and force changes.
  51  */
  52
  53 class FGFeature
  54 {
  55 public:
  56
  57 /* These have no effect on the value, but it should be
  58    considered volatile across any call to update() below
  59 */
  60    static void register_float  ( char *name, float  *value );
  61    static void register_double ( char *name, double *value );
  62    static void register_int    ( char *name, int    *value );
  63    static void register_char80 ( char *name, char   *value );
  64    static void register_string ( char *name, char   *value );
  65
  66 /* Note that the char80 is a fixed length string,
  67    statically allocated space by the registering program.
  68    In contrast, the string type is dynamically allocated
  69    and the registering program must have alloca()'d the default.
  70    Please don't use either of those if the numerics are usable.
  71 */
  72
  73 /* If you want to have a single variable available under two
  74    names, use this call.  This is equivalent to making the
  75    registering call above twice, except that you don't need
  76    to know the memory location of the original variable.
  77    If you create an alias to a variable that isn't registered,
  78    the alias is invisible but will subsequently appear if needed.
  79 */
  80    static void register_alias ( char *name, char *value );
  81
  82 /* Use this when the user requests that a feature be changed
  83    and you have no idea where it might be located in memory.
  84    Expect a non-zero return code if request cannot be completed.
  85 */
  86    static int modify   ( char *name, char *newvalue );
  87
  88 /* Programs wishing to traverse the list of registered names will
  89    use the first call to find out how many names are registered,
  90    and then iteratively use the second call to get the names.
  91    The third/fourth calls will retrieve the value as a string.
  92 */
  93    static int   index_count ();
  94    static char *index_name  ( int index );
  95    static char *index_value ( int index );
  96    static char *get_value ( char *name );
  97
  98 /* It is much more efficient to build the menu if you have full
  99    access to the data structures.  Therefore this is implemented
 100    internal to the module, even though the above functions would
 101    suffice for an inefficient external implementation.
 102 */
 103    static void maybe_rebuild_menu();
 104
 105 /* This should be called regularly.  It services the connections
 106    to any remote clients that are monitoring or maintaining data
 107    about the flight gear session in progress.  This service is
 108    expected to operate embedded inside the NetworkOLK stuff.
 109 */
 110    static void update();
 111
 112 private:
 113
 114    static void register_void  ( char *name, char itstype, void *value );
 115
 116 /* I don't have anything in mind for this section (yet).
 117 */
 118
 119
 120 };
 121 #endif // FG_FEATURES