Função SetDllDirectoryA (winbase.h)

Artigo
08/27/2023

Adiciona um diretório ao caminho de pesquisa usado para localizar DLLs para o aplicativo.

Sintaxe

BOOL SetDllDirectoryA(
  [in, optional] LPCSTR lpPathName
);

Parâmetros

[in, optional] lpPathName

O diretório a ser adicionado ao caminho de pesquisa. Se esse parâmetro for uma cadeia de caracteres vazia (""), a chamada removerá o diretório atual da ordem de pesquisa de DLL padrão. Se esse parâmetro for NULL, a função restaurará a ordem de pesquisa padrão.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Comentários

A função SetDllDirectory afeta todas as chamadas subsequentes para as funções LoadLibrary e LoadLibraryEx . Ele também desabilita efetivamente o modo de pesquisa de DLL seguro enquanto o diretório especificado está no caminho de pesquisa.

Observação

Para processos win32 que não estão executando um processo empacotado ou protegido, chamar essa função também afetará a ordem de pesquisa de DLL dos processos filhos iniciados a partir do processo que chamou a função.

Depois de chamar SetDllDirectory, o caminho de pesquisa de DLL padrão é:

O diretório do qual o aplicativo foi carregado.
O diretório especificado pelo parâmetro lpPathName .
O diretório do sistema. Use a função GetSystemDirectory para obter o caminho desse diretório. O nome desse diretório é System32.
O diretório do sistema de 16 bits. Não há nenhuma função que obtenha o caminho desse diretório, mas ela é pesquisada. O nome desse diretório é System.
O diretório do Windows. Use a função GetWindowsDirectory para obter o caminho desse diretório.
Os diretórios listados na variável de ambiente PATH.

Cada vez que a função SetDllDirectory é chamada, ela substitui o diretório especificado na chamada setDllDirectory anterior. Para especificar mais de um diretório, use a função AddDllDirectory e chame LoadLibraryEx com LOAD_LIBRARY_SEARCH_USER_DIRS.

Para reverter para o caminho de pesquisa padrão usado por LoadLibrary e LoadLibraryEx, chame SetDllDirectory com NULL. Isso também restaura o modo de pesquisa de DLL seguro com base no valor do registro SafeDllSearchMode .

Para compilar um aplicativo que usa essa função, defina _WIN32_WINNT como 0x0502 ou posterior. Para obter mais informações, consulte Usando os cabeçalhos do Windows.

Observação

O cabeçalho winbase.h define SetDllDirectory 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. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista, Windows XP com SP1 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	winbase.h (incluir Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll