Main Page | Modules | Data Structures | File List | Data Fields | Globals | Related Pages

Application Services Library
[AES Function Reference]

initialization and interprocess communication More...

Functions

short mt_appl_bvset (short bvdisk, short bvhard, short *global_aes)
short mt_appl_control (short ap_cid, short ap_cwhat, void *ap_cout, short *global_aes)
short mt_appl_exit (short *global_aes)
short mt_appl_find (const char *name, short *global_aes)
short mt_appl_getinfo (short type, short *out1, short *out2, short *out3, short *out4, short *global_aes)
short mt_appl_init (short *global_aes)
short mt_appl_read (short ap_id, short length, void *ap_pbuff, short *global_aes)
short mt_appl_search (short mode, char *fname, short *type, short *ap_id, short *global_aes)
short mt_appl_tplay (void *mem, short num, short scale, short *global_aes)
short mt_appl_trecord (void *mem, short count, short *global_aes)
short mt_appl_write (short ap_id, short length, void *ap_pbuff, short *global_aes)
short mt_appl_yield (short *global_aes)

Detailed Description

initialization and interprocess communication

The Application Services Library provides general use functions used in locating and working with other resident applications in addition to providing AES initialization and termination code.


Function Documentation

short mt_appl_bvset short  bvdisk,
short  bvhard,
short global_aes
 

tell PC-GEM which logical drives are connected to the system (for the file selector box).

Parameters:
bvdisk Bit vector with all connected disk drives. Bit 15 (the most significant bit) denotes drive A:
bvhard Bit vector with all connected hard drives.
global_aes global AES array
Returns:
Unknown
Since:
only available on PC-GEM (as of version 2.0)

short mt_appl_control short  ap_cid,
short  ap_cwhat,
void *  ap_cout,
short global_aes
 

Can be used to control the activity of applications.

Parameters:
ap_cid the AES ID (apid) of the application you want to control.
ap_cwhat the type of control (refer to the table below)
ap_cout is filled by the AES dependent on ap_cwhat.
global_aes global AES array
Returns:
0 if an error has occurred or a value>0 otherwise.
Since:
N.AES
See also:
SM_M_SPECIAL
The table hereafter summaries the action performed by mt_appl_control() depending on the value given in ap_cwhat.

Values of ap_cwhat Description
0..9 Reserved for N.AES
APC_HIDE Hide (fade out) application. If ap_cid is -1, the active application will be hidden.
APC_SHOW Show (fade in) application. If ap_cid is -1, all hidden applications are shown.
APC_TOP Bring application to front (the application becomes the active one).
APC_HIDENOT Hide all applications except the one referred to by ap_cid (which becomes the active application). If ap_cid is -1, all applications except the active one will be hidden.
APC_INFO Get the application parameter of the application ap_cid. If ap_cid is set to -1, the parameters of the active application are returned. ap_cout must point to a short variable. This variable is a bitmap variable:
APC_MENU The last used menu tree is returned. The parameter ap_cout is a pointer to an pointer of OBJECT. The AES fills in the address of the menu tree. If ap_cid is set to -1, the address of the menu tree of the active application is returned. If ap_cid is set to 0 the address of the system menu (AES internally) is returned. If the wanted application has no menu bar or if the wanted application doesn't exist, a NULL-pointer is returned in *ap_cout. The return value always equals 1.
Hint: the developer must know what he does! The changing of the tree can result in undefined system states. If MiNT memory protection is active, a read of the menu bar can result in an violation and terminate the application!
APC_WIDGETS This mode inquires or sets the 'default' positions of the window widgets. ap_cout is a pointer to buffer of size of MINWINOB (=12) short integers (16 bits). For inquiring the OBJECT order this buffer must be filled completly with -1. The last short must equal 0! If an error is returned the buffer is not large enough for all objects and should be enlarged. In the buffer the objects are contained in the following order: first the title bar from the left to the right, the objects of the vertical slider from top to bottom, the objects of the horizontal sloder from the left to the right. The list is terminated with a 0 short. For setting the positions, the first objects must be of the type topwidgets (from the left to the right), the next objects of the type right widgets (from top to bottom) and the last objects of the type bottom widgets (from the left to the right). If objects are set doubly or wrong, an error is returned.

