Windows API Reference - DLL Functions

Introduction to DLLs

Dynamic Link Libraries (DLLs) are shared libraries that can be loaded by multiple programs at runtime. They contain code and data that can be used by more than one program simultaneously. This promotes code reuse and reduces the overall memory footprint of applications. The Windows operating system relies heavily on DLLs for its core functionality and for providing APIs to developers.

Key Concepts:

Import Libraries: When you link against a DLL, you typically link against an import library (.lib) that contains information about the functions exported by the DLL.
Load-Time Dynamic Linking: The operating system loads the DLL when the application starts.
Run-Time Dynamic Linking: You can explicitly load and unload DLLs using functions like LoadLibrary and FreeLibrary.
Function Export: DLLs export functions that can be called by other applications.

Common DLL-Related Functions

The following are some of the most commonly used functions for managing and interacting with DLLs:

`LoadLibrary`

Loads a specified module into the address space of the calling process.


                    HMODULE LoadLibrary(

                        LPCTSTR lpFileName

                    );

Parameters:

Name	Type	Description
`lpFileName`	`LPCTSTR`	The name of the module to be loaded.

Return Value: If the function succeeds, the return value is a module handle to the loaded module. If the function fails, the return value is NULL. To get extended error information, call GetLastError.

`GetProcAddress`

Retrieves the address of an exported function or variable from the specified dynamic-link library (DLL).


                    FARPROC GetProcAddress(

                        HMODULE hModule,

                        LPCSTR lpProcName

                    );

Parameters:

Name	Type	Description
`hModule`	`HMODULE`	A handle to the DLL module that contains the function or variable.
`lpProcName`	`LPCSTR`	The function or variable to be located. This parameter can be an ASCII string that is the name of the function or variable, or it can be an integer ordinal for the function or variable.

Return Value: If the function succeeds, the return value is the address of the exported function or variable. If the function fails, the return value is NULL. To get extended error information, call GetLastError.

`FreeLibrary`

Decrements the reference count of the loaded DLL module. When the reference count reaches zero, the module is unmapped from the address space of all processes in which it is loaded and the handle is no longer valid.


                    BOOL FreeLibrary(

                        HMODULE hModule

                    );

Parameters:

Name	Type	Description
`hModule`	`HMODULE`	A handle to the loaded DLL module to be unmapped from the process's address space.

Return Value: If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.

`GetModuleHandle`

Retrieves a module handle for the specified module. The module must have been loaded by the current process.


                    HMODULE GetModuleHandle(

                        LPCTSTR lpModuleName

                    );

Parameters:

Name	Type	Description
`lpModuleName`	`LPCTSTR`	The name of the module. If this parameter is NULL, the handle returned is for the file used to create the calling process.

Return Value: If the function succeeds, the return value is a handle to the specified module. If the function fails, the return value is NULL. To get extended error information, call GetLastError.

DLL Export Functions

DLLs export functions using specific mechanisms. Developers define which functions are exported using module definition files (.def) or by using __declspec(dllexport) in their source code.

Example: Exporting a function

Consider a simple DLL exporting a function to add two numbers:


                    // In MyMath.cpp
                    #include <windows.h>


                    extern "C" __declspec(dllexport) int AddNumbers(int a, int b) {

                        return a + b;

                    }


                    // In MyMath.def (optional, for more control)
                    LIBRARY MyMath

                    EXPORTS

                        AddNumbers @1

Calling an exported function

To call the exported AddNumbers function from an application:


                    #include <windows.h>

                    #include <iostream>


                    typedef int (*AddFunc)(int, int); // Function pointer type


                    int main() {

                        HMODULE hDll = LoadLibrary(L"MyMath.dll");

                        if (hDll) {

                            AddFunc add = (AddFunc)GetProcAddress(hDll, "AddNumbers");

                            if (add) {

                                int result = add(5, 3);

                                std::wcout << L"Result: " << result << std::endl;

                            } else {

                                std::cerr << "Could not find AddNumbers function." << std::endl;

                            }

                            FreeLibrary(hDll);

                        } else {

                            std::cerr << "Could not load MyMath.dll." << std::endl;

                        }

                        return 0;

                    }

Note: Ensure that MyMath.dll is in a location accessible by the application, such as the same directory or the system's PATH environment variable.