Função LoadLibraryExA (libloaderapi.h)
Carrega o módulo especificado no espaço de endereço do processo de chamada. O módulo especificado pode fazer com que outros módulos sejam carregados.
Sintaxe
HMODULE LoadLibraryExA(
[in] LPCSTR lpLibFileName,
HANDLE hFile,
[in] DWORD dwFlags
);
Parâmetros
[in] lpLibFileName
Uma cadeia de caracteres que especifica o nome do arquivo do módulo a ser carregado. Esse nome não está relacionado ao nome armazenado em um módulo de biblioteca em si, conforme especificado pelo LIBRARY palavra-chave no arquivo de definição de módulo (.def).
O módulo pode ser um módulo de biblioteca (um arquivo .dll) ou um módulo executável (um arquivo .exe). Se o módulo especificado for um módulo executável, as importações estáticas não serão carregadas; em vez disso, o módulo é carregado como se DONT_RESOLVE_DLL_REFERENCES tivesse sido especificado. Consulte o parâmetro
Se a cadeia de caracteres especificar um nome de módulo sem um caminho e a extensão de nome de arquivo for omitida, a função acrescentará a extensão de biblioteca padrão ".DLL" ao nome do módulo. Para impedir que a função acrescente ".DLL" ao nome do módulo, inclua um caractere de ponto à direita (.) na cadeia de caracteres de nome do módulo.
Se a cadeia de caracteres especificar um caminho totalmente qualificado, a função pesquisa apenas esse caminho para o módulo. Ao especificar um caminho, use barras invertidas (\), não barras (/). Para obter mais informações sobre caminhos, consulte Arquivos de Nomenclatura, Caminhos e Namespaces.
Se a cadeia de caracteres especificar um nome de módulo sem um caminho e mais de um módulo carregado tiver o mesmo nome base e extensão, a função retornará um identificador para o módulo que foi carregado primeiro.
Se a cadeia de caracteres especificar um nome de módulo sem um caminho e um módulo com o mesmo nome ainda não estiver carregado ou se a cadeia de caracteres especificar um nome de módulo com um caminho relativo, a função procurará o módulo especificado. A função também pesquisa módulos se o carregamento do módulo especificado faz com que o sistema carregue outros módulos associados (ou seja, se o módulo tiver dependências). Os diretórios pesquisados e a ordem na qual são pesquisados dependem do caminho especificado e do parâmetro dwFlags
Se a função não conseguir localizar o módulo ou uma de suas dependências, a função falhará.
hFile
Esse parâmetro é reservado para uso futuro. Deve ser NULL.
[in] dwFlags
A ação a ser executada ao carregar o módulo. Se nenhum sinalizador for especificado, o comportamento dessa função será idêntico ao da função LoadLibrary. Esse parâmetro pode ser um dos valores a seguir.
| Valor | Significado |
|---|---|
|
Se esse valor for usado e o módulo executável for uma DLL, o sistema não chamará DllMain para inicialização e encerramento de processo e thread. Além disso, o sistema não carrega módulos executáveis adicionais referenciados pelo módulo especificado.
Observação Não use esse valor; ele é fornecido apenas para compatibilidade com versões anteriores. Se você estiver planejando acessar apenas dados ou recursos na DLL, use LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE ou LOAD_LIBRARY_AS_IMAGE_RESOURCE ou ambos. Caso contrário, carregue a biblioteca como uma DLL ou módulo executável usando a função LoadLibrary.
|
|
Se esse valor for usado, o sistema não verificará regras de do AppLocker ou aplicará políticas de restrição de software para a DLL. Essa ação se aplica apenas à DLL que está sendo carregada e não às suas dependências. Esse valor é recomendado para uso em programas de instalação que devem executar DLLs extraídas durante a instalação.
Windows Server 2008 R2 e Windows 7: Em sistemas com KB2532445 instalados, o chamador deve estar em execução como "LocalSystem" ou "TrustedInstaller"; caso contrário, o sistema ignorará esse sinalizador. Para obter mais informações, consulte "Você pode contornar as regras do AppLocker usando uma macro do Office em um computador que executa o Windows 7 ou o Windows Server 2008 R2" na Base de Dados de Conhecimento de Ajuda e Suporte em https://support.microsoft.com/kb/2532445. Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: AppLocker foi introduzido no Windows 7 e no Windows Server 2008 R2. |
|
Se esse valor for usado, o sistema mapeará o arquivo para o espaço de endereço virtual do processo de chamada como se fosse um arquivo de dados. Nada é feito para executar ou preparar para executar o arquivo mapeado. Portanto, você não pode chamar funções como GetModuleFileName, GetModuleHandle ou GetProcAddress com essa DLL. Usar esse valor faz com que as gravações na memória somente leitura gerem uma violação de acesso. Use esse sinalizador quando quiser carregar uma DLL apenas para extrair mensagens ou recursos dele.
Esse valor pode ser usado com LOAD_LIBRARY_AS_IMAGE_RESOURCE. Para obter mais informações, consulte Comentários. |
|
Semelhante a LOAD_LIBRARY_AS_DATAFILE, exceto que o arquivo DLL é aberto com acesso de gravação exclusivo para o processo de chamada. Outros processos não podem abrir o arquivo DLL para acesso de gravação enquanto ele estiver em uso. No entanto, a DLL ainda pode ser aberta por outros processos.
Esse valor pode ser usado com LOAD_LIBRARY_AS_IMAGE_RESOURCE. Para obter mais informações, consulte Comentários. Windows Server 2003 e Windows XP: Esse valor não tem suporte até o Windows Vista. |
|
Se esse valor for usado, o sistema mapeará o arquivo para o espaço de endereço virtual do processo como um arquivo de imagem.
No entanto, o carregador não carrega as importações estáticas nem executa as outras etapas habituais de inicialização. Use esse sinalizador quando quiser carregar uma DLL apenas para extrair mensagens ou recursos dele.
A menos que o aplicativo dependa do arquivo ter o layout na memória de uma imagem, esse valor deve ser usado com LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE ou LOAD_LIBRARY_AS_DATAFILE. Para obter mais informações, consulte a seção Comentários. Windows Server 2003 e Windows XP: Esse valor não tem suporte até o Windows Vista. |
|
Se esse valor for usado, o diretório de instalação do aplicativo será pesquisado para a DLL e suas dependências. Os diretórios no caminho de pesquisa padrão não são pesquisados. Esse valor não pode ser combinado com LOAD_WITH_ALTERED_SEARCH_PATH.
Windows 7, Windows Server 2008 R2, Windows Vista e Windows Server 2008: Esse valor requer que KB2533623 sejam instalados. Windows Server 2003 e Windows XP: Esse valor não tem suporte. |
|
Esse valor é uma combinação de LOAD_LIBRARY_SEARCH_APPLICATION_DIR, LOAD_LIBRARY_SEARCH_SYSTEM32e LOAD_LIBRARY_SEARCH_USER_DIRS. Os diretórios no caminho de pesquisa padrão não são pesquisados. Esse valor não pode ser combinado com LOAD_WITH_ALTERED_SEARCH_PATH.
Esse valor representa o número máximo recomendado de diretórios que um aplicativo deve incluir em seu caminho de pesquisa de DLL. Windows 7, Windows Server 2008 R2, Windows Vista e Windows Server 2008: Esse valor requer que KB2533623 sejam instalados. Windows Server 2003 e Windows XP: Esse valor não tem suporte. |
|
Se esse valor for usado, o diretório que contém a DLL será temporariamente adicionado ao início da lista de diretórios que são pesquisados para as dependências da DLL. Os diretórios no caminho de pesquisa padrão não são pesquisados.
O parâmetro lpFileName deve especificar um caminho totalmente qualificado. Esse valor não pode ser combinado com LOAD_WITH_ALTERED_SEARCH_PATH. Por exemplo, se Lib2.dll for uma dependência de C:\Dir1\Lib1.dll, loading Lib1.dll with this value causes the system to search for Lib2.dll somente em C:\Dir1. Para pesquisar Lib2.dll em C:\Dir1 e todos os diretórios no caminho de pesquisa da DLL, combine esse valor com LOAD_LIBRARY_SEARCH_DEFAULT_DIRS. Windows 7, Windows Server 2008 R2, Windows Vista e Windows Server 2008: Esse valor requer que KB2533623 sejam instalados. Windows Server 2003 e Windows XP: Esse valor não tem suporte. |
|
Se esse valor for usado, %windows%\system32 será pesquisado para a DLL e suas dependências.
Os diretórios no caminho de pesquisa padrão não são pesquisados. Esse valor não pode ser combinado com LOAD_WITH_ALTERED_SEARCH_PATH.
Windows 7, Windows Server 2008 R2, Windows Vista e Windows Server 2008: Esse valor requer que KB2533623 sejam instalados. Windows Server 2003 e Windows XP: Esse valor não tem suporte. |
|
Se esse valor for usado, os diretórios adicionados usando o Windows 7, Windows Server 2008 R2, Windows Vista e Windows Server 2008: Esse valor requer que KB2533623 sejam instalados. Windows Server 2003 e Windows XP: Esse valor não tem suporte. |
|
Se esse valor for usado e lpFileName especificar um caminho absoluto, o sistema usará a estratégia de pesquisa de arquivo alternativa discutida na seção Comentários para localizar módulos executáveis associados que o módulo especificado faz com que sejam carregados. Se esse valor for usado e lpFileName especificar um caminho relativo, o comportamento será indefinido.
Se esse valor não for usado ou se lpFileName não especificar um caminho, o sistema usará a estratégia de pesquisa padrão discutida na seção Comentários para localizar módulos executáveis associados que o módulo especificado faz com que sejam carregados. Esse valor não pode ser combinado com nenhum sinalizador de LOAD_LIBRARY_SEARCH. |
|
Especifica que a assinatura digital da imagem binária deve ser verificada no tempo de carregamento.
Esse valor requer Windows 8.1, Windows 10 ou posterior. |
|
Se esse valor for usado, o carregamento de uma DLL para execução do diretório atual só será permitido se ele estiver em um diretório na lista de carga segura. |
Valor de retorno
Se a função for bem-sucedida, o valor retornado será um identificador para o módulo carregado.
Se a função falhar, o valor retornado será NULL. Para obter informações de erro estendidas, chame GetLastError.
Observações
A função LoadLibraryEx é muito semelhante à função LoadLibrary. As diferenças consistem em um conjunto de comportamentos opcionais que LoadLibraryEx fornece:
- LoadLibraryEx pode carregar um módulo DLL sem chamar a função DllMain da DLL.
- LoadLibraryEx pode carregar um módulo de forma otimizada para o caso em que o módulo nunca será executado, carregando o módulo como se fosse um arquivo de dados.
- LoadLibraryEx pode encontrar módulos e seus módulos associados usando uma das duas estratégias de pesquisa ou pode pesquisar um conjunto de diretórios específico do processo.
O processo de chamada pode usar o identificador retornado pelo LoadLibraryEx para identificar o módulo em chamadas para as funções GetProcAddress, FindResourcee LoadResource.
Para habilitar ou desabilitar mensagens de erro exibidas pelo carregador durante as cargas de DLL, use a função
Não é seguro chamar LoadLibraryEx de DllMain. Para obter mais informações, consulte a seção Comentários no DllMain.
Visual C++: o compilador do Visual C++ dá suporte a uma sintaxe que permite declarar variáveis locais de thread: _declspec(thread). Se você usar essa sintaxe em uma DLL, não poderá carregar a DLL explicitamente usando LoadLibraryEx em versões do Windows antes do Windows Vista. Se a DLL for carregada explicitamente, você deverá usar as funções de armazenamento local do thread em vez de _declspec(thread). Para obter um exemplo, consulte Usando o Armazenamento Local de Thread em uma biblioteca de link dinâmico.
carregando uma DLL como um arquivo de dados ou recurso de imagem
Os valores LOAD_LIBRARY_AS_DATAFILE, LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVEe LOAD_LIBRARY_AS_IMAGE_RESOURCE afetam a contagem de referência por processo e o carregamento do módulo especificado. Se algum desses valores for especificado para o parâmetro dwFlags, o carregador verificará se o módulo já foi carregado pelo processo como uma DLL executável. Nesse caso, isso significa que o módulo já está mapeado para o espaço de endereço virtual do processo de chamada. Nesse caso, LoadLibraryEx retorna um identificador para a DLL e incrementa a contagem de referência de DLL. Se o módulo DLL ainda não foi carregado como uma DLL, o sistema mapeia o módulo como um arquivo de dados ou imagem e não como uma DLL executável. Nesse caso, LoadLibraryEx retorna um identificador para o arquivo de imagem ou dados carregados, mas não incrementa a contagem de referência para o módulo e não torna o módulo visível para funções como CreateToolhelp32Snapshot ou EnumProcessModules.Se LoadLibraryEx for chamado duas vezes para o mesmo arquivo com LOAD_LIBRARY_AS_DATAFILE, LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVEou LOAD_LIBRARY_AS_IMAGE_RESOURCE, dois mapeamentos separados serão criados para o arquivo.
Quando o valor LOAD_LIBRARY_AS_IMAGE_RESOURCE é usado, o módulo é carregado como uma imagem usando a expansão de alinhamento da seção PE (executável portátil). Endereços virtuais relativos (RVA) não precisam ser mapeados para endereços de disco, portanto, os recursos podem ser recuperados mais rapidamente do módulo. Especificar LOAD_LIBRARY_AS_IMAGE_RESOURCE impede que outros processos modifiquem o módulo enquanto ele é carregado.
A menos que um aplicativo dependa de características específicas de mapeamento de imagem, o valor LOAD_LIBRARY_AS_IMAGE_RESOURCE deve ser usado com LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE ou LOAD_LIBRARY_AS_DATAFILE. Isso permite que o carregador escolha se deseja carregar o módulo como um recurso de imagem ou um arquivo de dados, selecionando qualquer opção que permita que o sistema compartilhe páginas com mais eficiência. Funções de recurso como FindResource podem usar qualquer mapeamento.
Para determinar como um módulo foi carregado, use uma das macros a seguir para testar o identificador retornado por LoadLibraryEx.
#define LDR_IS_DATAFILE(handle) (((ULONG_PTR)(handle)) & (ULONG_PTR)1)
#define LDR_IS_IMAGEMAPPING(handle) (((ULONG_PTR)(handle)) & (ULONG_PTR)2)
#define LDR_IS_RESOURCE(handle) (LDR_IS_IMAGEMAPPING(handle) || LDR_IS_DATAFILE(handle))
A tabela a seguir descreve essas macros.
| Macro | Descrição |
|---|---|
| LDR_IS_DATAFILE( identificador de) | Se essa macro retornar TRUE, o módulo será carregado como um arquivo de dados (LOAD_LIBRARY_AS_DATAFILE ou LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE). |
| LDR_IS_IMAGEMAPPING( identificador de) | Se essa macro retornar TRUE, o módulo foi carregado como um arquivo de imagem (LOAD_LIBRARY_AS_IMAGE_RESOURCE). |
| LDR_IS_RESOURCE(identificador) | Se essa macro retornar VERDADEIRO, o módulo foi carregado como um arquivo de dados ou um arquivo de imagem. |
Use a função FreeLibrary para liberar um módulo carregado, independentemente de o módulo ter sido incrementado ou não. Se o módulo tiver sido carregado como um arquivo de dados ou imagem, o mapeamento será destruído, mas a contagem de referência não será decrementada. Caso contrário, a contagem de referência de DLL será decremente decremente. Portanto, é seguro chamar FreeLibrary com qualquer identificador retornado por LoadLibraryEx.
pesquisando DLLs e dependências
O caminho de pesquisa é o conjunto de diretórios que são pesquisados por uma DLL. A função LoadLibraryEx pode procurar uma DLL usando um caminho de pesquisa padrão ou um caminho de pesquisa alterado ou pode usar um caminho de pesquisa específico do processo estabelecido com as funções SetDefaultDllDirectories e AddDllDirectory. Para obter uma lista de diretórios e a ordem na qual eles são pesquisados, consulte Dynamic-Link Ordem de Pesquisa da Biblioteca.A função LoadLibraryEx usa o caminho de pesquisa padrão nos seguintes casos:
- O nome do arquivo é especificado sem um caminho e o nome do arquivo base não corresponde ao nome do arquivo base de um módulo carregado e nenhum dos sinalizadores de LOAD_LIBRARY_SEARCH são usados.
- Um caminho é especificado, mas LOAD_WITH_ALTERED_SEARCH_PATH não é usado.
- O aplicativo não especificou um caminho de pesquisa DLL padrão para o processo usando SetDefaultDllDirectories.
Se lpFileName especificar um caminho relativo, todo o caminho relativo será acrescentado a cada token no caminho de pesquisa da DLL. Para carregar um módulo de um caminho relativo sem pesquisar outro caminho, use GetFullPathName para obter um caminho não relacionado e chamar LoadLibraryEx com o caminho não relacionado. Se o módulo estiver sendo carregado como um arquivo de dados e o caminho relativo começar com "." ou "..", o caminho relativo será tratado como um caminho absoluto.
Se lpFileName especificar um caminho absoluto e dwFlags estiver definido como LOAD_WITH_ALTERED_SEARCH_PATH, LoadLibraryEx usará o caminho de pesquisa alterado. O comportamento é indefinido quando LOAD_WITH_ALTERED_SEARCH_PATH sinalizador é definido e lpFileName especifica um caminho relativo.
A função SetDllDirectory pode ser usada para modificar o caminho de pesquisa. Essa solução é melhor do que usar SetCurrentDirectory ou codificar o caminho completo para a DLL. No entanto, lembre-se de que o uso SetDllDirectory desabilita efetivamente o modo de pesquisa de DLL seguro enquanto o diretório especificado está no caminho de pesquisa e não é thread-safe. Se possível, é melhor usar AddDllDirectory para modificar um caminho de pesquisa de processo padrão. Para obter mais informações, consulte Dynamic-Linkda Ordem de Pesquisa da Biblioteca.
Um aplicativo pode especificar os diretórios para pesquisar uma única chamada
- O diretório que contém a DLL (LOAD_LIBRARY_SEARCH_DLL_LOAD_DIR). Esse diretório é pesquisado apenas para que as dependências da DLL sejam carregadas.
- O diretório do aplicativo (LOAD_LIBRARY_SEARCH_APPLICATION_DIR).
- Caminhos adicionados explicitamente ao caminho de pesquisa do aplicativo com a função
AddDllDirectory ( LOAD_LIBRARY_SEARCH_USER_DIRS ) ou a funçãoSetDllDirectory. Se mais de um caminho tiver sido adicionado, a ordem na qual os caminhos são pesquisados não será especificada. - O diretório System32 (LOAD_LIBRARY_SEARCH_SYSTEM32).
Windows 7, Windows Server 2008 R2, Windows Vista e Windows Server 2008: os sinalizadores LOAD_LIBRARY_SEARCH_ estão disponíveis em sistemas que KB2533623 instalados. Para determinar se os sinalizadores estão disponíveis, use GetProcAddress para obter o endereço da função AddDllDirectory, RemoveDllDirectoryou SetDefaultDllDirectories. Se GetProcAddress for bem-sucedido, os sinalizadores de LOAD_LIBRARY_SEARCH_ poderão ser usados com LoadLibraryEx.
Se o aplicativo tiver usado a função
Se um caminho for especificado e houver um arquivo de redirecionamento associado ao aplicativo, a função LoadLibraryEx pesquisa o módulo no diretório do aplicativo. Se o módulo existir no diretório do aplicativo, LoadLibraryEx ignorará a especificação do caminho e carregará o módulo do diretório do aplicativo. Se o módulo não existir no diretório do aplicativo, a função carregará o módulo do diretório especificado. Para obter mais informações, consulte de Redirecionamento da Biblioteca de Link Dinâmico.
Se você chamar LoadLibraryEx com o nome de um assembly sem uma especificação de caminho e o assembly estiver listado no manifesto compatível com o sistema, a chamada será redirecionada automaticamente para o assembly lado a lado.
Comentários de segurança
LOAD_LIBRARY_AS_DATAFILE não impede que outros processos modifiquem o módulo enquanto ele é carregado. Como isso pode tornar seu aplicativo menos seguro, você deve usar LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE em vez de LOAD_LIBRARY_AS_DATAFILE ao carregar um módulo como um arquivo de dados, a menos que você precise usar especificamente LOAD_LIBRARY_AS_DATAFILE. Especificar LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE impede que outros processos modifiquem o módulo enquanto ele é carregado. Não especifique LOAD_LIBRARY_AS_DATAFILE e LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE na mesma chamada.Não use a função
Não faça suposições sobre a versão do sistema operacional com base em uma chamada LoadLibraryEx que pesquisa uma DLL. Se o aplicativo estiver em execução em um ambiente em que a DLL não esteja legitimamente presente, mas uma versão mal-intencionada da DLL estiver no caminho de pesquisa, a versão mal-intencionada da DLL poderá ser carregada. Em vez disso, use as técnicas recomendadas descritas em Obtendo a versão do sistema.
Para obter uma discussão geral sobre problemas de segurança de DLL, consulte Dynamic-Linkde Segurança da Biblioteca.
Exemplos
O exemplo de código a seguir demonstra uma chamada para LoadLibraryExA.
//Load the FMAPI DLL
hLib = ::LoadLibraryEx(L"fmapi.dll", NULL, NULL);
if ( !hLib )
{
wprintf(L"Could not load fmapi.dll, Error #%d.\n", GetLastError());
return;
}
Para obter um exemplo adicional, consulte Pesquisa de texto para números de código de erro.
Nota
O cabeçalho libloaderapi.h define LoadLibraryEx como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows XP [somente aplicativos da área de trabalho] |
| servidor com suporte mínimo | Windows Server 2003 [somente aplicativos da área de trabalho] |
| da Plataforma de Destino |
Windows |
| cabeçalho | libloaderapi.h (inclua Windows.h) |
| biblioteca | Kernel32.lib |
| de DLL |
Kernel32.dll |
Consulte também
Funções da biblioteca Dynamic-Link
da ordem de pesquisa da biblioteca de
Dynamic-Link de Segurança da Biblioteca
Run-Time de Vinculação Dinâmica