initialization and interprocess communication More...

Macros
#define	appl_bvset(a, b) mt_appl_bvset(a,b,aes_global)

#define	appl_control(a, b, c) mt_appl_control(a,b,c,aes_global)

#define	appl_exit() mt_appl_exit(aes_global)

#define	appl_find(a) mt_appl_find(a,aes_global)

#define	appl_getinfo(a, b, c, d, e) mt_appl_getinfo(a,b,c,d,e,aes_global)

#define	appl_xgetinfo(a, b, c, d, e) mt_appl_getinfo(a,b,c,d,e,aes_global)

#define	appl_getinfo_str(a, b, c, d, e) mt_appl_getinfo_str(a,b,c,d,e,aes_global)

#define	appl_read(a, b, c) mt_appl_read(a,b,c,aes_global)

#define	appl_search(a, b, c, d) mt_appl_search(a,b,c,d,aes_global)

#define	appl_tplay(a, b, c) mt_appl_tplay(a,b,c,aes_global)

#define	appl_trecord(a, b) mt_appl_trecord(a,b,aes_global)

#define	appl_write(a, b, c) mt_appl_write(a,b,c,aes_global)

#define	appl_yield() mt_appl_yield(aes_global)

#define	appl_getcicon() mt_appl_getcicon(aes_global)

#define	appl_get_cicon(a, b, c, d, e, f) mt_appl_get_cicon(a,b,c,d,e,f, aes_global)

Functions
static short	appl_init (void)

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_getinfo_str (short type, char out1, char out2, char out3, char 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)

short	mt_appl_get_cicon (short type, const char name, short size, short cicon_width, short cicon_height, CICON cicon_data, 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.

Macro Definition Documentation

#define appl_bvset	(	a,
		b
	)	mt_appl_bvset(a,b,aes_global)

single-thread version of mt_appl_bvset()

#define appl_control	(	a,
		b,
		c
	)	mt_appl_control(a,b,c,aes_global)

single-thread version of mt_appl_control()

#define appl_exit ( ) mt_appl_exit(aes_global)

single-thread version of mt_appl_exit()

#define appl_find ( a ) mt_appl_find(a,aes_global)

single-thread version of mt_appl_find()

#define appl_get_cicon	(	a,
		b,
		c,
		d,
		e,
		f
	)	mt_appl_get_cicon(a,b,c,d,e,f, aes_global)

single-thread version of mt_appl_get_cicon()

#define appl_getcicon ( ) mt_appl_getcicon(aes_global)

single-thread version of mt_appl_getcicon()

#define appl_getinfo	(	a,
		b,
		c,
		d,
		e
	)	mt_appl_getinfo(a,b,c,d,e,aes_global)

single-thread version of mt_appl_getinfo()

#define appl_getinfo_str	(	a,
		b,
		c,
		d,
		e
	)	mt_appl_getinfo_str(a,b,c,d,e,aes_global)

single-thread version of mt_appl_getinfo_str()

#define appl_read	(	a,
		b,
		c
	)	mt_appl_read(a,b,c,aes_global)

single-thread version of mt_appl_read()

#define appl_search	(	a,
		b,
		c,
		d
	)	mt_appl_search(a,b,c,d,aes_global)

single-thread version of mt_appl_search()

#define appl_tplay	(	a,
		b,
		c
	)	mt_appl_tplay(a,b,c,aes_global)

single-thread version of mt_appl_tplay()

#define appl_trecord	(	a,
		b
	)	mt_appl_trecord(a,b,aes_global)

single-thread version of mt_appl_trecord()

#define appl_write	(	a,
		b,
		c
	)	mt_appl_write(a,b,c,aes_global)

single-thread version of mt_appl_write()

#define appl_xgetinfo	(	a,
		b,
		c,
		d,
		e
	)	mt_appl_getinfo(a,b,c,d,e,aes_global)

single-thread version of mt_appl_getinfo()

#define appl_yield ( ) mt_appl_yield(aes_global)

single-thread version of mt_appl_yield()

Function Documentation

static short appl_init ( void )

inlinestatic

single-thread version of mt_appl_init()

References aes_global, gl_ap_version, gl_apid, and mt_appl_init().

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: `APCI_HIDDEN` is set if the application is hidden `APCI_HASMBAR` is set if the application has a menu bar `APCI_HASDESK` is set if the application has a own desk
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.
APC_APP_CONFIG	With this option you are able to inform to AES how you want your application should be considered. ap_cout is a pointer to a string. At this time value supported are: `"app_debug=true"` or "app_debug" : put the application in debug mode `"app_debug=false"` : stop debug mode `"app_topmost=true"` or "app_topmost" : Application windows will be always on top (compare to other classical application) but without focus (can be usefull for tesk bar for exemple) `"app_topmost=false"` : remove previous option `"app_system"` : application is a system application (used in appl_search() for type APP_SYSTEM) `"app_texticon=opaque"` : background icon text is opaque `"app_texticon=transparent"` : background icon text is transparent `"app_signal_mesag=true"`: Request receive Unix Signal when even message is waiting see APC_INFORM_MESAG as it do exactly the same `"app_signal_mesag=false"`: Request stop receive Unix Signal when even message is waiting appl_control return 1 if the request is recognize else 0
APC_INFORM_MESAG	Request to AES to inform the application when there is a AES message waiting with a Unix Signal. ap_cout : not used. When the application receive a message the AES send the Signal SIGUSR2 (30) to the application, to manage the message should use classical event_mesag() or event_multi() functions. Calling one time this call request to AES to send Signal, calling a second time remove this order. appl_control return 1 if take into account else 0

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.