Hidden application have a '*' placed in front of their names in the applications menu, unless they did not have a window open during hiding. If the latter is the case only the active application is changed.

So the '*' in front of the name means: One ore more windows of this application are hidden.

short mt_appl_exit short global_aes  ) 
 

Unregister an application from the AES and free its AES ID.

Parameters:
global_aes global AES array
Returns:
0 if an error occurred or non-zero otherwise.
Since:
All AES versions.
See also:
mt_appl_init()
The handling of an error (return value 0) is currently undefined.

short mt_appl_find const char *  name,
short global_aes
 

searches the AES's current process list for a program named Name and, if present, returns the application identifier of the process.

Parameters:
name is a pointer to a null-terminated ASCII string containing a valid GEMDOS filename (not including an extension) padded with blanks to be exactly 8 characters long (not including the NULL).
global_aes global AES array
Returns:
the application identifier of the process if it is found or -1 otherwise.
Since:
All AES versions.
See also:
mt_appl_write(), mt_appl_init()
AES versions from 4.0 add several extensions to this call for the benefit of MultiTOS. This functionality only exists if the AES version is 4.0 and above and mt_appl_getinfo() indicates that it is available. Here is the extension description:
  • If the upper word of the CHAR * is 0xFFFF, the lower word is assumed to be the MiNT id and mt_appl_find() will return the AES application identifier.
  • If the upper word of the CHAR * is 0xFFFE, the lower word is assumed to be the AES application identifier and the MiNT id is returned.
  • If the upper word of the CHAR * is 0x0000, the current processes' application identifier is returned.

short mt_appl_getinfo short  type,
short out1,
short out2,
short out3,
short out4,
short global_aes
 

returns information about the AES.

Parameters:
type specifies the type of information to be returned in the shorts pointed to by out1, out2, out3 and out4.
out1 1st return value
[option CHECK_NULLPTR] out1 may be NULL
out2 2nd return value
[option CHECK_NULLPTR] out2 may be NULL
out3 3rd return value
[option CHECK_NULLPTR] out3 may be NULL
out4 4th return value
[option CHECK_NULLPTR] out4 may be NULL
global_aes global AES array
Returns:
0 if an error occurred or non-zero otherwise.
Since:
Available as of AES version 4.00.
See also:
mt_appl_init()
The table hereafter summaries the values returned in out1, out2, out3 and out4 depending on the type of information requested.

Name Value Returns
AES_LARGEFONT 0 AES Large Font Information:
  • out1 is filled in with the AES font's point size.
  • out2 is filled in with the font id.
  • out3 is a code indicating the type of font:
  • out4 is unused.

AES_SMALLFONT 1 AES Large Font Information: Same as above for the current small font.

AES_SYSTEM 2 AES System Specifics
  • out1 is filled in with the resolution number (as would be returned by Getrez()).
  • out2 is filled in with the number of colors supported by the AES object library.
  • out3 is 0 if color icons are not supported or 1 if they are.
  • out4 is 0 to indicate that the extended resource file format is not supported or 1 if it is.

AES_LANGUAGE 3 AES Globalization

AES_PROCESS 4 AES Multiple Process Support
  • out1 is 0 to indicate the use of non-pre-emptive multitasking and 1 to indicate the use of pre-emptive multitasking.
  • out2 is 0 if mt_appl_find() cannot convert between MiNT and AES id's and 1 to indicate that it can.
  • out3 is 0 if mt_appl_search() is not implemented and 1 if it is.
  • out4 is 0 if mt_rsrc_rcfix() is not implemented and 1 if it is.

AES_PCGEM 5 AES PC-GEM Features

AES_INQUIRE 6 AES Extended Inquiry Functions

#(reserved) 7 Currently reserved.

AES_MOUSE 8 AES Mouse Support
  • out1 is 0 to indicate that mode parameters of 258-260 are not supported by mt_graf_mouse() and 1 if they are.
  • out2 is 0 to indicate that the application has control over the mouse form and 1 to indicate that the mouse form is maintained by the AES on a per-application basis.
  • out3 and out4 are currently unused.

