QueryOptionalDelayLoadedAPI function (libloaderapi2.h)

Article
10/09/2023

Determines whether the specified function in a delay-loaded DLL is available on the system.

Syntax

BOOL QueryOptionalDelayLoadedAPI(
  [in] HMODULE hParentModule,
  [in] LPCSTR  lpDllName,
  [in] LPCSTR  lpProcName,
       DWORD   Reserved
);

Parameters

[in] hParentModule

A handle to the calling module. Desktop applications can use the GetModuleHandle or GetModuleHandleEx function to get this handle. Windows Store apps should set this parameter to static_cast<HMODULE>(&__ImageBase).

[in] lpDllName

The file name of the delay-loaded DLL that exports the specified function. This parameter is case-insensitive.

Windows Store apps should specify API sets, rather than monolithic DLLs. For example, api-ms-win-core-memory-l1-1-1.dll, rather than kernel32.dll.

[in] lpProcName

The name of the function to query. This parameter is case-sensitive.

Reserved

This parameter is reserved and must be zero (0).

Return value

TRUE if the specified function is available on the system. If the specified function is not available on the system, this function returns FALSE. To get extended error information, call GetLastError.

Remarks

A delay-loaded DLL is statically linked but not actually loaded into memory until the running application references a symbol exported by that DLL. Applications often delay load DLLs that contain functions the application might call only rarely or not at all, because the DLL is only loaded when it is needed instead of being loaded at application startup like other statically linked DLLs. This helps improve application performance, especially during initialization. A delay-load DLL is specified at link time with the /DELAYLOAD (Delay Load Import) linker option.

Applications that target multiple versions of Windows or multiple Windows device families also rely on delay-loaded DLLs to make visible extra features when they are available.

A desktop application can use delayed loading as an alternative to runtime dynamic linking that uses LoadLibrary or LoadLibraryEx to load a DLL and GetProcAddress to get a pointer to a function. A Windows Store app cannot use LoadLibrary or LoadLibraryEx, so to get the benefits to runtime dynamic linking, a Windows Store app must use the delayed loading mechanism.

To check whether a function in a delay-loaded DLL is available on the system, the application calls QueryOptionalDelayLoadedAPI with the specified function. If QueryOptionalDelayLoadedAPI succeeds, the application can safely call the specified function.

Examples

The following example shows how to use QueryOptionalDelayLoadedAPI to determine whether the MkParseDisplayName function is available on the system.

#include <windows.h>
#include <libloaderapi2.h>

// For this example, you need to pass
// /delayload: ext-ms-win-com-ole32-l1-1-1.dll to link.exe.

EXTERN_C IMAGE_DOS_HEADER __ImageBase;

BOOL
AreMonikersSupported ()
{

    BOOL isApiAvailable;

    // Check if MkParseDisplayName is available on the system. It is only
    // available on desktop computers, and not on mobile devices or Xbox.

    isApiAvailable = 
        QueryOptionalDelayLoadedAPI(static_cast<HMODULE>(&__ImageBase),
                                    "ext-ms-win-com-ole32-l1-1-1.dll",
                                    "MkParseDisplayName",
                                    0);

    return isApiAvailable;
}

Requirements

Requirement	Value
Minimum supported client	Windows 10 [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2016 [desktop apps \| UWP apps]
Target Platform	Windows
Header	libloaderapi2.h
Library	WindowsApp.lib
DLL	Api-ms-win-core-libraryloader-l1-1-1.dll

Share via