| 术语 | dllmain |
| 释义 | DllMain 语法： C++ BOOL WINAPI DllMain( __in HINSTANCE hinstDLL, __in DWORD fdwReason, __in LPVOID lpvReserved ); 回调函数的DllMain 对一个动态链接库(DLL)可选的切入点。当系统启动或终止一个进程或线程，它调用入口点函数为每个加载使用过程的第一个线程的DLL。该系统还调用入口点函数的时，装上或卸下使用LoadLibrary和FreeLibrary函数的DLL。 警告有什么您可以在一个DLL入口点的严重限制。为了提供更复杂的初始化，创造一个DLL初始化例程。您可以要求应用程序调用之前调用DLL中的任何其他程序的初始化例程。 参数 hinstDLL [in] 一个句柄，DLL模块。值是DLL的基址。一个DLL HINSTANCE是作为DLL的HMODULE相同，因此hinstDLL可以在函数调用中要求模块句柄。 fdwReason [in] 原因代码说明了为什么该DLL入口点函数被调用。此参数可以是下列值之一。 ValueMeaning DLL_PROCESS_ATTACH 1The DLL被加载到了作为启动过程的结果当前进程的虚拟地址空间，或作为一个调用的结果给LoadLibrary。 DLL可以利用这个机会来初始化的任何实例数据或使用TlsAlloc函数分配一个线程本地存储(TLS)的索引。 在lpReserved参数指示是否正在加载的DLL静态或动态。 DLL_PROCESS_DETACH的 0The被卸载DLL是从调用进程的虚拟地址空间，因为它是加载失败或引用计数达到零(进程已终止或要求FreeLibrary一个每次调用LoadLibrary时间)。 在lpReserved参数指示DLL是否被作为一个FreeLibrary调用，一个没有装载，或进程的终止而卸下。 DLL可以利用这个机会来调用TlsFree函数来释放任何TLS通过使用TlsAlloc分配指标，并释放任何线程本地数据。 请注意，线程接收DLL_PROCESS_DETACH的通知不一定是相同的线程收到DLL_PROCESS_ATTACH通知。 DLL_THREAD_ATTACH 2The当前进程创建一个新线程。如果发生这种情况，系统调用入口点目前连接到该进程的所有DLL的功能。上述呼吁是在新线程的上下文。 DLL可以利用这个机会来初始化一个线程的TLS的插槽。一个线程调用DLL入口点的DLL_PROCESS_ATTACH函数不调用DLL入口点的DLL_THREAD_ATTACH功能。 请注意，DLL的入口点函数调用创建的线程，只有用此值后，该DLL的进程加载。当一个DLL被加载使用LoadLibrary，现有的线程不调用入口点函数的新加载的DLL。 DLL_THREAD_DETACH 3A条线程退出干净。如果DLL存储在TLS的插槽的指针分配的内存，它应该利用这个机会释放内存。该系统调用入口点对所有与此当前加载的DLL函数值。该调用在退出线程的上下文。 lpvReserved [in] 如果fdwReason是DLL_PROCESS_ATTACH，lpvReserved是动态负载和非NULL的静态负载空。 如果fdwReason是DLL_PROCESS_DETACH的，lpvReserved为NULL，如果FreeLibrary被称为或DLL加载失败，非空，如果该进程终止。 返回值 当系统调用的价值与DLL_PROCESS_ATTACH DllMain函数，该函数返回TRUE，如果它成功或FALSE，如果初始化失败。如果返回值为FALSE时，DllMain中调用，因为该进程使用LoadLibrary函数，调用LoadLibrary返回NULL。 (系统立即调用您的入口点与DLL_PROCESS_DETACH的和卸载DLL函数。如果返回值为FALSE时的DllMain进程初始化过程中调用)，该进程终止了一个错误。为了获得更多错误信息，调用GetLastError。 当系统调用的任何值比其他DLL_PROCESS_ATTACH DllMain函数，返回值将被忽略。 备注 DllMain中是一个库占位符定义函数的名称。您必须指定实际的名称使用当您生成的DLL。有关详细信息，请参阅您的文档的开发工具中。 在初始启动过程中或之后调用LoadLibrary，系统会扫描的过程中加载的DLL列表。对于每个尚未已经与DLL_PROCESS_ATTACH值调用DLL时，系统调用DLL的入口点函数。这一呼吁是在线程导致进程地址空间的变化，例如进程的主线程或调用LoadLibrary的线程方面。进入入口点是由序列上的进程范围的基础制度。在DllMain线程举行加载器锁因此不需要进行额外的DLL可以动态加载或初始化。 如果DLL的入口点函数返回FALSE DLL_PROCESS_ATTACH通知后，它收到一个DLL_PROCESS_DETACH的通知和卸载DLL是立即。但是，如果DLL_PROCESS_ATTACH代码抛出一个异常，在入口点函数将不会收到DLL_PROCESS_DETACH的通知。 目前在该入口点函数是即使入口点函数是从未DLL_THREAD_ATTACH要求线程终止线程调用的案件： 该主题是在过程中的初始线程，因此，所谓的入职制度与DLL_PROCESS_ATTACH值点的功能。 该线程运行时已经向LoadLibrary函数调用了，因此系统从不调用入口点它的功能。 当一个DLL是从作为一个DLL的，该进程的终止，或对FreeLibrary调用失败的结果的过程装载卸载，系统不会调用DLL的入口点与个别线程DLL_THREAD_DETACH值函数这一进程。该DLL只发送1 DLL_PROCESS_DETACH的通知。 DLL可以借此机会，清理已知的DLL的所有线程的所有资源。 在处理DLL_PROCESS_DETACH的，一个DLL应该如堆内存免费资源只有在被卸载DLL是动态(即lpReserved参数为NULL)。如果这一进程终止(即lpvReserved参数非空)，在当前线程除外进程的所有线程可能已退出已经或已明确向ExitProcess函数，这可能使一些如堆过程中资源的呼吁终止在不一致的状态。在这种情况下，它是不安全的DLL清理资源。相反，DLL应允许操作系统回收内存。 如果您终止通过调用TerminateProcess或TerminateJobObject，这一进程的DLL不接受DLL_PROCESS_DETACH的通知的过程。如果您通过调用TerminateThread终止一个线程，该线程的DLL没有收到DLL_THREAD_DETACH通知。 在入口点函数只应执行简单的初始化或终止任务。它不能调用LoadLibrary或LoadLibraryEx函数(或一个函数，调用这些函数)，因为这可能会创建在DLL加载顺序依赖循环。这可能导致一个DLL被系统使用之前已经执行它的初始化代码。同样，在入口点函数不能调用FreeLibrary函数(或函数调用FreeLibrary在进程终止)，因为这可能导致在DLL中使用该系统后，终止执行的代码。 由于Kernel32.dll中保证是加载到进程地址时，入口点函数被调用的空间，在Kernel32.dll中调用函数不会导致使用该DLL初始化代码之前，已被处决。因此，入口点函数可以调用的函数在Kernel32.dll中不加载其他DLL。例如，可以创造这样的DllMain的关键路段和互斥同步对象，并使用TLS。不幸的是，不是在Kernel32.dll中的安全功能的全面清单。 Windows 2000的：不要在DllMain创建一个名为同步对象，因为该系统将加载一个额外的DLL。 调用函数所需要的DLL以外的Kernel32.dll可能会导致问题，这些问题难以诊断。例如，调用用户，壳牌，和COM的功能可能会导致访问冲突错误，因为有些功能加载其他系统组件。相反，像这样的通话功能，在终止可能会导致访问冲突错误，因为相应的组件可能已被卸载或初始化。 因为DLL文件通知被序列化，入口点功能，不应尝试与其他线程或进程。死锁可能发生的结果。 有关在写作时尽量一个DLL做法的信息，请参阅http://www.microsoft.com/whdc/driver/kernel/DLL_bestprac.mspx。 如果您的DLL与C运行时库(CRT)的联系，在入口点的CRT提供调用构造函数和全球性和静态C + +对象的析构函数。因此，DllMain中，这些限制也适用于构造函数和析和任何从他们称为码。 实例 有关示例，请参见动态链接库的入口点函数。 要求： 最低支持：client－Windows 2000专业版 最低支持server－Windows 2000服务器 参见 动态链接库的入口点函数 动态链接库函数 FreeLibrary GetModuleFileName 调用LoadLibrary 对TlsAlloc TlsFree 如果有任何问题和意见，请发送给微软(wsddocfb@microsoft.com) 生成日期：2009年8月27日 ＝＝英文原文＝＝DllMain Callback Function An optional entry point into a dynamic-link library (DLL). When the system starts or terminates a process or thread, it calls the entry-point function for each loaded DLL using the first thread of the process. The system also calls the entry-point function for a DLL when it is loaded or unloaded using the LoadLibrary and FreeLibrary functions. Warning There are serious limits on what you can do in a DLL entry point. To provide more complex initialization, create an initialization routine for the DLL. You can require applications to call the initialization routine before calling any other routines in the DLL. Syntax C++ BOOL WINAPI DllMain( __in HINSTANCE hinstDLL, __in DWORD fdwReason, __in LPVOID lpvReserved ); Parameters hinstDLL [in] A handle to the DLL module. The value is the base address of the DLL. The HINSTANCE of a DLL is the same as the HMODULE of the DLL, so hinstDLL can be used in calls to functions that require a module handle. fdwReason [in] The reason code that indicates why the DLL entry-point function is being called. This parameter can be one of the following values. ValueMeaning DLL_PROCESS_ATTACH 1The DLL is being loaded into the virtual address space of the current process as a result of the process starting up or as a result of 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. The lpReserved parameter indicates whether the DLL is being loaded statically or dynamically. DLL_PROCESS_DETACH 0The DLL is being unloaded from the virtual address space of the calling process because it was loaded unsuccessfully or the reference count has reached zero (the processes has either terminated or called FreeLibrary one time for each time it called LoadLibrary). The lpReserved parameter indicates whether the DLL is being unloaded as a result of a FreeLibrary call, a failure to load, or process termination. The DLL can use this opportunity to call the TlsFree function to free any TLS indices allocated by using TlsAlloc and to free any thread local data. Note that the thread that receives the DLL_PROCESS_DETACH notification is not necessarily the same thread that received the DLL_PROCESS_ATTACH notification. DLL_THREAD_ATTACH 2The current process is creating a new thread. When this occurs, the system calls the entry-point function 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. A thread calling the DLL entry-point function with DLL_PROCESS_ATTACH does not call the DLL entry-point function with DLL_THREAD_ATTACH. Note that a DLL's entry-point function is called with this value only by threads created after the DLL is loaded by the process. When a DLL is loaded using LoadLibrary, existing threads do not call the entry-point function of the newly loaded DLL. DLL_THREAD_DETACH 3A thread is exiting cleanly. If the DLL has stored a pointer to allocated memory in a TLS slot, it should use this opportunity to free the memory. The system calls the entry-point function of all currently loaded DLLs with this value. The call is made in the context of the exiting thread. lpvReserved [in] If fdwReason is DLL_PROCESS_ATTACH, lpvReserved is NULL for dynamic loads and non-NULL for static loads. If fdwReason is DLL_PROCESS_DETACH, lpvReserved is NULL if FreeLibrary has been called or the DLL load failed and non-NULL if the process is terminating. Return Value When the system calls the DllMain function with the DLL_PROCESS_ATTACH value, the function returns TRUE if it succeeds or FALSE if initialization fails. If the return value is FALSE when DllMain is called because the process uses the LoadLibrary function, LoadLibrary returns NULL. (The system immediately calls your entry-point function with DLL_PROCESS_DETACH and unloads the DLL.) If the return value is FALSE when DllMain is called during process initialization, the process terminates with an error. To get extended error information, call GetLastError . When the system calls the DllMain function with any value other than DLL_PROCESS_ATTACH, the return value is ignored. Remarks DllMain is a placeholder for the library-defined function name. You must specify the actual name you use when you build your DLL. For more information, see the documentation included with your development tools. During initial process startup or after a call to LoadLibrary, the system scans the list of loaded DLLs for the process. For each DLL that has not already been called with the DLL_PROCESS_ATTACH value, 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. Access to the entry point is serialized by the system on a process-wide basis. Threads in DllMain hold the loader lock so no additional DLLs can be dynamically loaded or initialized. If the DLL's entry-point function returns FALSE following a DLL_PROCESS_ATTACH notification, it receives a DLL_PROCESS_DETACH notification and the DLL is unloaded immediately. However, if the DLL_PROCESS_ATTACH code throws an exception, the entry-point function will not receive the DLL_PROCESS_DETACH notification. There are cases in which the entry-point function is called for a terminating thread even if the entry-point function was never called with DLL_THREAD_ATTACH for the thread: The thread was the initial thread in the process, so the system called the entry-point function with the DLL_PROCESS_ATTACH value. The thread was already running when a call to the LoadLibrary function was made, so the system never called the entry-point function for it. When a DLL is unloaded from a process as a result of an unsuccessful load of the DLL, termination of the process, or a call to FreeLibrary , the system does not call the DLL's entry-point function with the DLL_THREAD_DETACH value for the individual threads of the process. The DLL is only sent a DLL_PROCESS_DETACH notification. DLLs can take this opportunity to clean up all resources for all threads known to the DLL. When handling DLL_PROCESS_DETACH, a DLL should free resources such as heap memory only if the DLL is being unloaded dynamically (the lpReserved parameter is NULL). If the process is terminating (the lpvReserved parameter is non-NULL), all threads in the process except the current thread either have exited already or have been explicitly terminated by a call to the ExitProcess function, which might leave some process resources such as heaps in an inconsistent state. In this case, it is not safe for the DLL to clean up the resources. Instead, the DLL should allow the operating system to reclaim the memory. If you terminate a process by calling TerminateProcess or TerminateJobObject , the DLLs of that process do not receive DLL_PROCESS_DETACH notifications. If you terminate a thread by calling TerminateThread , the DLLs of that thread do not receive DLL_THREAD_DETACH notifications. The entry-point function should perform only simple initialization or termination tasks. It must not call the LoadLibrary or LoadLibraryEx function (or a function that calls these functions), because this may create dependency loops in the DLL load order. This can result in a DLL being used before the system has executed its initialization code. Similarly, the entry-point function must not call the FreeLibrary function (or a function that calls FreeLibrary) during process termination, because this can result in a DLL being used after the system has executed its termination code. Because Kernel32.dll is guaranteed to be loaded in the process address space when the entry-point function is called, calling functions in Kernel32.dll does not result in the DLL being used before its initialization code has been executed. Therefore, the entry-point function can call functions in Kernel32.dll that do not load other DLLs. For example, DllMain can create synchronization objects such as critical sections and mutexes, and use TLS. Unfortunately, there is not a comprehensive list of safe functions in Kernel32.dll. Windows 2000: Do not create a named synchronization object in DllMain because the system will then load an additional DLL. Calling functions that require DLLs other than Kernel32.dll may result in problems that are difficult to diagnose. For example, calling User, Shell, and COM functions can cause access violation errors, because some functions load other system components. Conversely, calling functions such as these during termination can cause access violation errors because the corresponding component may already have been unloaded or uninitialized. Because DLL notifications are serialized, entry-point functions should not attempt to communicate with other threads or processes. Deadlocks may occur as a result. For information on best practices when writing a DLL, see http://www.microsoft.com/whdc/driver/kernel/DLL_bestprac.mspx . If your DLL is linked with the C run-time library (CRT), the entry point provided by the CRT calls the constructors and destructors for global and static C++ objects. Therefore, these restrictions for DllMain also apply to constructors and destructors and any code that is called from them. Examples For an example, see Dynamic-Link Library Entry-Point Function . Requirements Minimum supported clientWindows 2000 Professional Minimum supported serverWindows 2000 Server See Also Dynamic-Link Library Entry-Point Function Dynamic-Link Library Functions FreeLibrary GetModuleFileName LoadLibrary TlsAlloc TlsFree Send comments about this topic to Microsoft Build date: 8/27/2009 ＝＝原始网址＝＝http://msdn.microsoft.com/en-us/library/ms682583(VS.85).aspx\n |
| 随便看 |
|
windows api函数参考手册包含2258条windows api函数文档，详细介绍nodejs、java、rust调用windows api的方法技巧，是学习windows api编程的入门中文文档。