7. Linking
There are two ways to link a DLL and import a function. Static linking is very easy and the recommended way if the DLL is certain to be available on the client's machine. If the DLL is optional it is better to use dynamic linking (runtime-linking) to make sure that the application does not fail just because of a missing (possibly unimportant) DLL.
Static linking encodes the calling of the library DLL into the code as a direct call with no checking for inability to connect to the library. Dynamic linking calls the library DLL during the application's run-time and has the capability to handle problems with connection to the library. Dynamic linking can occur at startup, or during the program run-time as the library is needed by the user.
Borland usually uses static linking, but a few API translations use dynamic linking. One example is the translation of SMAPI (MAPI.pas).
Let's look at the two ways of linking a DLL and importing a function.
7.1. Static Linking
If using static linking, simply declare the function prototype in the interface section and the implementation section the following way:
INTERFACE
{Function|Procedure} FunctionName [FunctionDeclaration;]
IMPLEMENTATION
{Function|Procedure} FunctionName external DLLName [name 'FunctionExportName'];
The translation of a function prototype was in the previous section. What about importing the function? It's not obligatory to include the parameter part of the function in the implementation section, but you can if you want. As an example to explain how to import a function, let's use the OpenEvent function from the kernel32.dll.
There are two implementations of the function, one with unicode-support (16bit-WideChar) and one with ansi-character (8bit char) support.
The C-declaration is
WINBASEAPI
HANDLE
WINAPI
OpenEventA(
DWORD dwDesiredAccess,
BOOL bInheritHandle,
LPCSTR lpName
);
WINBASEAPI
HANDLE
WINAPI
OpenEventW(
DWORD dwDesiredAccess,
BOOL bInheritHandle,
LPCWSTR lpName
);
#ifdef UNICODE
#define OpenEvent OpenEventW
#else
#define OpenEvent OpenEventA
#endif // !UNICODE
Three function names are declared: OpenEventA for the ansi-character version of the function, OpenEventW for the wide-character (unicode) version, and OpenEvent. OpenEvent uses the widechar version of the function (OpenEventW ) if the UNICODE symbol is declared or the ansichar-version OpenEventA if the UNICODE symbol is not declared.
INTERFACE
{...}
function OpenEventA (dwDesiredAccess: DWORD;
bInheritHandle: BOOL;
lpName: PAnsiChar): THandle; stdcall;
function OpenEventW (dwDesiredAccess: DWORD;
bInheritHandle: BOOL;
lpName: PWideChar): THandle; stdcall;
{$IFDEF UNICODE}
function OpenEvent (dwDesiredAccess: DWORD;
bInheritHandle: BOOL;
lpName: PWideChar): THandle; stdcall;
{$ELSE}
function OpenEvent (dwDesiredAccess: DWORD;
bInheritHandle: BOOL;
lpName: PChar): THandle; stdcall;
{$ENDIF}
{...}
IMPLEMENTATION
Const
kernel32 = 'kernel32.dll';
{...}
function OpenEventA; external kernel32 name 'OpenEventA';
function OpenEventW; external kernel32 name 'OpenEventW';
{$IFDEF UNICODE}
function OpenEvent; external kernel32 name 'OpenEventW';
{$ELSE}
function OpenEvent; external kernel32 name 'OpenEventA';
{$ENDIF}
{...}