AES_MENU 9 AES Menu Support
  • out1 is 0 to indicate that sub-menus are not supported and 1 if MultiTOS style sub-menus are.
  • out2 is 0 to indicate that popup menus are not supported and 1 if MultiTOS style popup menus are.
  • out3 is 0 to indicate that scrollable menus are not supported and 1 if MultiTOS style scrollable menus are.
  • out4 is 0 to indicate that the MN_SELECTED message does not contain object tree information in msg[5,6,7] and 1 to indicate that it does.

AES_SHELL 10 AES Shell Support
  • out1 & 0x00FF indicates the highest legal value for the mode parameter of mt_shel_write(). (parameter wodex & 0x00FF)
  • out1 & 0xFF00 indicate which extended mt_shel_write() mode bits are supported. (parameter wodex & 0xFF00)
  • out2 is 0 if mt_shel_write() with a mode parameter of 0 (SWM_LAUNCH) launches an application or 1 if it cancels the previous mt_shel_write().
  • out3 is 0 if mt_shel_write() with a mode parameter of 1 (SWM_LAUNCHNOW) launches an application immediately or 1 if it takes effect when the current application exits.
  • out4 is 0 if ARGV style parameter passing is not supported or 1 if it is.

AES_WINDOW 11 AES Window Features
  • out1 is a bitmap of extended modes supported by mt_wind_get() and/or mt_wind_set() (if a bit is set, it is supported) as follows:
    Bit mode
    0 WF_TOP returns window below the top also.
    1 WF_NEWDESK get.
    2 WF_COLOR get/set.
    3 WF_DCOLOR get/set.
    4 WF_OWNER get/set.
    5 WF_BEVENT get/set.
    6 WF_BOTTOM set.
    7 WF_ICONIFY set.
    8 WF_UNICONIFY set.
    9-15Unused
  • out2 is current unused.
  • out3 is a bitmap of supported window behaviors (if a bit is set, it is supported) as follows:
    Bit Behaviour
    0 Iconifier gadget present.
    1 Bottomer gadget present.
    2 shift-click sends window to bottom.
    3 "hot" close box supported.
    4-15Unused
  • out4 is currently unused.

AES_MESSAGE 12 AES Extended Messages
  • out1 is a bitmap of extra messages supported (if a bit is set, it is supported) as follows:
    Bit Message
    0 WM_NEWTOP is meaningful.
    1 WM_UNTOPPED is sent.
    2 WM_ONTOP is sent.
    3 AP_TERM is sent.
    4 Shutdown and resolution change messages.
    5 CH_EXIT is sent.
    6 WM_BOTTOMED is sent.
    7 WM_ICONIFY is sent.
    8 WM_UNICONIFY is sent.
    9 WM_ALLICONIFY is sent.
    10-15 Unused
  • out2 is a bitmap of extra messages supported. Current all bits are unused.
  • out3 is a bitmap indicating message behaviour (if a bit is set, the behaviour exists) as follows:
    Bit Message
    0 WM_ICONIFY message gives coordinates.
    1-15 Unused
  • out4 is currently unused.

AES_OBJECT 13 AES Extended Objects
  • out1 is 0 if 3D objects are not supported or 1 if they are.
  • out2 is 0 if mt_objc_sysvar() is not present, 1 if MultiTOS v1.01 mt_objc_sysvar() is present, or 2 if extended mt_objc_sysvar() is present.
  • out3 is 0 if the system font is the only font supported or 1 if GDOS fonts are also supported.
  • out4 is reserved for OS extensions.

AES_FORM 14 AES Form Support
  • out1 is 0 if 'flying dialogs' are not supported or 1 if they are.
  • out2 is 0 if keyboard tables are not supported or 1 if Mag!X style keyboard tables are supported.
  • out3 is 0 if the last cursor position from mt_objc_edit() is not returned or 1 if it is.
  • out4 is currently reserved.

extended functions 64 Extended functions

Additional N.AES functions 65 Additional N.AES functions

