DllCanUnloadNow - OLE Programmer's Reference (ole.hlp)

DllCanUnloadNow

Determines whether the DLL that implements it is in use. It is called by OLE, not by the application. If the DLL is not in use, the calling function can safely unload it from memory.

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

HRESULT DllCanUnloadNow();
Return Values
S_OK

Indicates that the DLL can be unloaded.

S_FALSE

Indicates that the DLL cannot be unloaded now.

Comments
A call to DllCanUnloadNow determines 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 (the reference count on all of its objects is 0).

Notes to Callers
You should not have to call DllCanUnloadNow directly. OLE calls it only through a call to the CoFreeUnusedLibraries function. When it returns S_OK, CoFreeUnusedLibraries safely frees the DLL.

Notes to Implementors
You need to implement DllCanUnloadNow in, and export it from, DLLs that are to be dynamically loaded through a call to the CoGetClassObject function. (You also need to implement and export the DllGetClassObject function in the same DLL).

If a DLL loaded by CoGetClassObject fails to export DllCanUnloadNow, the DLL will not be unloaded until the application calls the CoUninitialize function to release the OLE libraries.

If the DLL links to another DLL, returning S_OK from DllCanUnloadNow will also cause the second, dependent DLL to be unloaded. To eliminate the possibility of a crash, the DLL should call the CoLoadLibrary function(path_to_second DLL, TRUE), which forces the COM library to reload the second DLL and set it up for a call to CoFreeUnusedLibraries to free it separately when appropriate.

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

See Also
DllGetClassObject

More Online Helps

Win32 Programmer's Reference (win32.hlp)
Win32 Multimedia Programmer's Reference (mmedia.hlp)
Microsoft Windows Pen API Programmer's Reference (penapi.hlp)
Microsoft Windows Sockets 2 Reference (sock2.hlp)
Microsoft Windows Telephony API (TAPI) Programmer's Reference (sock2.hlp)
Unix Manual Pages

greatis just4fun network