OS shared libraries API

Following API should be used in MS Windows dynamic-link libraries (.dll files) and Linux shared objects (.so files) accessed by %launchExt macro language command (in case of dll libraries it is also possible to use %launchDLL).

Implmenetation node:Interface between PE and external library is made through stub library, which is implemented for both MS Windows and Linux platform as part of PE in Eclipse. This library manages sub-layer between Java environment and OS environment using Java Native Interface.

PE is supporting two C language function calling conventions: "regparm" and "stdcall". Distinction between them is determined by _STD suffix in library function name, which usage is obligatory for functions implemented with stdcall convention. However, there is no explicit specification of used calling convention in %launchDLL/%launchExt command and library is searched in following sequence:

1. Function <function-name> is searched as first.
2. If <function-name> is not found, <function-name>_STD is searched.

This means that:

• every external library function has to have an unique name - _STD suffix can't be used to differentiate two functions names,
• name of function implementing stdcall convention have to end with _STD suffix and
• name of function implementing regparm convention can not end with _STD suffix.

Functions declaration:

char * __stdcall <function-name>_STD (const char *params, char 
  **macroCmds, char **defineSymbols);
  
 char * __regparm(3) <function-name> (const char *params, char 
  **macroCmds, char **defineSymbols);  

params - string containing parameters passed to the function

macroCmds - pointer to string used to pass PE macro language commands from function. After processing %launchExt/%launchDll command, it can be processed additional macro commands from macroCmds content. Multiple commands stored in macroCmds has to be separated with \n or \r\n sequence. See Macro commands topic for list of supported macro commands.

defineSymbol - pointer to string - deprecated, used only for backward compatibility

returns - string with lines directly sent to the output of the script

This is the basic declaration of API which should be used. Particular declaration used in external library implementation may differ depending on compiler used to build the shared library ( .DLL/ .SO) - supported attribute declaration may slightly differ.

char local_buffer[1000];
char* __attribute__((stdcall)) returnInputSTD_STD (char *params, char 
**MacroCmds, char **DefineSymbols)
{ 
    sprintf(local_buffer, params);

    *MacroCmds = local_buffer;

    return local_buffer;
}
char* __attribute__((regparm(3))) returnInput (char *params, char 
**MacroCmds, char **DefineSymbols)
{ 
    sprintf(local_buffer, params);
    *MacroCmds = local_buffer;
    return local_buffer;
}

Example of functions just returning string passed in params input parameter is showed above using GCC attribute declaration, one using " regparm" calling convention and one using " stdcall" convention.

Next example shows possible declaration of same functions when using Microsoft

 __declspec (dllexport) keyword used to export these functions:
__declspec (dllexport) char* __attribute__((stdcall)) 
returnInputSTD_STD (char *params, char **MacroCmds, char 
**DefineSymbols)
{ 
    sprintf(local_buffer, params);
    *MacroCmds = local_buffer;
    return local_buffer;
}
__declspec (dllexport) char* __attribute__((regparm(3))) returnInput 
(char *params, char **MacroCmds, char **DefineSymbols)
{ 
    sprintf(local_buffer, params);
    *MacroCmds = local_buffer;
    return local_buffer;
}