Referenced by mt_appl_getinfo(), and mt_appl_getinfo_str().

short mt_appl_get_cicon	(	short	type,
		const char *	name,
		short	size,
		short *	cicon_width,
		short *	cicon_height,
		CICON **	cicon_data,
		short *	global_aes
	)

returns information about the AES.

Parameters

type	: kind of icon type and format output
name	: name of the color icon
size	: size of icon
cicon_width	: return pixel width
cicon_height	: return pixel height
cicon_data	: return CICON block + mask + icon bitmap
global_aes	global AES array

Returns: 0 if an error occurred or non-zero otherwise.

Since: Available since MyAES 0.96 beta1

See also: mt_appl_getcicon()

some more explanation:

Description:
The goal of this function is to provide cicon server (24 bit true color for MyAES or 32 picture)
This function provide only CICON data with bitmap and mask and not a full object icon.
Data provide by this function should be relocated and copy, AES not keep in memory CICON block provided that should be copy.
type&0xFF:
0 : Application icon
1 : File extension icon
2 : Reserved
3 : Load PNG file as icon from specific path
4 : Other icon (any other specific icon)

if type&0x100 =0 cicon_data return a CICON block as need by AES for display color icon else cicon_data return a simple bitmap block in ARBG format with 8 bit transparency (this format is not recognize by AES)

name: name of the cicon to load, some exemple:
with type&0xFF:
0 : name = "purec"
1 : name = "html"
3 : name = "C:\myprog\mypng\pngname.png"
4 : name = "computer"

size Size of the cicon to load, there is 3 different case:
size > 0 is the size of the icon requested and should be a multiple of 16
size = 0 the default cicon size is requested and is set by aes configuration
size = -1 the return cicon can be of any size and can change from a cicon to another

cicon_data Return block of type CICON + mask + icon bitmap if type&0x100 = 0 else a bitmap 32 bit with alpha chanel in the format ARGB 8 bits per chanel.

Relocation of cicon_data, cicon_data provide CICON block + mask + bitmap

num_planes : number of planes
*col_data, *col_mask, *sel_data, *sel_mask: provide relative position from the start of cicon_data and should be relocated

As the block can be free by the AES you should copy the block for your need, the size of the block to copy is:

number_of_block = 0
if(cicon_data->col_data) number_of_block++;
if(cicon_data->col_mask) number_of_block++;
if(cicon_data->sel_data) number_of_block++;
if(cicon_data->sel_mask) number_of_block++;
size = sizeof(CICON) + (cicon_data->num_planes * cicon_width * cicon_height * number_of_block)/8 + cicon_width*cicon_height;

CICON *newcicon;
newcicon = malloc(size);
memcpy(newcicon,cicon_data);
if(cicon_data->col_data) newcicon->col_data += newcicon;
if(cicon_data->col_mask) newcicon->col_mask += newcicon;
if(cicon_data->sel_data) newcicon->sel_data += newcicon;
if(cicon_data->sel_mask) newcicon->sel_mask += newcicon;

WARNING : In the case of 32 bits bitmap requested size of the bloc = cicon_width * cicon_height * 4

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:
- SYSTEM_FONT (0) is the system font
- OUTLINE_FONT (1) is an outline 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 a bitmap variable:
- bit 0 (out4 & 0x0001) indicates that the extended resource file format (AES4) is supported.
- bit 1 (out4 & 0x0002) indicates that interface resource file format (RSHDR::rsh_vrsn = 3) is supported.

AES_LANGUAGE

3

AES Globalization

out1 is filled in with the current AES language code as follows:

Name	out1	Language
AESLANG_ENGLISH	0	English
AESLANG_GERMAN	1	German
AESLANG_FRENCH	2	French
(reserved)	3	(Reserved)
AESLANG_SPANISH	4	Spanish
AESLANG_ITALIAN	5	Italian
AESLANG_SWEDISH	6	Swedish

out2, out3, and out4 are unused.

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

out1 is 0 if mt_objc_xfind() is not implemented and 1 if it is.
out2 is currently reserved.
out3 is 0 if mt_menu_click() is not implemented and 1 if it is.
out4 is 0 if mt_shel_rdef() and mt_shel_wdef() are not implemented and 1 if they are.

AES_INQUIRE

6

AES Extended Inquiry Functions

