Skip to content

Latest commit

 

History

History
134 lines (95 loc) · 5.65 KB

nf-libloaderapi2-queryoptionaldelayloadedapi.md

File metadata and controls

134 lines (95 loc) · 5.65 KB
Raw
UID title description helpviewer_keywords old-location tech.root ms.assetid ms.date ms.keywords req.header req.include-header req.target-type req.target-min-winverclnt req.target-min-winversvr req.kmdf-ver req.umdf-ver req.ddi-compliance req.unicode-ansi req.idl req.max-support req.namespace req.assembly req.type-library req.lib req.dll req.irql targetos req.typenames req.redist ms.custom f1_keywords dev_langs topic_type api_type api_location api_name
NF:libloaderapi2.QueryOptionalDelayLoadedAPI
QueryOptionalDelayLoadedAPI function (libloaderapi2.h)
Determines whether the specified function in a delay-loaded DLL is available on the system.
QueryOptionalDelayLoadedAPI
QueryOptionalDelayLoadedAPI function
base.queryoptionaldelayloadedapi
libloaderapi2/QueryOptionalDelayLoadedAPI
base\queryoptionaldelayloadedapi.htm
base
43690689-4372-48ae-ac6d-230250f05f7c
12/05/2018
QueryOptionalDelayLoadedAPI, QueryOptionalDelayLoadedAPI function, base.queryoptionaldelayloadedapi, libloaderapi2/QueryOptionalDelayLoadedAPI
libloaderapi2.h
Windows
Windows 10 [desktop apps \| UWP apps]
Windows Server 2016 [desktop apps \| UWP apps]
WindowsApp.lib
Api-ms-win-core-libraryloader-l1-1-1.dll
Windows
19H1
QueryOptionalDelayLoadedAPI
libloaderapi2/QueryOptionalDelayLoadedAPI
c++
APIRef
kbSyntax
DllExport
api-ms-win-core-libraryloader-l1-1-1.dll
kernelbase.dll
api-ms-win-core-libraryloader-l2-1-0.dll
API-MS-Win-Core-LibraryLoader-Private-L1-1-0.dll
QueryOptionalDelayLoadedAPI

QueryOptionalDelayLoadedAPI function

-description

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

-parameters

-param hParentModule [in]

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).

-param lpDllName [in]

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.

-param lpProcName [in]

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

-param Reserved

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

-returns

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;
}

-see-also

LoadPackagedLibrary

Run-Time Dynamic Linking