Using an ap_gtype value of 4 and above is only supported as of AES version 4.1

Many of the ap_gtype return values identify features of TOS not supported by Atari but for the benefit of third-party vendors. You should contact the appropriate third-party for documentation on these functions.

Note:
If mt_appl_getinfo() is not implemented (mt_AESversion() < 0X0400 and the application "?AGI" (Winx, Magic>2) is not found), the trap is not performed (may crash on some system).

MagiC 2 have this AES call implemented, but "?AGI" is here since MagiC3 only... so this call will not work as expected with Magic2. One way is to check the magx cookie but i don't want to create dependencies between gemlib and any standard libc. So ATM, mt_appl_getinfo() is not executed on Magic2. Is it a real problem ?

short mt_appl_init short global_aes  ) 
 

should be the first function called in any application that intends to use GEM calls.

Parameters:
global_aes global AES array
Returns:
the applications' global identifier if successful or -1 if the AES cannot register the application. If successful, the global identifier should be stored in a global variable for later use. GEM applications may not make any AES or VDI calls unless mt_appl_init() succeeds. Besides the return value, the AES fills in the application's global array ( global_aes) as following:
Name index of global_aes[] Meaning

mt_AESversion() 0 AES version number.

mt_AESnumapps() 1 Number of concurrent applications possible (normally 1). MultiTOS will return -1.

mt_AESapid() 2 Application identifier (same as mt_appl_init() return value).

mt_AESappglobal() 3-4 LONG global available for use by the application.

mt_AESrscfile()5-6 Pointer to the base of the resource loaded via mt_rsrc_load().

(reserved) 7-12 Reserved

mt_AESmaxchar() 13 Current maximum character used by the AES to do vst_height() prior to writing to the screen. This entry is only present as of AES version 0x0400.

mt_AESminchar() 14 Current minimum character used by the AES to do vst_height() prior to writing to the screen. This entry is only present as of AES version 0x0400.
Since:
All AES versions.
See also:
mt_appl_exit()

short mt_appl_read short  ap_id,
short  length,
void *  ap_pbuff,
short global_aes
 

is designed to facilitate inter-process communication between processes running under the AES. The call will halt the application until a message of sufficient length is available (see version notes below).

Parameters:
ap_id is your application identifier as returned by mt_appl_init().
length is the length (in bytes) of the message to read.
ap_pbuff is a pointer to a memory buffer where the incoming message should be copied to.
global_aes global AES array
Returns:
0 if an error occurred or non-zero otherwise.
Since:
All AES versions.
See also:
mt_appl_write()
If the AES version is 4.0 or higher and mt_appl_getinfo() indicates that this feature is supported, ap_id takes on an additional meaning. If APR_NOWAIT (-1) is passed instead of ap_id, mt_appl_read() will return immediately if no message is currently waiting.

Normally this call is not used. mt_evnt_multi() or mt_evnt_mesag() is used instead for standard message reception. mt_appl_read() is required for reading messages that are long and/or of variable length. It is recommended that message lengths in multiples of 16 bytes be used.

short mt_appl_search short  mode,
char *  fname,
short type,
short ap_id,
short global_aes
 

provides a method of identifying all of the currently running processes.

Parameters:
mode specifies the search mode as follows:
  • APP_FIRST (0) Return the filename of the first process
  • APP_NEXT (1) Return the filename of subsequent processes
  • APP_DESK (2) Return the filename of the desktop
fname should point to a memory location at least 9 bytes long to hold the 8 character process filename found and the NULL byte.
type is a pointer to a WORD into which will be placed the process type as follows: [option CHECK_NULLPTR] type may be NULL
ap_id is a pointer to a word into which will be placed the processes' application identifier.
[option CHECK_NULLPTR] ap_id may be NULL
global_aes global AES array
Returns:
0 if no more applications exist or 1 when more processes exist that meet the search criteria.
Since:
Available only in AES versions 4.0 and above when mt_appl_getinfo() indicates its presence.
The type parameter is actually a bit mask so it is possible that a process containing more than one characteristic will appear. For example, the desktop may return a value of APP_APPLICATION | APP_SHELL (0x0A).

