Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function determines whether the dynamic-link library (DLL) that implements this function is in use. If it is not, the caller can safely unload the DLL from memory.

Note:
OLE does not provide this function. DLLs that support the OLE Component Object Model (COM) should implement and export DllCanUnloadNow.

Syntax

STDAPI DllCanUnloadNow(void);

Parameters

None.

Return Value

Value Description

S_OK

The DLL can be unloaded.

S_FALSE

The DLL cannot be unloaded now.

Remarks

A call to DllCanUnloadNowdetermines whether the DLL from which it is exported is still in use. A DLL is no longer in use when it is not managing any existing objects, that is, when the reference count on all of its objects is zero.

Notes to Callers

You should not have to call DllCanUnloadNowdirectly. OLE calls it only through a call to the CoFreeUnusedLibrariesfunction. When it returns S_OK, CoFreeUnusedLibrariessafely frees the DLL.

Notes to Implementers

You need to implement DllCanUnloadNowin, and export it from, DLLs that are to be dynamically loaded through a call to the CoGetClassObjectfunction. You also need to implement and export the DllGetClassObjectfunction in the same DLL.

If a DLL loaded through a call to CoGetClassObjectfails to export DllCanUnloadNow, the DLL will not be unloaded until the application calls the CoUninitializefunction to release the OLE libraries.

If the DLL links to another DLL and DllCanUnloadNowreturns S_OK, the primary and the dependent DLL will be unloaded. To eliminate the possibility of a crash, the primary DLL should call the CoLoadLibraryfunction, specifying the path to the second DLL as the first parameter and setting the auto free parameter to TRUE. This forces the COM library to reload the second DLL and set it up for a call to CoFreeUnusedLibrariesto free it separately when appropriate.

DllCanUnloadNowshould return S_FALSE if there are any existing references to objects that the DLL manages.

To determine whether the platform supports this function, see Determining Supported COM APIs.

Requirements

Header objbase.h
Library oleaut32.lib
Windows Embedded CE Windows CE 2.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also