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);
      }

Generated on Thu Jun 22 11:45:28 2006 for WinDom by  doxygen 1.4.6