short mt_appl_tplay void *  mem,
short  num,
short  scale,
short global_aes
 

plays back events originally recorded with mt_appl_trecord().

Parameters:
mem is a pointer to an array of EVNTREC structures (see mt_appl_trecord())
num indicates the number of EVNTREC's to play back.
scale indicates on a scale of 1 to 10000 how fast the AES will attempt to play back your recording. The "original" doc says that the normal speed is 100 (200 = twice speeder, 50 = twice slower... it's linear), but in most cases, 4 shall be used for normal speed (8=twice speeder, 2=twice slower..). See the important note below to know what's the right value for you.
global_aes global AES array
Returns:
always returns 1 meaning no error occurred.
Since:
All AES versions.
See also:
mt_appl_trecord()
This function does not work correctly on AES versions less than 1.40 without a patch program available from Atari Corp..

Note:
The mt_appl_trecord() function is bugged and stores a count of a 200Hz timer in EVNTREC::ap_value for APPEVNT_TIMER events, instead of a number of millisecondes. So, there is a coefficient of 5 between the value stored by mt_appl_trecord() and the value expected by mt_appl_tplay(). The mt_appl_tplay() function takes care of that and adds a coefficient of 5 for APPEVNT_TIMER event... but this has been implemented the wrong way ! and now the coefficient between "time" recorded by mt_appl_trecord() and "time" played by mt_appl_tplay() is 25. That's the reason why the right value for the scale parameter is 100/25=4 for normal speed, 200/25=8 for twice speeder replay, 50/25=2 for twice slower replay...

About the previous note: this story is just an hypothesis to explain the fact: the official doc says 100=normal speed but experiences have proven that 4=normal speed (Magic, tos).

Geneva seems to follows exactly the original doc. So, events recorded by Geneva should be played by geneva with scale=100 for normal speed; and event recorded by magic should be replayed by geneva with scale=500 for normal speed...

short mt_appl_trecord void *  mem,
short  count,
short global_aes
 

records AES events for later playback.

Parameters:
mem points to an array of Count EVNTREC structures
count dimension of the array of EVNTREC structures into which the AES will record events
global_aes global AES array
Returns:
addreturns the number of events actually recorded.
Since:
All AES versions.
See also:
mt_appl_tplay()
This function does not work correctly on AES versions less than 1.40 without a patch program available from Atari Corp.

Note:
ap_value seems to have words swapped (APPEVNT_MOUSE: X pos is in the high word and Y pos is in the low word).

Warning: the "elapsed time" unit should be milliseconds but it seems that most of the AES fill this value with a count of the 200Hz timer... but this is taken into account by a dirty and bugged workaround in mt_appl_tplay().

It seems that Geneva follows the original doc and stores the "elapsed time" in milliseconds.

short mt_appl_write short  ap_id,
short  length,
void *  ap_pbuff,
short global_aes
 

can be used to send a message to a valid message pipe.

Parameters:
ap_id is the application identifier of the process to which you wish to send the message.
length specifies the number of bytes present in the message.
ap_pbuff is a pointer to a memory buffer with at least length bytes available
global_aes global AES array
Returns:
0 if an error occurred or greater than 0 if the message was sent successfully.
Since:
All AES versions.
See also:
mt_appl_read(), mt_shel_write()
As of AES version 1.40, desk accessories may send MN_SELECTED messages to the desktop to trigger desktop functions.

As of AES version 4.00 you can use mt_shel_write(7,...) to 'broadcast' a message to all processes running with the exception of the AES itself, the desktop, and your own application. See mt_shel_write() for details.

It is recommended that you always send messages in 16 byte blocks using a WORD array of 8 elements as the AES does.

short mt_appl_yield short global_aes  ) 
 

forces an AES process switch.

Parameters:
global_aes global AES array
Returns:
unknown
Since:
PC-GEM (as of version 2.0), MagiC (as of version 2.0)
See also:
mt_evnt_timer()
Note:
Use mt_evnt_timer() with interval = 1L on other AES implementations.


Generated on Wed Nov 3 22:42:20 2004 for GEMLIB by  doxygen 1.3.9.1