out1 is 0 if -1 is not a valid ap_id parameter to mt_appl_read() or 1 if it is.
out2 is 0 if SHEL_BUFSIZE is not a valid length parameter to mt_shel_get() or 1 if it is.
out3 is 0 if -1 is not a valid mode parameter to mt_menu_bar() or 1 if it is.
out4 is 0 if MENU_INSTL is not a valid mode parameter to mt_menu_bar() or 1 if it is.

#(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	WF_WHEEL set/get.
10	WF_FIRSTAREAXYWH get.
11	WF_OPTS set/get.
12	WF_MENU set/get.
13	WF_WORKXYWH set/get (and bug-free when AES toolbar is installed)
14	mt_wind_get(WF_CALCW2F/WF_CALCF2W) and WO0_WCOWORK mode
15	mt_wind_set() and mt_wind_get() can be called with the special handle -2. Then, mt_wind_set() and mt_wind_get() invoked with this special handle report if the mode is supported by the AES. Here is an example : 1 if (wind_set(-2,WF_TOPMOST,0,0,0,0)) 2 topmost_supported = 1; 3 else 4 topmost_supported = 0; 5 // note: wind_set(-2,WF_TOPMOST,1,0,0) reports if 6 // submode '1' or WF_TOPMOST is supported or not by the AES

out2 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_WIDGETS set/get.

1-15 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-15 Unused
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	WM_REPOSED is sent.
11-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.

AES_EXTENDED

64

Extended functions

out1 is 0 if mt_shel_write() with AP_AESTERM is not supported or 1 if it is.
out2 is 0 if extended mt_shel_write() mode SWM_SHUTDOWN / SWM_REZCHANGE are not supported, or 1 if they are.
out3 is 0 if mt_appl_search() with string description is not supported, or 1 if it is.
out4 is 0 if mt_form_error() doesn't support all GEMDOS error codes, or 1 if it does.

AES_NAES

65

Additional N.AES functions

out1 is 1 if mt_appl_control() is available, or 0 otherwise.
out2 is filled with the highest Opcode for mt_appl_control()
out3 is 1 if mt_shel_help() is available, or 0 otherwise.
out4 is 1 if mt_wind_draw() is available, or 0 otherwise.

AES_VERSION

96

Additional AES functions

out1 : major version of the AES (ex: 0 for version 0.992).
out2 : minor version of the AES (ex: 992 for version 0.992).
out3 : development status. The low byte indicates the release status (0=alpha, 1=beta, 2=release). The high byte may be 1 to indicate a stable version (out3 & 0x100), or 0 otherwise.
out4 : target platform. May only be 0 (m68k) for now.

AES_WOPTS

97

return a bitmask of available WF_OPTS settings. This bitmask is identical to that use by the actual wind_set/get(WF_OPTS). See mt_wind_set() with WF_OPTS mode for details.

out1 : available window options 0
out2 : available window options 1
out3 : available window options 2
out4 : always cleared

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 ?

References mt_appl_find().

short mt_appl_getinfo_str	(	short	type,
		char *	out1,
		char *	out2,
		char *	out3,
		char *	out4,
		short *	global_aes
	)

returns information about the AES.

Parameters

type	specifies the type of information to be returned in the strings pointed to by out1, out2, out3 and out4.
out1	pointer to a string or NULL
out2	pointer to a string or NULL
out3	pointer to a string or NULL
out4	pointer to a string or 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_VERSION	96	Additional AES functions out1 : will be filled in with the identifiant of the AES. 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 ". This string is not null-terminated. out2 : will be filled with the long name of the AES. the buffer provided in out2 should take up to 256 (255 + 0 termination) characters. This buffer may contain CR (ascii 13) for change of line. For XaAES, this buffer contains "XaAES Ain't the AES, a free MultiTasking AES for FreeMiNT". out3 : will be filled with an info string that describe the AES. the buffer provided in out3 should take up to 256 (255 + 0 termination) characters. This buffer may contain CR (ascii 13) for change of line. For XaAES, this buffer contains "asci version\|development status\|architecture target\| build date & time\|compiler used" with character "\|" (ascii 0x7c) as delimiter. An example of string : "0.992\|Alpha\|m68k\|Dec 17 2004 22:58:52\|gcc 2.95.3".

Note: If mt_appl_getinfo_str() 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 ?

References mt_appl_find().

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-9	Reserved
(reserved)	10	Number of planes of the VDI workstation opened by the AES (used by BubbleGEM)
(reserved)	11-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()

Referenced by appl_init().

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: APP_SYSTEM (0x01) System process APP_APPLICATION (0x02) Application APP_ACCESSORY (0x04) Accessory APP_SHELL (0x08) [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).

Note

This function may be used to obtan other values if the AES support it. The availability of this extension is given by mt_appl_getinfo() with AES_EXTENDED mode. This extension is used by putting an AES-ID (with the minus sign) as mode parameter. Then :

fname will contain a description of the application (previoulsy registered by the application by calling mt_menu_register())
type meaning is unchanged.
ap_id will contain the process ID given by MiNT.

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.

Macros

Functions

Detailed Description

Macro Definition Documentation

Function Documentation