15.1 AV protocol

The AV protocol (Accessory-Venus) was developed by Stefan Eissing and used for the first time in the alternative desktop Gemini. Since then however this protocol has been supported in many further shells (Ease, Jinnee, MagXDesk, Thing, ...).

This section describes the version of the protocol from the Gemini distribution of 29th January 1995 (Gemini 1.a). All references to 'Venus' in the following can be substituted with 'Client' or 'Server' as appropriate when using other shells.

The communication between two processes takes place with AV protocol via the exchange of (extended) AES messages, which can be allocated to one of the following categories:

AV functions (Client -> Server)
VA functions (Server -> Client)

Warning: Here one must point out that with a view to future operating system versions, memory blocks used for communication between various programs, or allocated via pointers, have to be global (Mxalloc function with Global flag set). Otherwise memory protection violations would arise on computers with PMMU (e.g. Atari TT030 or Falcon030).

If paths or filenames are to be included in messages, then one must always quote the absolute path (i.e. including the drive) and the drive letters must be in upper case. Paths should always end with a backslash!

With an AV_PROTOKOLL call, each application can inquire which messages are unnderstood (not all shells support the complete protocol). It would be nice if other programs too would react to this protocol. At least AV_SENDKEY is certainly easy to implement and is the only method by which keypresses can be simulated via messages.

Under normal TOS, a desk accessory that has received an AC_CLOSE message from the AES inquires of the application (with ID) 0 via AV_PROTOKOLL whether it has understood this. In a multitasking environment (MultiTOS, MiNT/N.AES or MagiC) the program need no longer have the ID 0; besides, there will be (hardly) any AC_CLOSE messages any more. In addition, not just desk accessories but also normal programs will want to communicate with the AV-Server. So what do we do?

If more than one main application can exist, then the program or the desk accessory should try to extablish contact with GEMINI. After all, the ID can be obtained with appl_find. If this fails, then one can still search for AVSERVER or the contents of the (AES) nnvironmental variable AVSERVER. The latter possibility in particular permits easy configuration from the outside. The new versions of the library VAFUNC by Stephan Gerle (available in well-sorted mailboxes) proceed in almost the same way.

15.1.1 Quoting in AV protocol

Quoting in AV protocol means that filenames can optionally be enclosed in single quote-marks (e.g. 'name'). However, this is permitted only if both parties (Server and Client) are of the same mind, i.e. both understand it.

So why should one want to do this and how does it work? Let us assume that the Server sends a filename to the application which contains a space. An application that does not understand quoting will take this as two filenames having been passed instead of one, since normally spaces are used to separate filenames. But if the application does understand quoting (bit 4 in its protocol status is set), then the Server will enclose the filename with '' and the application will recognize that the space belongs to the filename. The same applies for filenames that are sent by an application to a Server, of course.

The question remains of how one sends single quote-marks. Well, such characters forming part of the filename are simply doubled up. So, for instance, Zorro's hypertext will be passed as 'Zorro''s hypertext'. So in such cases the same method is used as for the Drag&Drop protocol.

15.1.2 AV functions

These messages are sent by an application to Gemini or a present AV-Server:

• AV_ACCWINDCLOSED	Application has closed a window
• AV_ACCWINDOPEN	Application has opened a window
• AV_ASKCONFONT	Obtain the font for the console
• AV_ASKFILEFONT	Obtain the font for filenames
• AV_ASKOBJECT	Obtain the currently selected object
• AV_COPY_DRAGGED	Provide information about a copy action
• AV_COPYFILE	Copy/move files or folders
• AV_DELFILE	Delete files or folders
• AV_DRAG_ON_WINDOW	Provide information about moved objects
• AV_EXIT	Unlink from the AV protocol
• AV_FILEINFO	Display file or folder information
• AV_GETSTATUS	Obtain current status
• AV_OPENCONSOLE	Open the console window
• AV_OPENWIND	Open a file window
• AV_PATH_UPDATE	Contents of a directory was altered
• AV_PROTOKOLL	Provide information about supported messages
• AV_SENDCLICK	Send mouse event
• AV_SENDKEY	Send keyboard event
• AV_SETWINDPOS	Set position for directory window
• AV_STARTED	Reply to a VA_START message
• AV_STARTPROG	Start an application or file
• AV_STATUS	Set current status
• AV_VIEW	Load a viewer for a given filetype
• AV_WHAT_IZIT	Information about position on the screen
• AV_XWIND	Open a file windnow

