src/gestalt.c

   1 #include "glk.h"
   2
   3 /* Version of the Glk specification implemented by this library */
   4 #define MAJOR_VERSION 0
   5 #define MINOR_VERSION 7
   6 #define SUB_VERSION   0
   7
   8 /**
   9  * glk_gestalt:
  10  * @sel: A selector, representing which capability to request information
  11  * about.
  12  * @val: Extra information, depending on the value of @sel.
  13  *
  14  * Calls the gestalt system to request information about selector @sel, without
  15  * passing an array to store extra information in (see glk_gestalt_ext()).
  16  *
  17  * Returns: an integer, depending on what selector was called.
  18  */
  19 glui32
  20 glk_gestalt(glui32 sel, glui32 val)
  21 {
  22         return glk_gestalt_ext(sel, val, NULL, 0);
  23 }
  24
  25 /**
  26  * glk_gestalt_ext:
  27  * @sel: A selector, representing which capability to request information
  28  * about.
  29  * @val: Extra information, depending on the value of @sel.
  30  * @arr: Location of an array to store extra information in, or %NULL.
  31  * @arrlen: Length of @arr, or 0 if @arr is %NULL.
  32  *
  33  * Calls the gestalt system to request information about the capabilities of the
  34  * API. The selector @sel tells which capability you are requesting information
  35  * about; the other three arguments are additional information, which may or may
  36  * not be meaningful. The @arr and @arrlen arguments are always optional; you
  37  * may always pass %NULL and 0, if you do not want whatever information they
  38  * represent. glk_gestalt() is simply a shortcut for this; glk_gestalt(x, y) is
  39  * exactly the same as glk_gestalt_ext(x, y, NULL, 0).
  40  *
  41  * The critical point is that if the Glk library has never heard of the selector
  42  * sel, it will return 0. It is always safe to call glk_gestalt(x, y) (or
  43  * glk_gestalt_ext(x, y, NULL, 0)). Even if you are using an old library, which
  44  * was compiled before the given capability was imagined, you can test for the
  45  * capability by calling glk_gestalt(); the library will correctly indicate that
  46  * it does not support it, by returning 0.
  47  *
  48  * <note><para>
  49  *  It is also safe to call glk_gestalt_ext(x, y, z, zlen) for an unknown
  50  *  selector x, where z is not %NULL, as long as z points at an array of at
  51  *  least zlen elements. The selector will be careful not to write beyond that
  52  *  point in the array, if it writes to the array at all.
  53  * </para></note>
  54  *
  55  * <note><para>
  56  *  If a selector does not use the second argument, you should always pass 0; do
  57  *  not assume that the second argument is simply ignored. This is because the
  58  *  selector may be extended in the future. You will continue to get the current
  59  *  behavior if you pass 0 as the second argument, but other values may produce
  60  *  other behavior.
  61  * </para></note>
  62  *
  63  * Returns: an integer, depending on what selector was called.
  64  */
  65 glui32
  66 glk_gestalt_ext(glui32 sel, glui32 val, glui32 *arr, glui32 arrlen)
  67 {
  68         switch(sel)
  69         {
  70                 /* Version number */
  71                 case gestalt_Version:
  72                         return (MAJOR_VERSION << 16) + (MINOR_VERSION << 8) + SUB_VERSION;
  73
  74                 /* Which characters can the player type in line input? */
  75                 case gestalt_LineInput:
  76                         /* Does not accept control chars */
  77                         if( val < 32 || (val >= 127 && val <= 159) )
  78                                 return 0;
  79                         return 1;
  80
  81                 /* Which characters can the player type in char input? */
  82                 case gestalt_CharInput:
  83                         /* Does not accept control chars or unknown */
  84                         if( val < 32 || (val >= 127 && val <= 159) || val == keycode_Unknown )
  85                                 return 0;
  86                         return 1;
  87
  88                 /* Which characters can we print? */
  89                 case gestalt_CharOutput:
  90                         /* All characters are printed as one character, in any case */
  91                         if(arr && arrlen > 0)
  92                                 *arr = 1;
  93                         /* Cannot print control chars except \n, or chars > 255 */
  94                         if( (val < 32 && val != 10) || (val >= 127 && val <= 159) || (val > 255) )
  95                                 return gestalt_CharOutput_CannotPrint;
  96                         /* Can print all other Latin-1 characters */
  97                         return gestalt_CharOutput_ExactPrint;
  98
  99                 /* Unicode capabilities present */
 100                 case gestalt_Unicode:
 101                         return 1;
 102
 103                 /* Unsupported capabilities */
 104                 case gestalt_MouseInput:
 105                 case gestalt_Timer:
 106                 case gestalt_Graphics:
 107                 case gestalt_DrawImage:
 108                 case gestalt_Sound:
 109                 case gestalt_SoundVolume:
 110                 case gestalt_SoundNotify:
 111                 case gestalt_Hyperlinks:
 112                 case gestalt_HyperlinkInput:
 113                 case gestalt_SoundMusic:
 114                 case gestalt_GraphicsTransparency:
 115                 /* Selector not supported */
 116                 default:
 117                         return 0;
 118         }
 119 }
 120