|
Using DLL's and the Windows API |
Top Previous Next |
|
Emergence BASIC supports using external DLL's to extend the capabilities of the language through the use of import libraries. An import library is a special .LIB file that contains the names and entry points of all of the functions contained within a particular DLL. The Windows API is a collection of functions in system DLL's located in either the windows\system or windows\system32 directory. EBASIC includes import libraries for many of the standard Windows API DLL's. All import libraries are located in the libs directory in the main installation directory for Emergence BASIC.. See the list at the end of the topic. An include file containing declares, types and constants for much of the Windows API is included with your installation. All Win API function names are aliased with a leading underscore and to remove the 'A' on ANSI function names. Example: $INCLUDE "windows.inc" Creating import libraries To create an import library for a DLL select the Tools menu and select Create Import Library. Browse to the DLL you wish to use in your programs and click on the Open button. The new import library will have a .lib extension with the same name as the DLL and will be copied automatically to the libs directory. You only need to do this once for a new DLL. Once the import library is added you can use it in any program. Including the import library in the build After successfully creating an import library for a DLL you need to tell the Emergence BASIC Linker that you wish to include it when compiling programs. Use the $USE preprocessor command to include linker and import libraries. $USE "mydll.lib" You may also specify a full path name. $USE "c:\\mylibs\\mydll.lib" You do not need to use the $USE command to access any of the functions available in the default Windows API DLL's. The linker automatically includes the import libraries for the DLL's listed at the end of the topic. Calling functions in the DLL To use a function in a DLL it must first be declared using the IMPORT keyword. The IMPORT keyword tells the compiler that the function is located in either a DLL or import library. DECLARE IMPORT, GetSysColor(nIndex as INT),UINT Note the comma in the DECLARE statement. You can alias function names to resolve naming conflicts or to declare the same function more than once with different parameter types. DECLARE IMPORT, GetColor ALIAS GetSysColor(nIndex as INT),UINT Functions that use the C calling convention will usually be noted in the documentation for the DLL and can be used by including the CDECL keyword. The Windows API function wsprintf uses the C calling convention. DECLARE CDECL IMPORT, wsprintfA(buf as STRING, format as STRING, ... ), INT Calling functions in the C runtime library The C runtime DLL uses the import library crtdll.lib. However it is linked differently from other import libraries. To use the functions contained within the C runtime DLL use the EXTERN keyword instead of the IMPORT keyword. DECLARE CDECL EXTERN _sprintf(buf as STRING, format as STRING, ...),INT All functions in the C runtime library require the CDECL keyword and usually begin with an underscore. Calling functions with C name mangling Certain C and C++ compilers create DLL's with what's known as mangled function names. The format of the mangling varies from compiler to compiler but is generally the function name with a beginning underscore and a trailing @ symbol with a number. The number is used by other linkers to determine how many parameters are pushed on the stack. The DLL's creator can map the function names to normal ones but in most cases the name mapping is not done. To use DLL functions with mangled function names you must use the EXTERN keyword instead of the IMPORT keyword. For example if a C DLL was created with a function named INIT_the_system(bInit as INT),INT then the actual name exported in the DLL would be: _INIT_the_system@4 The correct DECLARE would look like: DECLARE EXTERN _INIT_the_system@4(bInit as INT),INT Import libraries included with Emergence BASIC as of Version 1.5 kernel32.lib user32.lib gdi32.lib comdlg32.lib comctrl32.lib shell32.lib winmm.lib ole32.lib olepro32.lib oleaut32.lib winspool.lib shlwapi.lib uuid.lib ddraw.lib dinput.lib advapi32.lib crtdll.lib dinput.lib The list of import libraries included with the distribution is subject to change. To be sure check the contents of the libs directory. Other import libraries internal to the use of the compiler are not listed here. |