Funkce Entry-Point knihovny Dynamic-Link

Knihovna DLL může volitelně zadat funkci vstupního bodu. Pokud je k dispozici, systém volá funkci vstupního bodu pokaždé, když proces nebo vlákno načte nebo uvolní knihovnu DLL. Dá se použít k provádění jednoduchých inicializačních a čisticích úloh. Může například nastavit místní úložiště vlákna při vytvoření nového vlákna a vyčistit ho při ukončení vlákna.

Pokud propojíte knihovnu DLL s knihovnou runtime jazyka C, může vám poskytnout funkci vstupního bodu a umožnit vám poskytnout samostatnou inicializační funkci. Další informace najdete v dokumentaci ke knihovně runtime.

Pokud poskytujete vlastní vstupní bod, podívejte se na funkci DllMain. Název DllMain je zástupný symbol pro uživatelem definovanou funkci. Je nutné zadat skutečný název, který použijete při sestavování knihovny DLL. Další informace najdete v dokumentaci, která je součástí vašich vývojových nástrojů.

Volání funkce Entry-Point

Systém volá funkci vstupního bodu vždy, když dojde k některé z následujících událostí:

• Proces načte knihovnu DLL. U procesů využívajících dynamické propojení za běhu načítání se knihovna DLL načte během inicializace procesu. Pro procesy používající propojení za běhu se knihovna DLL načte před LoadLibrary nebo LoadLibraryEx vrátí.
• Proces rozbalí knihovnu DLL. Knihovna DLL je uvolněna při ukončení procesu nebo volání FreeLibrary funkce a počet odkazů se změní na nulu. Pokud se proces ukončí v důsledku funkce TerminateProcess nebo TerminateThread, systém nevolá funkci vstupního bodu knihovny DLL.
• V procesu, který načetl knihovnu DLL, se vytvoří nové vlákno. Pomocí funkce DisableThreadLibraryCalls můžete zakázat oznámení při vytváření vláken.
• Vlákno procesu, který načetl knihovnu DLL, se obvykle ukončí, nepoužívá TerminateThread nebo TerminateProcess. Když proces uvolní knihovnu DLL, volá se funkce vstupního bodu pouze jednou pro celý proces, nikoli jednou pro každé existující vlákno procesu. Pomocí DisableThreadLibraryCalls zakázat oznámení při ukončení vláken.

Funkci vstupního bodu může volat pouze jedno vlákno najednou.

Systém volá funkci vstupního bodu v kontextu procesu nebo vlákna, které způsobily volání funkce. To umožňuje knihovně DLL použít funkci vstupního bodu pro přidělování paměti ve virtuálním adresním prostoru volajícího procesu nebo k otevření popisovačů přístupných pro proces. Funkce vstupního bodu může také přidělit paměť, která je privátní pro nové vlákno pomocí místního úložiště vlákna (TLS). Další informace o místním úložišti vlákna naleznete v tématu Thread Local Storage.

definice funkce Entry-Point

Funkce vstupního bodu knihovny DLL musí být deklarována pomocí konvence volání standardního volání. Pokud vstupní bod knihovny DLL není deklarován správně, knihovna DLL není načtena a systém zobrazí zprávu, že vstupní bod knihovny DLL musí být deklarován pomocí winAPI.

V těle funkce můžete zpracovat jakoukoli kombinaci následujících scénářů, ve kterých byl volána vstupní bod knihovny DLL:

• Proces načte knihovnu DLL (DLL_PROCESS_ATTACH).
• Aktuální proces vytvoří nové vlákno (DLL_THREAD_ATTACH).
• Vlákno se obvykle ukončí (DLL_THREAD_DETACH).
• Proces uvolní knihovnu DLL (DLL_PROCESS_DETACH).

Funkce vstupního bodu by měla provádět pouze jednoduché inicializační úlohy. Nesmí volat funkci LoadLibrary ani LoadLibraryEx (nebo funkci, která tyto funkce volá), protože to může vytvořit smyčky závislostí v pořadí načítání knihovny DLL. To může způsobit použití knihovny DLL před spuštěním inicializačního kódu systému. Podobně funkce vstupního bodu nesmí volat funkci FreeLibrary (nebo funkci, která volá FreeLibrary) během ukončení procesu, protože to může vést k použití knihovny DLL po spuštění kódu ukončení systému.

Vzhledem k tomu, že Kernel32.dll je zaručeno načtení do adresního prostoru procesu při volání funkce vstupního bodu, volání funkcí v Kernel32.dll nemá za následek použití knihovny DLL před spuštěním jeho inicializačního kódu. Funkce vstupního bodu proto může vytvářet objekty synchronizace , jako jsou kritické oddíly a mutexy, a používat protokol TLS, protože tyto funkce jsou umístěny v Kernel32.dll. Není bezpečné volat funkce registru, například proto, že jsou umístěny v Advapi32.dll.

Volání jiných funkcí může vést k problémům, které je obtížné diagnostikovat. Volání funkcí User, Shell a COM může například způsobit chyby narušení přístupu, protože některé funkce v jejich knihovnách DLL volají LoadLibrary načtení jiných systémových komponent. Volání těchto funkcí během ukončení může naopak způsobit chyby narušení přístupu, protože odpovídající komponenta již byla uvolněna nebo neinicializována.

Následující příklad ukazuje, jak strukturovat funkci vstupního bodu knihovny DLL.

BOOL WINAPI DllMain(
    HINSTANCE hinstDLL,  // handle to DLL module
    DWORD fdwReason,     // reason for calling function
    LPVOID lpReserved )  // reserved
{
    // Perform actions based on the reason for calling.
    switch( fdwReason ) 
    { 
        case DLL_PROCESS_ATTACH:
         // Initialize once for each new process.
         // Return FALSE to fail DLL load.
            break;

        case DLL_THREAD_ATTACH:
         // Do thread-specific initialization.
            break;

        case DLL_THREAD_DETACH:
         // Do thread-specific cleanup.
            break;

        case DLL_PROCESS_DETACH:
         // Perform any necessary cleanup.
            break;
    }
    return TRUE;  // Successful DLL_PROCESS_ATTACH.
}

návratová hodnota funkce Entry-Point

Pokud je volána vstupní funkce knihovny DLL, protože proces se načítá, vrátí funkce TRUE označující úspěch. U procesů využívajících propojení za běhu načítání vrátí hodnotu FALSE způsobí selhání inicializace procesu a proces se ukončí. U procesů využívajících propojení za běhu vrátí návratová hodnota FALSELoadLibrary nebo LoadLibraryEx funkce vrátit NULL, což značí selhání. (Systém okamžitě volá funkci vstupního bodu s DLL_PROCESS_DETACH a uvolní knihovnu DLL.) Návratová hodnota funkce vstupního bodu se ignoruje, když je funkce volána z jakéhokoli jiného důvodu.