WinDom: AV-protocol Library

- Main Page
- Modules
- Data Structures
- Files
- Related Pages

# AV-protocol Library
[Reference documentation]

Group of functions devoted to handle efficiently the AV protocol. More...

## Defines
#define | mt_AvStrfmt(a, b, c) AvStrfmt(b,c)
| see AvStrfmt()
## Functions
int | mt_AvInit (APPvar *app, char *name, int status, long idle)
| Initialize the AV protocol.
void | mt_AvExit (APPvar *app)
| close an AV session opened with AvInit()
INT16 * | mt_AvStatus (APPvar *app)
| returns features supported by AV server.
char * | mt_AvServer (APPvar *app)
| returns the name of the AV server
int | mt_AvWaitfor (APPvar *app, int, INT16 *, long)
| Wait for a given message.
char * | AvStrfmt (int mode, char *src)
| Quote or unquote filenames (utility for VA-protocol, Drag 'n drop, .

## Detailed Description

Group of functions devoted to handle efficiently the AV protocol.

## Define Documentation

#define mt_AvStrfmt | ( | a,
|  | b,
|  | c |  | ) | AvStrfmt(b,c)

| see AvStrfmt()

## Function Documentation

char* AvStrfmt | ( | int | mode,
|  | char * | src
| ) |

  | Quote or unquote filenames (utility for VA-protocol, Drag 'n drop, . ..) Parameters:
  | mode | action to perform : 1 to UNQUOTE the filenames (if needed), 0 to QUOTE the filename (if needed),
  | src | string that contains the filename(s). This string will not be modified.
Returns: a string that contains src with filenames unquoted, or filemane quoted (depending of mode value). This string is allocated using the standard malloc() function and should be released after use. With some modern filesystems, the filename can contain space characters. In this case, the AV protocol ask to ''quote'' a filename, i.e. quote characters are added at the beginning and the end of the filename. So, it is very important to use this function all the time when you send or received AV request with filename parameters. Please note, some desktops use the quoting filename with drag'n drop and argv protocol. QUOTING: if "src" contains at least one space character " ", quotes will be add at the begin and at the end of the string.
      ex:  [filename\0]   --> [filename\0]  (no changed)
      ex:  [filename with spaces\0] --> ['filename with spaces'\0]
UNQUOTING: the returned string will contain the filenames without quotes. The NULL character is used to separate filenames. 2 successives NULL-char are used to end the list
      ex:  [filename1 'file name 2' filename3] --> [filename1\0file name 2\0filename3\0\0]

void mt_AvExit | ( | APPvar * | app | ) |

  | close an AV session opened with AvInit() Parameters:
  | app | application descriptor.
Before terminate a client, the AV session must be absolutely closed with this function otherwise, the AV server will be confused. See also: mt_AvInit()

int mt_AvInit | ( | APPvar * | app,
|  | char * | name,
|  | int | status,
|  | long | idle
| ) |

  | Initialize the AV protocol. Parameters:
  | app | application descriptor
  | name | name of the client application (normaly, our application) in AES format (a 8-capitalized character eventually completed with space character),
  | status | bitfield defining the supported features by the client application: A_SETSTATUS (0x1) : client supports the VA_SETSTATUS message A_START (0x2) : client supports the VA_START message A_STARTED (0x4) : client supports the AV_STARTED message A_FONTCHANGED (0x8) : client supports the VA_FONTCHANGED message A_QUOTE (0x10): filename parameter are eventually quoted A_PATH_UPDATE (0x20) : client supports the VA_PATH_UPDATE message
  | idle | timeout for the server reply (units: ms). the value "1000" is a good choice.
Returns: AES id of the AV server or error code : -1 : server not found, -2 : server doesn't not supporte AV protocol. This function initializes an AV session between the client and the AV server and waits for the server's answer. Use mt_AvStatus() function to know the actions supported by the server. An AV session should be closed by calling mt_AvExit() before application termination. To identifiate the AV server, mt_AvInit() uses the environ variable AVSERVER. If this variable is not defined, AvInit() tries the following processes: 'AVSERVER', 'THING', 'GEMINI' then the desktop application. mt_AvInit() declares to the server the actions supported by the client (our application). The AV client states table displayed below gives the differents possible value. Among these values, the A_QUOTE value is very important. It means that the client supportes quoted filename : when a filename contains a space character, the complete string is surrounded by a quote character. For example, the string "The World" is quoted: "'The World'". Use mt_AvStrfmt() function to quote or unquote the strings. On return, mt_AvInit() returns the AV server AES pid (or negative error) and app->avid contains this pid. See also: mt_AvExit(), mt_Status(), mt_AvStrfmt()

char* mt_AvServer | ( | APPvar * | app | ) |

  | returns the name of the AV server Parameters:
  | app | application descriptor,
Returns: name of the AV server (in AES format). This function returns the name of the AV server if the AV session was succesfully opened with the mt_AvInit() function. The AV server GEM identifier is given by the variable app->avid. See also: mt_AvInit(), mt_AvStatus()

INT16* mt_AvStatus | ( | APPvar * | app | ) |

  | returns features supported by AV server. Parameters:
  | app | application descriptor
Returns: an array of 3 integers describing features supported by the AV server. Each element is a bitfield, each bit set to indicates a feature supported by the server. The first element may have the following bits : V_SENDKEY (0x1) : AV_SENDKEY message is supported V_ASKFILEFONT (0x2) : AV_ASKFILEFONT is message supported V_ASKCONFONT (0x4) : AV_ASKCONFONT is message supported V_ASKOBJECT (0x8) : AV_ASKOBJECT message supported V_OPENWIND (0x10) : V_STARTPROG (0x20) : V_ACCWINDOPEN (0x40) : V_STATUS (0x80) : V_COPY_DRAGGED (0x100) : V_PATH_UPDATE (0x200) : V_EXIT (0x400) : V_XWIND (0x800) : V_FONTCHANGED (0x1000) : V_STARTED (0x2000) : V_QUOTE (0x4000) : quoted filename supported V_FILEINFO (0x8000) : The second element may have the following bits : V_COPYFILE (0x1) : V_DELFILE (0x2) : V_VIEW (0x4) : V_SETWINDPOS (0x8) : The third element is currently not used. This function returns the actions supported by the AV server, if the AV session was succefully opened with the my_AvInit() function. mt_AvStatus() returns a pointer to a 3-integer array. Each value of this array is a bit field whose the values are listed below.

int mt_AvWaitfor | ( | APPvar * | app,
|  | int | msg,
|  | INT16 * | buf,
|  | long | idle
| ) |

  | Wait for a given message. Parameters:
  | app | application descriptor
  | msg | message to wait for,
  | buf | 8-word buffer,
  | idle | time idle,
Returns: 1 if the message is received, 0 otherwise. AvWaitfor() waits for a specific message MU_MESAG event. Typically, it is the answer of an AV request sent to the AV server. If other messages occur, these messages are not lost but are resent to the application. When the message is received, buf parameter contains the AES buffer message. Importante remark : AvWaitfor() does not make use of EvntWindom(), just evnt_multi(). Example :
          // ask to server to launch an application and wait the answer
          int exec_prog( char *prg, char *cmd) {
            ApplWrite( app.avid, AV_STARTPROG, prg, cmd, 0);
    	return AvWaitfor( VA_PROGSTARTED, evnt.buf, 1000);
          }