15.1.2.1 AV_ACCWINDCLOSED

Name:

»AV_ACCWINDCLOSED«

Number:

0x4726

Description:

An application informs the AV-Server that a window has been closed. This is only necessary if it closed the window itself. If the window is closed due to an AC_CLOSE message, the Server knows that all windows are closed.

Parameter	Meaning
WORD 3	AES handle of the window

Group:

AV functions

See also:

AV_ACCWINDOPEN AV protocol

15.1.2.2 AV_ACCWINDOPEN

Name:

»AV_ACCWINDOPEN«

Number:

0x4724

Description:

This message can be used by an application to inform the AV-Server about its own (opened) window.

Parameter	Meaning
WORD 3	AES handle of the opened window

Group:

AV functions

See also:

AV_ACCWINDCLOSED AV protocol

15.1.2.3 AV_ASKCONFONT

Name:	»AV_ASKCONFONT«
Number:	0x4714
Description:	With this message an application asks the AV-Server for the font currently set for the console window.
Group:	AV functions
See also:	AV_ASKFILEFONT VA_CONFONT VA_FILEFONT AV protocol

15.1.2.4 AV_ASKFILEFONT

Name:	»AV_ASKFILEFONT«
Number:	0x4712
Description:	Using this message the Client can request the current font used for filenames in directory windows.
Group:	AV functions
See also:	AV_ASKCONFONT VA_CONFONT VA_FILEFONT AV protocol

15.1.2.5 AV_ASKOBJECT

Name:	»AV_ASKOBJECT«
Number:	0x4716
Description:	Ask about the currently selected object(s). The name(s) of the selected object(s) is (are) returned. If no object is selected, the string is empty. If several objects are selected, their names are separated by spaces.
Group:	AV functions
See also:	VA_OBJECT AV protocol

15.1.2.6 AV_COPY_DRAGGED

Name:

»AV_COPY_DRAGGED«

Number:

0x4728

Description:

An application tells the AV-Server that the objects that have been dragged to its window should be copied. This may be the case, e.g. if objects are dragged to the TreeView window.

Parameter	Meaning
WORD 3	The keyboard state ([Alternate], [Control], [Shift])
WORD 4+5	Pointer to a string which must contain the name of the destination object This HAS to be a pathname!

This message may only be used as reply to a VA_DRAGACCWIND message.

Group:

AV functions

See also:

VA_DRAGACCWIND AV protocol

15.1.2.7 AV_COPYFILE

Name:

»AV_COPYFILE«

Number:

0x4755

Description:

This command directs the AV-Server to copy or move certain file(s) or folder(s).

Parameter	Meaning
WORD 3+4	Pointer to the source file/s and folder/s
WORD 5+6	Pointer to the destination folder
WORD 7	Various flags:
	Bit 0 = Delete original (= move)
	Bit 1 = Rename copy
	Bit 2 = Overwrite destination without comment
	Bit 3 = Only create symbolic links of
	sources (bit 0 in that case
	has no meaning)
	Bit 4-15 = Reserved, always 0

Note: All further bits are reserved for future purposes.

Multiple files must be separated by space characters. Folders must include a trailing backslash '\' character!

Group:

AV functions

See also:

VA_FILECOPIED AV protocol

15.1.2.8 AV_DELFILE

Name:

»AV_DELFILE«

Number:

0x4757

Description:

This command directs the AV-Server to delete certain file(s) or folder(s).

