20.4.2 Importing the Library Function

There are three ways an application can import dynamic-link library functions:

Import implicitly at link time

Import explicitly at link time

Import dynamically at run time

In each case, dynamic-link information contained in the application identifies the name of the library and the function name or function's ordinal entry value. The implicit import is the most commonly used method.

20.4.2.1 Implicit Link-Time Import

An implicit import is performed by listing the import library for the dynamic-link library on the linker command line for an application. You create the import library by using IMPLIB, as discussed in Section 20.3.3, “Creating the Makefile.”

The SDK contains a set of import libraries to allow linking to Windows DLLs. The following table lists these files and the purpose of each.

20.4.2.2 Explicit Link-Time Import

Like an implicit import, an explicit import is performed at link time. You perform an explicit import by listing each function in the IMPORTS section of the application's module-definition file. In the following example, there are three parts: the imported function name (MinRoutine), the dynamic-link library name (MinDLL), and the ordinal entry value of the function in the library (1).

IMPORTS
   MinRoutine=MinDLL.1

Due to performance and size considerations, it is strongly advised that application developers define ordinal entry values for all exported dynamic-link library functions. If you do not assign an ordinal entry value, however, you perform the explicit import as in the following example:

IMPORTS
   MinDLL.MinRoutine

20.4.2.3 Dynamic Run-Time Import

For dynamic run-time imports, the application must first load the library and explicitly ask for the address of the necessary function. After this is done, the application can call the function. In the following example, an application links dynamically with the CreateInfo function in the Windows library INFO.DLL.

HINSTANCE hLibrary;
FARPROC lpFunc;

hLibrary = LoadLibrary("INFO.DLL");
if (hLibrary >= 32) {
    lpFunc = GetProcAddress(hLibrary, "CreateInfo");

    if (lpFunc != (FARPROC) NULL)
        (*lpFunc) ((LPSTR) Buffer, 512);

    FreeLibrary(hLibrary);
    }

In this example, the LoadLibrary function loads the necessary Windows library and returns a module handle of it. The GetProcAddress function retrieves the address of the CreateInfo function by using the function's name, CreateInfo. The function address can then be used to call the function. The following statement is an indirect function call that passes two arguments (Buffer and the integer 512) to the function:

*(lpFunc) ((LPSTR) Buffer, 512);

Finally, the FreeLibrary function decrements (decreases by 1) the library's usage count. When the usage count becomes zero (that is, when no application is using the library), the library is removed from memory.

You could gain slightly better performance if the CreateInfo function had an ordinal value assigned in the library's module-definition file. Following is an example of such a .DEF file entry:

EXPORTS
    CreateInfo @27

This statement defines the ordinal value of CreateInfo as 27. Using this value involves changing the call to the GetProcAddress function to the following:

GetProcAddress(hLibrary, MAKEINTRESOURCE(27));