| BOOL DllEntryPoint(hDll, dwReason, lpReserved) | |||
| HANDLE hDll; | |||
| DWORD dwReason; | |||
| LPVOID lpReserved; |
DllEntryPoint is an optional entry into a DLL which, if provided, will be called when processes and threads are initialized and terminated, or upon calls to LoadLibrary and FreeLibrary.
hDll
Supplies the DLL with a handle to the DLL. This handle may be used in subsequent calls to GetModuleFileName and other module functions.
dwReason
Supplies a flag word that indicates why the DLL entry routine is being called.
| Reason | Values |
| DLL_PROCESS_ATTACH | Indicates that the DLL is attaching to the address space of the current process. This is either as a result of the process starting up, or after a call to LoadLibrary. DLLs should use this as a hook to initialize any instance data or to allocate a TLS index. |
| During initial process startup, or after a call to LoadLibrary, the list of loaded DLLs for the process is scanned. For each DLL that has not already been called with a DLL_PROCESS_ATTACH flag, the DLL is called. It is important to note that this call is made in the context of the thread that caused the process address space to change. | |
| DLL_THREAD_ATTACH | Indicates that a new thread is being created in the current process. All DLLs attached to the process at the time the thread starts will be called. DLLs may use this hook to initialize a TLS slot for the thread. The thread that calls the DLL with the DLL_PROCESS_ATTACH flag will not call the DLL with the DLL_THREAD_ATTACH flag. |
| It is important to note that after a DLL is loaded with LoadLibrary, only threads created after the DLL is loaded will be called with this flag value. Win32 does not cause pre-existing threads to call the newly loaded DLL. | |
| DLL_THREAD_DETACH | Indicates that a thread is exiting cleanly and that if the DLL has stored any TLS data, it should use this hook to free the data. The exiting thread will call all currently loaded DLLs with this flag value. It is important to note that there are cases where a thread will call with this flag value even if it never called the DLL with the DLL_THREAD_ATTACH flag. This can happen in two situations: |
| The thread was the initial thread in the process in which case it called the DLL with the DLL_PROCESS_ATTACH message. | |
| The thread was already running when a LoadLibrary call was made. Since the thread was “pre-existing”, it never called the DLL as a result of the successful LoadLibrary. | |
| DLL_PROCESS_DETACH | Indicates that the calling process is detaching the DLL from its address space. This is either due to a clean process exit, or from a FreeLibrary call. The DLL should use this opportunity to return any TLS indexes allocated with TlsAlloc and to free any thread local data. When a DLL is detached from a process (as a result of process termination, or FreeLibrary), individual threads do not call the DLL_THREAD_DETACH flag. The only notification given to the DLL is the DLL_PROCESS_DETACH notification. DLLs should use this opportunity to clean up all per-thread resources for all threads attached and known to the DLL. |
lpReserved
Reserved; should be NULL.
The return value is used only when a dll is called with a flag value of DLL_PROCESS_ATTACH. All other calls to DllEntryPoint will ignore the return value.
| Return Value | Meaning |
| TRUE | A value of TRUE should be returned if DllEntryPoint was successful. |
| FALSE | FALSE should be returned if initialization failed. If DllEntryPoint was called as part of a call to LoadLibrary, LoadLibrary will fail. If DllEntryPoint was called during process initialization, the process will terminate with an error. |
DllEntryPoint is a placeholder for the library-supplied function name. The actual name must be specified on the linker command line with the “-entry” option.
TlsAlloc