Parameter	Meaning
WORD 3+4	Pointer to the file(s)/folder(s) to be deleted
WORD 5-7	Reserved, always 0

Multiple files or folders must be separated by space characters. Folders must include a trailing backslash '\' character!

Group:

AV functions

See also:

VA_FILEDELETED AV protocol

15.1.2.9 AV_DRAG_ON_WINDOW

Name:

»AV_DRAG_ON_WINDOW«

Number:

0x4734

Description:

An application tells the AV-Server that objects have been dragged onto one of its windows inquired for with AV_WHATIZIT.

Parameter	Meaning
WORD 3	X-position to which the mouse was dragged
WORD 4	Y-position to which the mouse was dragged
WORD 5	Keyboard state ([Alternate], [Control], [Shift])
WORD 6+7	Pointer to a string that contain the names of the objects

The names are the names of files, folders or drives; multiple names are separated by a space character. Names of folders or drives must include a trailing backslash '\' character!

Group:

AV functions

15.1.2.10 AV_EXIT

Name:

»AV_EXIT«

Number:

0x4736

Description:

An application tells the AV-Server that it doesn't link into the protocol any longer.

Parameter	Meaning
WORD 3	AES id of the application

This message must be used, before terminating a program if the program did use AV_PROTOKOLL!

Group:

AV functions

See also:

appl_init AV protocol

15.1.2.11 AV_FILEINFO

Name:

»AV_FILEINFO«

Number:

0x4753

Description:

This command directs the AV-Server to display an information dialog for a given file or folder.

Parameter	Meaning
WORD 3+4	Pointer to file or folder name
WORD 5-7	Reserved, always 0

Multiple files/folders may be separated using space characters. Folders must include a trailing backslash '\' character!

Group:

AV functions

See also:

VA_FILECHANGED AV protocol

15.1.2.12 AV_GETSTATUS

Name:	»AV_GETSTATUS«
Number:	0x4703
Description:	An accessory asks Venus for the current status that it has given to Venus via the AV_STATUS message.
Group:	AV functions
See also:	AV_STATUS AV protocol

15.1.2.13 AV_OPENCONSOLE

Name:	»AV_OPENCONSOLE«
Number:	0x4718
Description:	Venus should open the console window. If it is open already, it will be topped. This action is of use if a desk accessory is about to launch a TOS program using the system function. Note: No GEM programs should be started by an accessory via the system function! The message should only be used if the user explicitly wants to, as otherwise it can quickly lead to confusion. This message is only available in Gemini at present.
Group:	AV functions
See also:	AV_OPENWIND AV_XWIND VA_CONSOLEOPEN VA_XOPEN VA_WINDOPEN AV_STARTPROG

15.1.2.14 AV_OPENWIND

Name:

»AV_OPENWIND«

Number:

0x4720

Description:

An application directs the AV-Server to open a file window.

Parameter	Meaning
WORD 3+4	Pointer to the path for the window
WORD 5+6	Pointer to a string containing the wildcards for the files which should be displayed

Note: This message should only be used when the reason is clearly evident to the user.

Group:

AV functions

15.1.2.15 AV_PATH_UPDATE

Name:

»AV_PATH_UPDATE«

Number:

0x4730

Description:

A program/accessory tells the AV-Server that the contents of a folder has been changed. The AV-Server redraws this folder if it is displayed in a window, even if subdirectories are shown.

Parameter	Meaning
WORD 3+4	Pointer to the complete (!) pathname

The update of "C:\" for example results in redisplaying everything on drive C:.

Group:

AV functions

See also:

AV_OPENWIND AV_XWIND AV protocol

15.1.2.16 AV_PROTOKOLL

Name:

»AV_PROTOKOLL«

Number:

0x4700

Description:

This message should be used to ask an application or the AV-Server whether or which messages are supported.

