C++ Syntax

BOOL WINAPI

DllMain(

HINSTANCE f_hInstance,

DWORD f_dwReason,

void* f_pDummy );

This procedure is called once when the plug-in is loaded from disk and once when it is discarded again. It is the standard entry point for any DLL.

Parameters

Instance

[HINSTANCE] Instance handle of the DLL. As this handle might be needed later, it should be stored in a global variable.

Reason

[DWORD] Supplies a flag indicating why the DLL entry routine is being called. This value can be one of the following values:

DLL_PROCESS_ATTACH

Indicates the DLL is attaching to the address space of the current process as a result of the process starting up or a call to LoadLibrary. DLLs can use this opportunity to initialize any instance data or to use the TlsAlloc function to allocate a thread local storage (TLS) index.

During initial process startup or after a call to LoadLibrary, the operating system scans the list of loaded DLLs for the process. For each DLL that has not already been called with a DLL_PROCESS_ATTACH flag, the system calls the DLL's entry-point function. This call is made in the context of the thread that caused the process address space to change, such as the primary thread of the process or the thread that called LoadLibrary.

DLL_THREAD_ATTACH

Indicates the current process is creating a new thread. When this occurs, the system calls the entry-point of all DLLs currently attached to the process. The call is made in the context of the new thread. DLLs can use this opportunity to initialize a TLS slot for the thread. The thread calling the DLL entry-point with the DLL_PROCESS_ATTACH flag does not call the DLL entry-point with the DLL_THREAD_ATTACH flag.

Note that a DLL's entry-point is called with this flag value only by threads created after the DLL is attached to the process. When a DLL is attached by LoadLibrary, existing threads do not call the entry-point of the newly loaded DLL.

DLL_THREAD_DETACH

Indicates a thread is exiting cleanly. If the DLL has stored a pointer to allocated memory in a TLS slot, it uses this opportunity to free the memory. The operating system calls the entry-point of all currently loaded DLLs with this flag value. The call is made in the context of the exiting thread. There are cases in which the entry-point is invoked for a terminating thread even if the DLL never attached to the thread. For example, the entry-point was never called with the DLL_THREAD_ATTACH flag in the context of the thread. This can occur in two situations:

- The thread was the initial thread in the process so the system called the entry-point with the DLL_PROCESS_ATTACH flag.

- The thread was already running when a LoadLibrary call was made, so the system never called the entry-point function for it.

DLL_PROCESS_DETACH

Indicates the DLL is detaching from the address space of the calling process. This results from either a clean process exit, or from a FreeLibrary call. The DLL can use this opportunity to call the TlsFree function to free any TLS indexes allocated by using TlsAlloc and to free any thread local data. When a DLL detaches from a process as a result of process termination, or FreeLibrary, the operating system does not call the DLL's entry-point with the DLL_THREAD_DETACH flag for the individual threads of the process. The only notification given to the DLL is the DLL_PROCESS_DETACH notification. DLLs can take this opportunity to clean up all resources for all threads attached and known to the DLL.

Dummy

[void*] Specifies further aspects of DLL initialization and cleanup. If Reason is DLL_PROCESS_ATTACH, Dummy is nullptr for dynamic loads, and not nullptr for static loads. If Reason is DLL_PROCESS_DETACH, Dummy is nullptr if DllMain has been called via FreeLibrary, and not nullptr if DllMain has been called during process termination.

Return Value

When the system calls the DllMain function with the DLL_PROCESS_ATTACH flag, the function returns TRUE if it succeeds or FALSE if the initialization fails. If the return value is FALSE when the DllMain was invoked because the process called the LoadLibrary function, LoadLibrary returns nullptr. If the return value is FALSE when the DllMain is called during process initialization, the process terminates with an error. To get extended error information, use the GetLastError function.

When the system calls the DllMain function with any flag other than DLL_PROCESS_ATTACH, the return value is ignored.

Comment

Although the Win32 documentation (as stated above) says this procedure is the right place to perform initialization tasks, plug-ins using the CAD6interface should not perform any task except storing the plug-in's instance handle here. Instead, all initialization should be performed inside the MKI_PlugInInit procedure. This will ensure that all data will be initialized for each instance of the application running.

For an example of DllMain, see the Basic Plug-In Code.