[MiNT] Current appl_getinfo() implementations in XaAES

[Odd Skancke <ozk@atari.org>]

 hello, all.

 Below is a part of the file newcalls.txt, describing how XaAES
currently behaves (or should behave, not everything is tested).
Hopefully this will be agreed on, and implemented into MyAES as well.
Bear in mind that this documentation is not complete, it should be
merged into Opinions?


 <-- snip from newcalls.txt --->

                            -= Detecting XaAES =-

 appl_getinfo() is the correct call to use if the application wants to
know
 which AES it runs under.

 Normal binding;

 INPUT:
  control[0]    130                              Opcode
  control[1]      1                              Elements in intin
  control[2]      5 (or 1 - extended appl_info)  Elements in intout
  control[3]      0 (or n - extended appl_info)  Elements in addrin
  control[4]      0                              Elements in addrout

  intin[0]        Mode

 OUTPUT:
  intout[0]       Return value - 0 = failure, 1 = success
  intout[1]       ap_gout1
  intout[2]       ap_gout2
  intout[3]       ap_gout3
  intout[4]       ap_gout4

 With extended appl_info, control[N_ADDRIN] and control[N_INTOUT] is
consulted
 to determine what information should be returned based on 'Mode'. The
meaning
 of the different extended parameters are documented for each extended
'Mode'.

 If control[N_INTOUT] have a value of 1, the normal ap_gout[1-4]
elements are
 not used.

 If control[N_ADDRIN] have a value other than 0, then pointers are
passed in
 addrin[0 .. N_ADDRIN], whose value depends on the 'Mode' being used.


 AES_WINDOW (11) - XaAES adds the following;

 'ap_gout1'     Bit  9 wind_get/set(WF_WHEEL)
                Bit 10 wind_get(WF_FIRSTAREAXYWH)
                Bit 11 wind_get/set(WF_OPTS)
                Bit 12 wind_get/set(WF_MENU) 

 AES_MESSAGES (12) - XaAES addes the following;

 'ap_gout1'     Bit 10 WM_REPOSED supported.

---------------------- Extended appl_info() modes
--------------------------

 AES_VERSION (96)

 This is a new extended mode which will return detailed version
information
 about the AES. When control[N_INTOUT] == 5, the following is filled
into
 ap_gout[1-4];

  ap_gout1 = Major version number (decimal)
  ap_gout2 = Minor version number (decimal)
  ap_gout3 = Development Status (Beta, alpha, etc.)
  ap_gout4 = Target platform (m68k, etc.)
 'ap_gout1' &     Together, these two contain the decimal representation
of
 'ap_gout2'       the AES's version number. For XaAES v0.992, 'ap_out1'
                  contains 0 (0x0000) and 'ap_out2' contains 992
(0x3e0).
 'ap_gout3'       This is a 16-bit integer where bits 0-7 (the low byte)
is
                  a value indicating the development status of the AES,
                  see below (AES_DEVSTATUS_xxx) for meaning of different
                  values. Bits 8-15 are flags, see below
(AES_FDEVSTATUS_xxx)
                  for current definitions.
 'ap_gout4'       This is a value indicating which platform the AES was
built
                  for. See below (AES_ARCH_xxx) for meaning of different
                  values.

 When control[N_ADDRIN] == 4, the meaning of the pointers and what is
filled
 is defined as follows;

  addrin[0]     'aes_id' pointer
  addrin[1]     'long_name' pointer
  addrin[2]     'info_string' pointer
  addrin[3]	reserved, set to NULL.
 
 'aes_id'       This is a character string with a fixed lenght of 8
bytes,
                into which the AES will write its unique AES ID.
                the AES ID is a left-aligned, space padded string, and
can
                be considered to be the current AES's short name.
                For XaAES this string is filled with "   XaAES".

 'long_name'    This is a character buffer that the application must
ensure
                can take up to 256 (255 + 0 termination) characters. The
AES
                fills its long name description into this buffer. Lines
in
                here are delimitted using CR (ascii 13). For XaAES, this
                buffer contains the following after the call;

                "XaAES Ain't the AES, a free MultiTasking AES for
FreeMiNT"

 'info_string'  This is a character buffer that the application must
ensure
                can take up to 256 (255 + 0 termination) characters. The
AES
                fills this buffer with the following information where
each
                element is delimitted by the "|" (ascii 0x7c) character.
                The string is constructed as follows;

                "asci version|development status|architecture target|
                 build date & time|compiler used",0

                Example string returned might be;
                "0.992|Alpha|m68k|Dec 17 2004 22:58:52|gcc 2.95.3",0
 
 Here are new appl_info() constants to add to your header file;

/*
 * AES_VERSION mode for appl_init()
 */
#define AES_VERSION  96

/*
 * Target architecture definitions, returned by
 * appl_getinfo(AES_VERSION) in ap_gout4.
 */
#define AES_ARCH_M68K 0

/*
 * Development status - values low byte returned
 * by appl_getinfo(AES_VERSION) in low byte of ap_gout3 
 */
#define AES_DEVSTATUS_ALPHA   0
#define AES_DEVSTATUS_BETA    1
#define AES_DEVSTATUS_RELEASE 2
/*
 * Development status flags - bits 8-15 of ap_gout3
 * returned by appl_getinfo(AES_VERSION)
 */
#define AES_FDEVSTATUS STABLE 0x100


 <---- end snip ----->

 Best Regards
Odd Skancke