Parameter	Meaning
WORD 3	Bit 0 = VA_SETSTATUS
	Bit 1 = VA_START
	Bit 2 = AV_STARTED
	Bit 3 = VA_FONTCHANGED
	Bit 4 = Provides & uses filename quoting
	Bit 5 = VA_PATH_UPDATE
	Bit 6-15 = Reserved, always 0
WORD 4+5	Reserved, always 0
WORD 6+7	A pointer to the name of the desk
	accessory/application for use with
	appl_find (aligned to 8 characters
	and terminated by a '\0' byte).

Group:

AV functions

See also:

AV_STARTED VA_FONTCHANGED VA_SETSTATUS VA_START

15.1.2.17 AV_SENDCLICK

Name:

»AV_SENDCLICK«

Number:

0x4709

Description:

An application sends a mouse event to the AV-Server.

Parameter	Meaning
WORD 3	ev_mmox
WORD 4	ev_mmoy
WORD 5	ev_mmobutton
WORD 6	ev_mmokstate
WORD 7	ev_mbreturn

Group:

AV functions

See also:

evnt_button evnt_multi

15.1.2.18 AV_SENDKEY

Name:

»AV_SENDKEY«

Number:

0x4710

Description:

Using this message a Client can send the AV-Server any key events it may not use for itself.

Parameter	Meaning
WORD 3	Keyboard state (ev_mmokstate)
WORD 4	Scan code of the pressed key (ev_mkreturn)

As an unofficial extension ('CodeAlpha') there is a concept that allows ASCII characters for which no scancode exists to be passed as well. For this one passes 0 for the scancode, the desired ASCII value and in msg[5] the value $5048 (the latter to indicate that msg[4] is indeed valid and that no conversion via the scancode tables is required.

This message should always be supported If possible, as with its help trans-application window cycling can be realised, for instance.

Group:

AV functions

See also:

evnt_keybd evnt_multi Scancode table

15.1.2.19 AV_SETWINDPOS

Name:

»AV_SETWINDPOS«

Number:

0x4759

Description:

With this the Client can be informed of the position and size of the next directory window to be opened by the AV-Server (with AV_XWIND or AV_OPENWIND).

Parameter	Meaning
WORD 3	X-position
WORD 4	Y-position
WORD 5	Width of window
WORD 6	Height of window
WORD 7	Reserved, always 0

The coordinates are given in absolute coordinates. If AV_XWIND tops an existing window rather than opening a new window, this message has no effect!

Group:

AV functions

See also:

AV_OPENWIND AV_XWIND

15.1.2.20 AV_STARTED

Name:

»AV_STARTED«

Number:

0x4738

Description:

A Client informs the AV-Server it has received and understood the VA_START message and the memory reserved for the command line can be released.

Parameter	Meaning
WORD 3+4	Pointer to the command line containing path or
	filename received by VA_START; can also be NULL.

To recognize which VA_START message is being dealt with, the values of VA_START are returned.

Group:

AV functions

See also:

VA_START AV protocol

15.1.2.21 AV_STARTPROG

Name:

»AV_STARTPROG«

Number:

0x4722

Description:

An application requests the AV-Server to start a program (or file).

Parameter	Meaning
WORD 3+4	Pointer to the program's name (with complete path!)
WORD 5+6	Pointer to the command line for the program (may be NULL)
WORD 7	Any 16-bit WORD, which will be returned by VA_PROGSTART

In Gemini the installed applications are also taken into account. This makes it possible to specify a file for which a program is then searched for.

Group:

AV functions

See also:

VA_PROGSTART AV protocol

15.1.2.22 AV_STATUS

Name:

»AV_STATUS«

Number:

0x4704

Description:

An accessory can give its current state to Venus, which will store it in the INF-file and can be restored using AV_GETSTATUS. Before sending AV_STATUS it must send AV_PROTOKOLL to Venus!

Parameter	Meaning
WORD 3+4	A pointer to a string, which must not contain
	any control characters and must not be longer
	than 256 characters; the pointer may be NULL

The application must first have registered itself with the Server via AV_PROTOKOLL.

Group:

AV functions

See also:

AV_GETSTATUS AV_PROTOKOLL AV protocol

15.1.2.23 AV_VIEW

Name:

»AV_VIEW«

Number:

0x4751

Description:

The AV-Server calls the viewer for a specific file.

Parameter	Meaning
WORD 3+4	Pointer to the name of the file to be displayed (only a single file is allowed!)
WORD 5	0 = Calls the viewer
	1 = Calls the editor
WORD 6-7	Reserved, always 0

Note: Only a single file may be specified. If no suitable viewer is available, an error-message will be returned to the user.

Group:

AV functions

See also:

VA_VIEWED AV protocol

15.1.2.24 AV_WHAT_IZIT

Name:

»AV_WHAT_IZIT«

Number:

0x4732

Description:

A Client requests details about what is located at a given position of the screen.

Parameter	Meaning
WORD 3	X-coordinate
WORD 4	Y-coordinate

The coordinates are the normal VDI coordinates (the origin is the left upper corner of the screen).

Group:

AV functions

See also:

VA_THAT_IZIT AV protocol

15.1.2.25 AV_XWIND

Name:

»AV_XWIND«

Number:

0x4740

Description:

Thing opens a directory window, similar to AV_OPENWIND except additional options are available:

Parameter	Meaning
WORD 3+4	Pointer to the path for opening directories
WORD 5+6	Pointer to the mask (wildcard) for the available files
WORD 7	Bit-mask:
	0x0001 = Use current top window, if available
	0x0002 = Use wildcard for object selection
	0x0004 = Continue using existing window
	All other bit must be set to zero.

Note: This message should only be used when the reason is clearly evident to the user.

Group:

AV functions

15.1.3 VA functions

These messages are sent by Gemini or other present AV-Server to an application:

• VA_ACC_QUOTING(a)	Test accessory protocol status for quoting
• VA_CONFONT	Convey font of the console
• VA_CONSOLEOPEN	Convey whether the console window is open
• VA_COPY_COMPLETE	Reply to AV_COPY
• VA_DRAGACCWIND	Objects were dragged to application's window
• VA_DRAG_COMPLETE	AV_DRAG_ON_WINDOW action is completed
• VA_FILECHANGED	Reply to AV_FILEINFO.
• VA_FILECOPIED	Reply to AV_COPYFILE.
• VA_FILEDELETED	Reply to AV_DELFILE.
• VA_FILEFONT	Convey font for file window
• VA_FONTCHANGED	A set font has been changed
• VA_OBJECT	Returns the names of the selected objects
• VA_PATH_UPDATE	Contents of a directory have changed
• VA_PROGSTART	Information about whether a program could be started
• VA_PROTOSTATUS	Reply to AV_PROTOKOLL.
• VA_SERVER_QUOTING(a)	Test Server protocol status for quoting
• VA_SETSTATUS	Convey status of an application
• VA_START	An application has been activated
• VA_THAT_IZIT	Provides information about object at screen position
• VA_VIEWED	Reply to AV_VIEW.
• VA_WINDOPEN	Conveys whether the console window is open
• VA_XOPEN	Conveys whether a window could be opened

15.1.3.1 VA_ACC_QUOTING(a)

This is a test of the protocol status of an accessory for quoting.

In C the test may be realized as a macro as follows:

#define VA_ACC_QUOTING(a)   ((a) & 0x10)

15.1.3.2 VA_CONFONT

Name:

»VA_CONFONT«

Number:

0x4715

Description:

Gives the currently selected font for the console window. Valid are:

Parameter	Meaning
WORD 3	Console font (ID)
WORD 4	Console font size (points)

Group:

Name:	»VA_WINDOPEN«
Number:	0x4721
Description:	Returns the state of the file window (see VA_CONSOLEOPEN).
Group:	VA functions
See also:	AV_OPENCONSOLE VA_CONSOLEOPEN AV protocol